zigpy 1.2.2__tar.gz → 1.4.0__tar.gz

{zigpy-1.2.2/zigpy.egg-info → zigpy-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zigpy
-Version: 1.2.2
+Version: 1.4.0
 Summary: Library implementing a Zigbee stack
 Author-email: Russell Cloran <rcloran@gmail.com>
 License: GPL-3.0
@@ -16,7 +16,7 @@ Requires-Dist: crccheck
 Requires-Dist: cryptography
 Requires-Dist: voluptuous
 Requires-Dist: jsonschema
-Requires-Dist: pyserial-asyncio-fast
+Requires-Dist: serialx>=1.4.0
 Requires-Dist: typing_extensions
 Requires-Dist: frozendict
 Dynamic: license-file

{zigpy-1.2.2 → zigpy-1.4.0}/pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
     "cryptography",
     "voluptuous",
     "jsonschema",
-    'pyserial-asyncio-fast',
+    "serialx>=1.4.0",
     "typing_extensions",
     "frozendict",
 ]

{zigpy-1.2.2 → zigpy-1.4.0}/tests/test_application.py

@@ -12,6 +12,8 @@ import pytest
 import zigpy.application
 import zigpy.config as conf
 from zigpy.datastructures import RequestLimiter
+import zigpy.device
+import zigpy.endpoint
 from zigpy.exceptions import (
     DeliveryError,
     NetworkNotFormed,
@@ -1862,3 +1864,202 @@ async def test_callback_wrapping_async(
             ),
         ),
     ]
