Deprecate returning to dock in Husqvarna Automower (#130649)

homeassistant/components/husqvarna_automower/binary_sensor.py

@@ -3,24 +3,42 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 import logging
+from typing import TYPE_CHECKING
 
 from aioautomower.model import MowerActivities, MowerAttributes
 
+from homeassistant.components.automation import automations_with_entity
 from homeassistant.components.binary_sensor import (
+    DOMAIN as BINARY_SENSOR_DOMAIN,
     BinarySensorDeviceClass,
     BinarySensorEntity,
     BinarySensorEntityDescription,
 )
+from homeassistant.components.script import scripts_with_entity
 from homeassistant.core import HomeAssistant
+from homeassistant.helpers import entity_registry as er
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.issue_registry import (
+    IssueSeverity,
+    async_create_issue,
+    async_delete_issue,
+)
 
 from . import AutomowerConfigEntry
+from .const import DOMAIN
 from .coordinator import AutomowerDataUpdateCoordinator
 from .entity import AutomowerBaseEntity
 
 _LOGGER = logging.getLogger(__name__)
 
 
+def entity_used_in(hass: HomeAssistant, entity_id: str) -> list[str]:
+    """Get list of related automations and scripts."""
+    used_in = automations_with_entity(hass, entity_id)
+    used_in += scripts_with_entity(hass, entity_id)
+    return used_in
+
+
 @dataclass(frozen=True, kw_only=True)
 class AutomowerBinarySensorEntityDescription(BinarySensorEntityDescription):
     """Describes Automower binary sensor entity."""
@@ -43,6 +61,7 @@ MOWER_BINARY_SENSOR_TYPES: tuple[AutomowerBinarySensorEntityDescription, ...] =
         key="returning_to_dock",
         translation_key="returning_to_dock",
         value_fn=lambda data: data.mower.activity == MowerActivities.GOING_HOME,
+        entity_registry_enabled_default=False,
     ),
 )
 
@@ -81,3 +100,39 @@ class AutomowerBinarySensorEntity(AutomowerBaseEntity, BinarySensorEntity):
     def is_on(self) -> bool:
         """Return the state of the binary sensor."""
         return self.entity_description.value_fn(self.mower_attributes)
+
+    async def async_added_to_hass(self) -> None:
+        """Raise issue when entity is registered and was not disabled."""
+        if TYPE_CHECKING:
+            assert self.unique_id
+        if not (
+            entity_id := er.async_get(self.hass).async_get_entity_id(
+                BINARY_SENSOR_DOMAIN, DOMAIN, self.unique_id
+            )
+        ):
+            return
+        if (
+            self.enabled
+            and self.entity_description.key == "returning_to_dock"
+            and entity_used_in(self.hass, entity_id)
+        ):
+            async_create_issue(
+                self.hass,
+                DOMAIN,
+                f"deprecated_entity_{self.entity_description.key}",
+                breaks_in_ha_version="2025.6.0",
+                is_fixable=False,
+                severity=IssueSeverity.WARNING,
+                translation_key="deprecated_entity",
+                translation_placeholders={
+                    "entity_name": str(self.name),
+                    "entity": entity_id,
+                },
+            )
+        else:
+            async_delete_issue(
+                self.hass,
+                DOMAIN,
+                f"deprecated_task_entity_{self.entity_description.key}",
+            )
+        await super().async_added_to_hass()

homeassistant/components/husqvarna_automower/strings.json

@@ -311,6 +311,12 @@
       }
     }
   },
+  "issues": {
+    "deprecated_entity": {
+      "title": "The Husqvarna Automower {entity_name} sensor is deprecated",
+      "description": "The Husqavarna Automower entity `{entity}` is deprecated and will be removed in a future release.\nYou can use the new returning state of the lawn mower entity instead.\nPlease update your automations and scripts to replace the sensor entity with the newly added todo entity.\nWhen you are done migrating you can disable `{entity}`."
+    }
+  },
   "services": {
     "override_schedule": {
       "name": "Override schedule",

tests/components/husqvarna_automower/test_binary_sensor.py

@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, patch
 
 from aioautomower.model import MowerActivities, MowerAttributes
 from freezegun.api import FrozenDateTimeFactory
+import pytest
 from syrupy import SnapshotAssertion
 
 from homeassistant.components.husqvarna_automower.coordinator import SCAN_INTERVAL
@@ -17,6 +18,7 @@ from .const import TEST_MOWER_ID
 from tests.common import MockConfigEntry, async_fire_time_changed, snapshot_platform
 
 
+@pytest.mark.usefixtures("entity_registry_enabled_by_default")
 async def test_binary_sensor_states(
     hass: HomeAssistant,
     mock_automower_client: AsyncMock,
@@ -50,6 +52,7 @@ async def test_binary_sensor_states(
         assert state.state == "on"
 
 
+@pytest.mark.usefixtures("entity_registry_enabled_by_default")
 async def test_binary_sensor_snapshot(
     hass: HomeAssistant,
     entity_registry: er.EntityRegistry,