+
+
+async def test_device_reinterviewed_with_db(app):
+    """Test _device_reinterviewed removes old device from DB before saving new one."""
+
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+
+    old_dev = app.add_device(ieee=ieee, nwk=nwk)
+    old_dev.node_desc = make_node_desc()
+
+    # Set up a mock DB listener
+    db_listener = MagicMock()
+    db_listener._remove_device = AsyncMock()
+    app._dblistener = db_listener
+    old_dev.add_context_listener(db_listener)
+
+    shadow = zigpy.device.Device(app, ieee, nwk)
+    shadow.node_desc = make_node_desc()
+    shadow.status = zigpy.device.Status.ENDPOINTS_INIT
+    ep = shadow.add_endpoint(1)
+    ep.profile_id = 260
+    ep.device_type = 0x0100
+    ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    await app._device_reinterviewed(old_dev, shadow)
+
+    # DB removal should have been called for the old device
+    db_listener._remove_device.assert_awaited_once_with(old_dev)
+
+
+async def test_reinterview_device_public_api(app):
+    """Test reinterview_device delegates to dev.reinterview()."""
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+    dev = app.add_device(ieee=ieee, nwk=nwk)
+    dev.reinterview = AsyncMock()
+
+    await app.reinterview_device(ieee)
+
+    dev.reinterview.assert_awaited_once()
+
+
+async def test_reinterview_device_not_found(app):
+    """Test reinterview_device raises KeyError for unknown device."""
+    with pytest.raises(KeyError):
+        await app.reinterview_device(make_ieee(99))
+
+
+async def test_device_reinterviewed_preserves_groups(app):
+    """Test _device_reinterviewed migrates group memberships to the new device."""
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+
+    old_dev = app.add_device(ieee=ieee, nwk=nwk)
+    old_dev.node_desc = make_node_desc()
+    old_ep = old_dev.add_endpoint(1)
+    old_ep.profile_id = 260
+    old_ep.device_type = 0x0100
+    old_ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    # Add old endpoint to groups
+    group_10 = app.groups.add_group(10, "Group 10")
+    group_20 = app.groups.add_group(20, "Group 20")
+    group_10.add_member(old_ep, suppress_event=True)
+    group_20.add_member(old_ep, suppress_event=True)
+    assert old_ep.unique_id in group_10
+    assert old_ep.unique_id in group_20
+
+    # Create shadow with matching endpoint
+    shadow = zigpy.device.Device(app, ieee, nwk)
+    shadow.node_desc = make_node_desc()
+    shadow.status = zigpy.device.Status.ENDPOINTS_INIT
+    new_ep = shadow.add_endpoint(1)
+    new_ep.profile_id = 260
+    new_ep.device_type = 0x0100
+    new_ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    await app._device_reinterviewed(old_dev, shadow)
+
+    new_dev = app.devices[ieee]
+    new_ep = new_dev.endpoints[1]
+
+    # Group members should point to new endpoint objects, not old ones
+    assert group_10[new_ep.unique_id] is new_ep
+    assert group_10[new_ep.unique_id] is not old_ep
+    assert group_20[new_ep.unique_id] is new_ep
+    assert group_20[new_ep.unique_id] is not old_ep
+
+    # New endpoint should know about its group memberships
+    assert 10 in new_ep.member_of
+    assert 20 in new_ep.member_of
+
+    # Old endpoint should no longer be a member
+    assert not old_ep.member_of
+
+
+async def test_device_reinterviewed_skips_group_removed_during_swap(app):
+    """If a group is removed while `_remove_device` is awaiting, restoration skips it
+    instead of raising and aborting the reinterview.
+    """
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+
+    old_dev = app.add_device(ieee=ieee, nwk=nwk)
+    old_dev.node_desc = make_node_desc()
+    old_ep = old_dev.add_endpoint(1)
+    old_ep.profile_id = 260
+    old_ep.device_type = 0x0100
+    old_ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    surviving = app.groups.add_group(10, "Group 10")
+    doomed = app.groups.add_group(20, "Group 20")
+    surviving.add_member(old_ep, suppress_event=True)
+    doomed.add_member(old_ep, suppress_event=True)
+
+    # Simulate the race: between `_remove_device` returning and group restoration
+    # running, group 20 is removed. We trigger this by patching the dblistener's
+    # `_remove_device` to drop the group as a side effect.
+    db_listener = MagicMock()
+
+    async def fake_remove(_dev):
+        app.groups.pop(20, None)
+
+    db_listener._remove_device = AsyncMock(side_effect=fake_remove)
+    app._dblistener = db_listener
+    old_dev.add_context_listener(db_listener)
+
+    shadow = zigpy.device.Device(app, ieee, nwk)
+    shadow.node_desc = make_node_desc()
+    shadow.status = zigpy.device.Status.ENDPOINTS_INIT
+    new_ep = shadow.add_endpoint(1)
+    new_ep.profile_id = 260
+    new_ep.device_type = 0x0100
+    new_ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    await app._device_reinterviewed(old_dev, shadow)
+
+    new_dev = app.devices[ieee]
+    new_ep = new_dev.endpoints[1]
+
+    # Surviving group has the new endpoint; doomed group is gone, no KeyError raised.
+    assert new_ep.unique_id in surviving
+    assert 20 not in app.groups
+    app.listener_event.assert_any_call("device_reinterviewed", new_dev)
+
+
+async def test_device_reinterviewed_finalization_failure_propagates(app):
+    """Test that _device_reinterviewed lets exceptions propagate to reinterview()."""
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+
+    old_dev = app.add_device(ieee=ieee, nwk=nwk)
+    old_dev.node_desc = make_node_desc()
+    old_dev.model = "OldModel"
+
+    shadow = zigpy.device.Device(app, ieee, nwk)
+    shadow.node_desc = make_node_desc()
+    shadow.status = zigpy.device.Status.ENDPOINTS_INIT
+
+    # Make _finalize_device fail
+    app._finalize_device = Mock(side_effect=RuntimeError("finalization boom"))
+
+    # Exception should propagate — reinterview() is responsible for restoration
+    with pytest.raises(RuntimeError, match="finalization boom"):
+        await app._device_reinterviewed(old_dev, shadow)
+
+
+async def test_device_reinterviewed_persists_relays(app):
+    """Test that relays are re-persisted after reinterview."""
+    ieee = make_ieee()
+    nwk = t.NWK(0x1234)
+
+    old_dev = app.add_device(ieee=ieee, nwk=nwk)
+    old_dev.node_desc = make_node_desc()
+    old_dev._relays = t.Relays([t.NWK(0xAAAA)])
+
+    db_listener = MagicMock()
+    db_listener._remove_device = AsyncMock()
+    app._dblistener = db_listener
+    old_dev.add_context_listener(db_listener)
+
+    shadow = zigpy.device.Device(app, ieee, nwk)
+    shadow.node_desc = make_node_desc()
+    shadow.status = zigpy.device.Status.ENDPOINTS_INIT
+    ep = shadow.add_endpoint(1)
+    ep.profile_id = 260
+    ep.device_type = 0x0100
+    ep.status = zigpy.endpoint.Status.ZDO_INIT
+
+    await app._device_reinterviewed(old_dev, shadow)
+
+    new_dev = app.devices[ieee]
+
+    # Relays should have been copied and re-persisted
+    assert new_dev._relays == t.Relays([t.NWK(0xAAAA)])
+    db_listener.device_relays_updated.assert_called_once_with(
+        new_dev, t.Relays([t.NWK(0xAAAA)])
+    )

{zigpy-1.2.2 → zigpy-1.4.0}/tests/test_device.py

@@ -547,6 +547,7 @@ async def test_update_device_firmware(monkeypatch, dev, caplog):
     monkeypatch.setattr(endpoint.Endpoint, "initialize", mockepinit)
     monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info)
     dev.zdo.Active_EP_req = mockrequest
+    dev.reinterview = AsyncMock()  # prevent post-OTA reinterview side effects
 
     with mock_attribute_reads(cluster, {"current_file_version": 0x00000001}):
         await dev.initialize()
@@ -970,6 +971,7 @@ async def test_update_legrand_device_firmware(monkeypatch, dev, caplog):
     monkeypatch.setattr(endpoint.Endpoint, "initialize", mockepinit)
     monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info)
     dev.zdo.Active_EP_req = mockrequest
+    dev.reinterview = AsyncMock()  # prevent post-OTA reinterview side effects
 
     with mock_attribute_reads(cluster, {"current_file_version": 0x00000001}):
         await dev.initialize()
@@ -2003,3 +2005,225 @@ async def test_attribute_report_not_matched_with_request(dev):
     result = await request_task
 
     assert result == default_rsp_cmd
+
+
+async def test_reinterview_end_to_end(
+    monkeypatch,
+    app: zigpy.application.ControllerApplication,
+):
+    """End-to-end reinterview: real app, full flow from reinterview() through swap."""
+    ieee = t.EUI64.convert("aa:bb:cc:dd:ee:ff:00:11")
+    node_desc = zdo_t.NodeDescriptor(1, 1, 1, 4, 5, 6, 7, 8)
+
+    async def mock_get_node_descriptor(self):
+        self.node_desc = node_desc
+        return node_desc
+
+    async def mockrequest(*args, **kwargs):
+        return [0, None, [0, 1]]
+
+    async def mockepinit(self, *args, **kwargs):
+        self.status = endpoint.Status.ZDO_INIT
+        self.add_input_cluster(Basic.cluster_id)
+
+    async def mock_ep_get_model_info(self):
+        return "Model", "Manufacturer"
+
+    monkeypatch.setattr(device.Device, "get_node_descriptor", mock_get_node_descriptor)
+    monkeypatch.setattr(endpoint.Endpoint, "initialize", mockepinit)
+    monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info)
+
+    # Initial join and initialization
+    dev = app.add_device(ieee=ieee, nwk=t.NWK(0x1234))
+    dev.zdo.Active_EP_req = mockrequest
+    await dev.initialize()
+    assert dev.is_initialized
+    old_dev = app.devices[ieee]
+
+    # Set non-discovery state on the old device
+    old_dev._last_seen = datetime(2026, 1, 1, tzinfo=UTC)
+    old_dev.lqi = 200
+    old_dev.rssi = -40
+
+    # Patch Device.__init__ so the shadow also gets Active_EP_req mocked
+    original_init = device.Device.__init__
+
+    def patched_init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        self.zdo.Active_EP_req = mockrequest
+
+    monkeypatch.setattr(device.Device, "__init__", patched_init)
+
+    # Change what model info returns for the reinterview
+    async def mock_ep_get_model_info_v2(self):
+        return "ModelV2", "ManufacturerV2"
+
+    monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info_v2)
+
+    # Reset listener_event mock so we only see events from the reinterview
+    app.listener_event.reset_mock()
+
+    # Run the full reinterview flow
+    await old_dev.reinterview()
+
+    # The device in app.devices should be a new object
+    new_dev = app.devices[ieee]
+    assert new_dev is not old_dev
+    assert new_dev.model == "ModelV2"
+    assert new_dev.manufacturer == "ManufacturerV2"
+    assert new_dev.is_initialized
+    assert 1 in new_dev.endpoints
+    assert not new_dev.reinterviewing
+    assert not old_dev.reinterviewing
+
+    # Non-discovery state should have been preserved
+    assert new_dev._last_seen == datetime(2026, 1, 1, tzinfo=UTC)
+    assert new_dev.lqi == 200
+    assert new_dev.rssi == -40
+
+    # device_reinterviewed event should have been fired, but NOT device_initialized
+    app.listener_event.assert_any_call("device_reinterviewed", new_dev)
+    device_initialized_calls = [
+        c for c in app.listener_event.call_args_list if c[0][0] == "device_initialized"
+    ]
+    assert len(device_initialized_calls) == 0
+
+
+@pytest.mark.parametrize(
+    "exception",
+    [TimeoutError, RuntimeError("unexpected")],
+    ids=["timeout", "unexpected"],
+)
+async def test_reinterview_failure_preserves_device(monkeypatch, dev, exception):
+    """Test that failed re-interview preserves the old device regardless of exception type."""
+
+    async def mockrequest_success(*args, **kwargs):
+        return [0, None, [0, 1]]
+
+    async def mockepinit(self, *args, **kwargs):
+        self.status = endpoint.Status.ZDO_INIT
+        self.add_input_cluster(Basic.cluster_id)
+
+    async def mock_ep_get_model_info(self):
+        return "OldModel", "OldManufacturer"
+
+    monkeypatch.setattr(endpoint.Endpoint, "initialize", mockepinit)
+    monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info)
+
+    # First initialize normally
+    dev.zdo.Active_EP_req = mockrequest_success
+    await dev.initialize()
+    assert dev.model == "OldModel"
+
+    # Use a real dict for devices so we can verify restoration
+    dev._application.devices = {dev.ieee: dev}
+
+    # Make the shadow's discovery fail
+    monkeypatch.setattr(
+        device.Device, "get_node_descriptor", AsyncMock(side_effect=exception)
+    )
+
+    dev._application._device_reinterviewed = AsyncMock()
+
+    await dev.reinterview()
+
+    # _device_reinterviewed should NOT have been called
+    dev._application._device_reinterviewed.assert_not_called()
+
+    # Old device should be restored in app.devices
+    assert dev._application.devices[dev.ieee] is dev
+
+    # Old device is completely untouched
+    assert dev.model == "OldModel"
+    assert dev.manufacturer == "OldManufacturer"
+    assert 1 in dev.endpoints
+    assert dev.is_initialized
+    assert not dev.reinterviewing
+
+    # Failure event was fired
+    dev._application.listener_event.assert_called_with(
+        "device_reinterview_failure", dev
+    )
+
+
+async def test_reinterview_blocks_auto_init(dev):
+    """Test that schedule_initialize is a no-op while reinterviewing."""
+    dev._reinterview_in_progress = True
+
+    result = dev.schedule_initialize()
+
+    assert result is None
+    assert not dev.initializing
+
+
+async def test_reinterview_already_in_progress(dev):
+    """Test that concurrent reinterview calls are prevented."""
+    dev._reinterview_in_progress = True
+    dev._application._device_reinterviewed = AsyncMock()
+
+    await dev.reinterview()
+
+    dev._application._device_reinterviewed.assert_not_called()
+
+
+async def test_reinterview_during_initialization(dev):
+    """Test that reinterview is skipped if initialization is in progress."""
+    dev._initialize_task = asyncio.Future()  # simulate in-progress init
+    dev._application._device_reinterviewed = AsyncMock()
+
+    await dev.reinterview()
+
+    dev._application._device_reinterviewed.assert_not_called()
+    dev._initialize_task.cancel()
+
+
+async def test_reinterview_during_ota(dev):
+    """Test that reinterview is skipped while an OTA is in progress."""
+    dev.ota_in_progress = True
+    dev._application._device_reinterviewed = AsyncMock()
+
+    await dev.reinterview()
+
+    dev._application._device_reinterviewed.assert_not_called()
+
+
+async def test_update_firmware_triggers_reinterview(monkeypatch, dev):
+    """Test that successful OTA triggers reinterview."""
+    ep = dev.add_endpoint(1)
+    cluster = zigpy.zcl.Cluster.from_id(ep, Ota.cluster_id, is_server=False)
+    ep.add_output_cluster(Ota.cluster_id, cluster)
+
+    async def mockrequest(nwk, tries=None, delay=None):
+        return [0, None, [0, 1]]
+
+    async def mockepinit(self, *args, **kwargs):
+        self.status = endpoint.Status.ZDO_INIT
+        self.add_input_cluster(Basic.cluster_id)
+
+    async def mock_ep_get_model_info(self):
+        return "Model", "Manufacturer"
+
+    monkeypatch.setattr(endpoint.Endpoint, "initialize", mockepinit)
+    monkeypatch.setattr(endpoint.Endpoint, "get_model_info", mock_ep_get_model_info)
+    dev.zdo.Active_EP_req = mockrequest
+
+    with mock_attribute_reads(cluster, {"current_file_version": 0x00000001}):
+        await dev.initialize()
+
+    # Mock the OTA process to return success
+
+    monkeypatch.setattr(
+        "zigpy.device.update_firmware",
+        AsyncMock(return_value=foundation.Status.SUCCESS),
+    )
+
+    dev.reinterview = AsyncMock()
+
+    with mock_attribute_reads(cluster, {"current_file_version": 0x00000002}):
+        result = await dev.update_firmware(
+            MagicMock(),
+            progress_callback=MagicMock(),
+        )
+
+    assert result == foundation.Status.SUCCESS
+    dev.reinterview.assert_awaited_once()

{zigpy-1.2.2 → zigpy-1.4.0}/tests/test_serial.py

@@ -54,7 +54,7 @@ async def test_serial_normal(
         kwargs["rtscts"] = rtscts
 
     with patch(
-        "zigpy.serial.pyserial_asyncio.create_serial_connection",
+        "zigpy.serial.serialx_create_serial_connection",
         AsyncMock(
             return_value=(AsyncMock(), AsyncMock())
         ),
@@ -71,32 +71,7 @@ async def test_serial_normal(
         assert mock_calls[0].kwargs[kwarg] == expected_kwargs[kwarg]
 
 
-async def test_serial_socket() -> None:
-    loop = asyncio.get_running_loop()
-    protocol_factory = Mock()
-
-    with patch.object(
-        loop,
-        "create_connection",
-        AsyncMock(
-            return_value=(AsyncMock(), AsyncMock())
-        ),
-    ):
-        await zigpy.serial.create_serial_connection(
-            loop, protocol_factory, "socket://1.2.3.4:5678"
-        )
-        await zigpy.serial.create_serial_connection(
-            loop, protocol_factory, "socket://1.2.3.4"
-        )
-
-        assert len(loop.create_connection.mock_calls) == 2
-        assert loop.create_connection.mock_calls[0].kwargs["host"] == "1.2.3.4"
-        assert loop.create_connection.mock_calls[0].kwargs["port"] == 5678
-        assert loop.create_connection.mock_calls[1].kwargs["host"] == "1.2.3.4"
-        assert loop.create_connection.mock_calls[1].kwargs["port"] == 6638
-
-
-async def test_pyserial_error_remapping(tmp_path: pathlib.Path) -> None:
+async def test_serial_error_remapping(tmp_path: pathlib.Path) -> None:
     loop = asyncio.get_running_loop()
     protocol_factory = Mock()
 
@@ -119,15 +94,6 @@ async def test_pyserial_error_remapping(tmp_path: pathlib.Path) -> None:
             loop, protocol_factory, url=denied_port
         )
 
-    # IsADirectoryError
-    a_folder = tmp_path / "a_folder"
-    a_folder.mkdir()
-
-    with pytest.raises(IsADirectoryError):
-        await zigpy.serial.create_serial_connection(
-            loop, protocol_factory, url=a_folder
-        )
-
     # Locked
     locked_port = tmp_path / "locked"
     with locked_port.open("w") as f:

{zigpy-1.2.2 → zigpy-1.4.0}/zigpy/application.py

@@ -596,9 +596,13 @@ class ControllerApplication(zigpy.util.ListenableMixin, abc.ABC):
         self.devices[ieee] = dev
         return dev
 
-    def device_initialized(self, device: zigpy.device.Device) -> None:
-        """Used by a device to signal that it is initialized"""
-        LOGGER.debug("Device is initialized %s", device)
+    def _finalize_device(self, device: zigpy.device.Device) -> zigpy.device.Device:
+        """Apply quirks, persist to DB, and register the device.
+
+        Returns the (possibly quirked) device stored in ``self.devices``.
+        Does **not** fire any listener events beyond ``raw_device_initialized``
+        (which triggers the DB save).
+        """
         device.original_signature = device.get_signature()
 
         self.listener_event("raw_device_initialized", device)
@@ -606,8 +610,85 @@ class ControllerApplication(zigpy.util.ListenableMixin, abc.ABC):
         self.devices[device.ieee] = device
         if self._dblistener is not None:
             device.add_context_listener(self._dblistener)
+
+        return device
+
+    def device_initialized(self, device: zigpy.device.Device) -> None:
+        """Used by a device to signal that it is initialized"""
+        LOGGER.debug("Device is initialized %s", device)
+        device = self._finalize_device(device)
         self.listener_event("device_initialized", device)
 
+    async def _device_reinterviewed(
+        self,
+        old_device: zigpy.device.Device,
+        shadow: zigpy.device.Device,
+    ) -> None:
+        """Swap an old device with a successfully re-interviewed shadow.
+
+        Preserves non-discovery state (last_seen, relays, lqi, rssi) and group
+        memberships.  Exceptions propagate to ``reinterview()`` which logs them
+        and fires the ``device_reinterview_failure`` event.
+        """
+        # Copy non-discovery state from old device to shadow
+        shadow._last_seen = old_device._last_seen
+        shadow._relays = old_device._relays
+        shadow.lqi = old_device.lqi
+        shadow.rssi = old_device.rssi
+
+        # Collect group memberships and remove old endpoints from groups
+        old_group_memberships: dict[int, set[int]] = {}
+        for ep in old_device.non_zdo_endpoints:
+            if ep.member_of:
+                old_group_memberships[ep.endpoint_id] = set(ep.member_of)
+                for group in list(ep.member_of.values()):
+                    group.remove_member(ep, suppress_event=True)
+
+        # Remove old device data from DB (cascade deletes endpoints, clusters,
+        # attribute cache, group members, and relays).  We call _remove_device
+        # directly instead of the public device_removed() because we need the
+        # delete to complete before _finalize_device enqueues the save.
+        if self._dblistener is not None:
+            old_device.remove_listener(self._dblistener)
+            await self._dblistener._remove_device(old_device)
+
+        # Clean up old device's callbacks and tasks
+        old_device.on_remove()
+
+        # Apply quirks, persist to DB, and register the device — but do NOT
+        # fire the device_initialized listener event.  Callers (and ZHA)
+        # should listen for device_reinterviewed instead.
+        new_device = self._finalize_device(shadow)
+
+        # Clear the reinterview flag so the new device isn't permanently stuck
+        # (relevant when no quirk is applied and new_device is the shadow itself)
+        new_device._reinterview_in_progress = False
+
+        # Restore group memberships on the new device's matching endpoints.
+        # A group may have been removed while we were awaiting `_remove_device`,
+        # so guard against missing entries rather than aborting the reinterview.
+        for ep_id, group_ids in old_group_memberships.items():
+            if ep_id in new_device.endpoints:
+                new_ep = new_device.endpoints[ep_id]
+                for group_id in group_ids:
+                    group = self.groups.get(group_id)
+                    if group is not None:
+                        group.add_member(new_ep)
+
+        # Persist relays for the new device (cascade deleted the old row)
+        if self._dblistener is not None and new_device._relays is not None:
+            self._dblistener.device_relays_updated(new_device, new_device._relays)
+
+        self.listener_event("device_reinterviewed", new_device)
+
+    async def reinterview_device(self, ieee: t.EUI64) -> None:
+        """Re-interview a device. Safe for sleepy end-devices.
+
+        If the device does not respond, existing state is preserved.
+        """
+        dev = self.get_device(ieee=ieee)
+        await dev.reinterview()
+
     async def remove(
         self, ieee: t.EUI64, remove_children: bool = True, rejoin: bool = False
     ) -> None: