zencontrol-python 0.1.0__tar.gz → 0.1.1__tar.gz

zencontrol_python-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Wright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{zencontrol_python-0.1.0/zencontrol_python.egg-info → zencontrol_python-0.1.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.0
+Version: 0.1.1
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
-License-Expression: LGPL-2.1-only
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/sjwright/zencontrol-python
 Project-URL: Repository, https://github.com/sjwright/zencontrol-python
 Project-URL: Issues, https://github.com/sjwright/zencontrol-python/issues
@@ -74,6 +74,10 @@ Not implemented:
 * Command to read an ambient light sensor's lux value. _(As a workaround, you can target a light sensor to a system variable. Not elegant but it works.)_
 * Event notification for ambient light sensor lux values. _(Same workaround as above.)_
 
+## License
+
+[MIT](LICENSE)
+
 ## Links
 
 * [About TPI Advanced](https://support.zencontrol.com/hc/en-us/articles/360000337175-What-is-the-Third-Party-Interface-TPI)

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/README.md

@@ -38,6 +38,10 @@ Not implemented:
 * Command to read an ambient light sensor's lux value. _(As a workaround, you can target a light sensor to a system variable. Not elegant but it works.)_
 * Event notification for ambient light sensor lux values. _(Same workaround as above.)_
 
+## License
+
+[MIT](LICENSE)
+
 ## Links
 
 * [About TPI Advanced](https://support.zencontrol.com/hc/en-us/articles/360000337175-What-is-the-Third-Party-Interface-TPI)

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers."
 readme = "README.md"
 requires-python = ">=3.11"
-license = "LGPL-2.1-only"
+license = "MIT"
 license-files = ["LICENSE"]
 authors = [
     {name = "Simon Wright"},

zencontrol_python-0.1.1/tests/test_discovery.py

@@ -0,0 +1,156 @@
+"""Unit tests for multicast controller discovery."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from zencontrol.api.models import DiscoveredController, ZenController
+from zencontrol.api.protocol import ZenProtocol
+from zencontrol.io.event import ZenEvent
+
+
+def _event(
+    *,
+    ip: str = "192.168.1.50",
+    mac: bytes = b"\x02\x00\x00\x00\x00\x01",
+    code: int = 1,
+) -> ZenEvent:
+    return ZenEvent(
+        raw_data=b"ZC" + mac + bytes([0, code, 0]),
+        event_code=code,
+        target=0,
+        payload=b"\x00",
+        mac_address=mac,
+        ip_address=ip,
+        ip_port=6969,
+    )
+
+
+@pytest.mark.asyncio
+async def test_unknown_multicast_queries_label_and_remembers() -> None:
+    protocol = ZenProtocol()
+    seen: list[DiscoveredController] = []
+
+    async def on_discovered(discovered: DiscoveredController) -> None:
+        seen.append(discovered)
+
+    protocol.callbacks.controller_discovered = on_discovered
+
+    with patch.object(
+        protocol, "query_controller_label", new_callable=AsyncMock, return_value="Kitchen"
+    ) as query:
+        await protocol._process_zen_event(_event())
+
+    query.assert_awaited_once()
+    assert len(protocol.identified_controllers) == 1
+    discovered = protocol.identified_controllers[0]
+    assert discovered.host == "192.168.1.50"
+    assert discovered.mac == "02:00:00:00:00:01"
+    assert discovered.label == "Kitchen"
+    assert discovered.port == 5108
+    assert seen == [discovered]
+
+
+@pytest.mark.asyncio
+async def test_second_packet_from_same_mac_or_ip_is_ignored() -> None:
+    protocol = ZenProtocol()
+    with patch.object(
+        protocol, "query_controller_label", new_callable=AsyncMock, return_value="Kitchen"
+    ) as query:
+        await protocol._process_zen_event(_event())
+        await protocol._process_zen_event(_event())
+        await protocol._process_zen_event(
+            _event(ip="192.168.1.99", mac=b"\x02\x00\x00\x00\x00\x01")
+        )
+        await protocol._process_zen_event(
+            _event(ip="192.168.1.50", mac=b"\xaa\xbb\xcc\xdd\xee\xff")
+        )
+
+    assert query.await_count == 1
+    assert len(protocol.identified_controllers) == 1
+
+
+@pytest.mark.asyncio
+async def test_registered_controller_is_not_discovered() -> None:
+    protocol = ZenProtocol()
+    ctrl = ZenController(
+        id="1",
+        name="known",
+        label="Known",
+        host="192.168.1.50",
+        port=5108,
+        mac="02:00:00:00:00:01",
+        protocol=protocol,
+    )
+    protocol.set_controllers([ctrl])
+
+    with patch.object(
+        protocol, "query_controller_label", new_callable=AsyncMock, return_value="Nope"
+    ) as query:
+        await protocol._process_zen_event(_event())
+
+    query.assert_not_awaited()
+    assert protocol.identified_controllers == []
+
+
+@pytest.mark.asyncio
+async def test_registering_controller_forgets_identified() -> None:
+    protocol = ZenProtocol()
+    with patch.object(
+        protocol, "query_controller_label", new_callable=AsyncMock, return_value="Kitchen"
+    ):
+        await protocol._process_zen_event(_event())
+    assert len(protocol.identified_controllers) == 1
+
+    ctrl = ZenController(
+        id="1",
+        name="kitchen",
+        label="Kitchen",
+        host="192.168.1.50",
+        port=5108,
+        mac="02:00:00:00:00:01",
+        protocol=protocol,
+    )
+    protocol.set_controllers([ctrl])
+    assert protocol.identified_controllers == []
+
+
+@pytest.mark.asyncio
+async def test_label_query_failure_still_remembers_controller() -> None:
+    protocol = ZenProtocol()
+    with patch.object(
+        protocol,
+        "query_controller_label",
+        new_callable=AsyncMock,
+        side_effect=TimeoutError("offline"),
+    ):
+        await protocol._process_zen_event(_event())
+
+    assert len(protocol.identified_controllers) == 1
+    assert protocol.identified_controllers[0].label is None
+
+
+@pytest.mark.asyncio
+async def test_new_controller_discovered_while_one_is_registered() -> None:
+    protocol = ZenProtocol()
+    known = ZenController(
+        id="1",
+        name="known",
+        label="Known",
+        host="192.168.1.10",
+        port=5108,
+        mac="11:22:33:44:55:66",
+        protocol=protocol,
+    )
+    protocol.set_controllers([known])
+
+    with patch.object(
+        protocol, "query_controller_label", new_callable=AsyncMock, return_value="Annex"
+    ) as query:
+        await protocol._process_zen_event(_event())
+
+    query.assert_awaited_once()
+    assert len(protocol.identified_controllers) == 1
+    assert protocol.identified_controllers[0].label == "Annex"

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/tests/test_reconnect.py

@@ -122,3 +122,45 @@ async def test_stop_does_not_reconnect() -> None:
         await zen.stop()
         await asyncio.sleep(0.1)
         assert create_count == 1
+
+
+@pytest.mark.asyncio
+async def test_supervisor_cancel_does_not_reconnect() -> None:
+    """HA cancels tasks on shutdown before unload sets _stopping — no reconnect."""
+    zen = ZenControl()
+    zen.reconnect_min_delay = 0.01
+    started = asyncio.Event()
+    create_count = 0
+
+    class _BlockingListener(_ControllableListener):
+        async def events(self):
+            started.set()
+            try:
+                while True:
+                    await asyncio.sleep(3600)
+                    yield  # pragma: no cover
+            except asyncio.CancelledError:
+                raise
+
+    async def fake_create(*args, **kwargs):
+        nonlocal create_count
+        create_count += 1
+        return _BlockingListener()
+
+    with patch(
+        "zencontrol.api.protocol.ZenListener.create",
+        new=AsyncMock(side_effect=fake_create),
+    ):
+        await zen.start()
+        await asyncio.wait_for(started.wait(), timeout=1.0)
+        assert create_count == 1
+        assert zen._supervisor_task is not None
+
+        zen._supervisor_task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await zen._supervisor_task
+
+        await asyncio.sleep(0.1)
+        assert create_count == 1
+        # Mimic unload after task cancel
+        await zen.aclose()

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/tests/test_wire_resilience.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from unittest.mock import AsyncMock, MagicMock, patch
+import socket
+from unittest.mock import AsyncMock, MagicMock, call, patch
 
 import pytest
 
@@ -44,6 +45,65 @@ async def test_event_queue_drop_oldest_under_backpressure() -> None:
     assert second.event_code == 3
 
 
+@pytest.mark.asyncio
+async def test_multicast_listener_joins_before_endpoint_and_drops_on_stop() -> None:
+    """Reuse/join must happen before asyncio owns the socket; DROP before close."""
+    fake_sock = MagicMock()
+    fake_transport = MagicMock()
+    fake_transport.is_closing.return_value = False
+    fake_transport.get_extra_info.return_value = fake_sock
+
+    with patch("zencontrol.io.event.socket.socket", return_value=fake_sock):
+        loop = asyncio.get_running_loop()
+        with patch.object(
+            loop,
+            "create_datagram_endpoint",
+            new_callable=AsyncMock,
+            return_value=(fake_transport, MagicMock()),
+        ) as create_endpoint:
+            listener = await ZenListener.create(unicast=False)
+
+    create_endpoint.assert_awaited_once()
+    assert create_endpoint.await_args.kwargs["sock"] is fake_sock
+    assert listener._mreq is not None
+
+    # First setsockopt should be SO_REUSEADDR (before bind); ADD_MEMBERSHIP after bind
+    first_opt = fake_sock.setsockopt.call_args_list[0].args[:2]
+    assert first_opt == (socket.SOL_SOCKET, socket.SO_REUSEADDR)
+    assert fake_sock.bind.call_args_list[0] == call(
+        ("0.0.0.0", EventConst.MULTICAST_PORT)
+    )
+    add_call = next(
+        c
+        for c in fake_sock.setsockopt.call_args_list
+        if c.args[:2] == (socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP)
+    )
+    assert add_call.args[2] == listener._mreq
+    bind_pos = next(
+        i for i, (name, *_) in enumerate(fake_sock.method_calls) if name == "bind"
+    )
+    add_pos = next(
+        i
+        for i, (name, args, _) in enumerate(fake_sock.method_calls)
+        if name == "setsockopt"
+        and args[:2] == (socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP)
+    )
+    assert bind_pos < add_pos
+
+    joined_mreq = add_call.args[2]
+    await listener.stop_listening()
+
+    drop_calls = [
+        c
+        for c in fake_sock.setsockopt.call_args_list
+        if c.args[:2] == (socket.IPPROTO_IP, socket.IP_DROP_MEMBERSHIP)
+    ]
+    assert len(drop_calls) == 1
+    assert drop_calls[0].args[2] == joined_mreq
+    fake_transport.close.assert_called_once()
+    assert listener._mreq is None
+
+
 def test_local_ip_for_remote_returns_ipv4() -> None:
     ip = local_ip_for_remote("127.0.0.1")
     assert ip.count(".") == 3

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/zencontrol/__init__.py

@@ -45,7 +45,7 @@ from .interface import (
 )
 
 # API-level models (used by zen_api)
-from .api.models import ZenAddress, ZenInstance, ZenColour
+from .api.models import ZenAddress, ZenInstance, ZenColour, DiscoveredController
 from .api.protocol import ZenProtocol
 
 # Low-level models (used by zen_io)
@@ -58,7 +58,7 @@ from .exceptions import ZenError, ZenTimeoutError, ZenResponseError
 # Utilities
 from .utils import run_with_keyboard_interrupt
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "Simon Wright"
 
 # Public API - these are the main classes users should import
@@ -80,6 +80,7 @@ __all__ = [
     "ZenInstance",
     "ZenProtocol",
     "ZenColour",
+    "DiscoveredController",
 
     # Low-level models (for advanced users)
     "ZenClient",

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/zencontrol/api/__init__.py

@@ -8,7 +8,7 @@ This module contains models and types that belong to the API layer:
 - Types and enums used by the API layer
 """
 
-from .models import ZenController, ZenAddress, ZenInstance, ZenColour, ZenProfile
+from .models import ZenController, ZenAddress, ZenInstance, ZenColour, ZenProfile, DiscoveredController
 from .protocol import ZenProtocol
 from .types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventMask, ZenEventMode
 
@@ -19,6 +19,7 @@ __all__ = [
     "ZenInstance",
     "ZenColour",
     "ZenProfile",
+    "DiscoveredController",
     "ZenProtocol",
     
     # API-level types

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/zencontrol/api/models.py

@@ -18,6 +18,19 @@ from ..io import ZenClient
 from .types import ZenAddressType, ZenInstanceType, ZenColourType, Const
 
 
+DEFAULT_CONTROLLER_PORT = 5108
+
+
+@dataclass(frozen=True)
+class DiscoveredController:
+    """A controller identified from multicast events (not yet registered)."""
+
+    host: str
+    mac: str
+    label: Optional[str] = None
+    port: int = DEFAULT_CONTROLLER_PORT
+
+
 @dataclass
 class ZenController:
     """Represents a ZenControl controller

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/zencontrol/api/protocol.py

@@ -11,11 +11,29 @@ from colorama import Fore, Back, Style
 from dataclasses import dataclass, field
 
 from ..io import ZenClient, ZenListener, ZenEvent, Request, Response, ResponseType, RequestType, EventConst, ClientConst
-from .models import ZenController, ZenAddress, ZenInstance, ZenColour, ZenProfile
+from .models import (
+    DEFAULT_CONTROLLER_PORT,
+    DiscoveredController,
+    ZenController,
+    ZenAddress,
+    ZenInstance,
+    ZenColour,
+    ZenProfile,
+)
 from .types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventCode, ZenEventMask, ZenEventMode, ZenErrorCode, Const
 from ..exceptions import ZenError, ZenTimeoutError, ZenResponseError
 from ..utils import local_ip_for_remote
 
+
+def _mac_bytes_to_str(mac: bytes) -> str:
+    """Format MAC bytes as uppercase colon-separated hex."""
+    return ":".join(f"{b:02X}" for b in mac)
+
+
+def _mac_str_to_key(mac: str) -> str:
+    """Normalize a MAC string to uppercase hex without separators."""
+    return mac.upper().replace(":", "").replace("-", "")
+
 """
 ===================================================================================
 This module implements the ZenControl TPI Advanced API using zen_io.
@@ -40,6 +58,9 @@ class ZenCallbacks:
         self.button_long_press: Optional[Callable[..., Awaitable[None]]] = None
         self.motion_event: Optional[Callable[..., Awaitable[None]]] = None
         self.system_variable_change: Optional[Callable[..., Awaitable[None]]] = None
+        self.controller_discovered: Optional[
+            Callable[[DiscoveredController], Awaitable[None]]
+        ] = None
 
 
 class EntityRegistry:
@@ -216,6 +237,13 @@ class ZenProtocol:
         
         # Controllers will be assigned later
         self.controllers = []
+        # Controllers identified via multicast but not yet registered
+        self.identified_controllers: list[DiscoveredController] = []
+        self._discovery_pending_macs: set[str] = set()
+        self._discovery_pending_ips: set[str] = set()
+        self.controller_discovered_callback: Optional[
+            Callable[[DiscoveredController], Awaitable[None]]
+        ] = None
         # High-level callback registry (replaced per ZenControl instance)
         self.callbacks = ZenCallbacks()
         # Interface-layer entity identity (scoped to this protocol)
@@ -275,6 +303,39 @@ class ZenProtocol:
 
     def set_controllers(self, controllers: list[ZenController]):
         self.controllers = controllers # Used to match events to controllers, and include controller objects in callbacks
+        # Drop identified entries that are now registered
+        for ctrl in controllers:
+            self.forget_identified(host=ctrl.host, mac=ctrl.mac)
+
+    def get_identified_by_ip_mac(
+        self, ip: Optional[str] = None, mac: Optional[bytes | str] = None
+    ) -> Optional[DiscoveredController]:
+        """Find an already-identified (discovered) controller by IP or MAC."""
+        mac_key: Optional[str] = None
+        if isinstance(mac, bytes):
+            mac_key = _mac_str_to_key(_mac_bytes_to_str(mac))
+        elif isinstance(mac, str):
+            mac_key = _mac_str_to_key(mac)
+        for discovered in self.identified_controllers:
+            if ip is not None and discovered.host == ip:
+                return discovered
+            if mac_key is not None and _mac_str_to_key(discovered.mac) == mac_key:
+                return discovered
+        return None
+
+    def forget_identified(
+        self, *, host: Optional[str] = None, mac: Optional[str] = None
+    ) -> None:
+        """Remove matching entries from the identified-controller cache."""
+        mac_key = _mac_str_to_key(mac) if mac else None
+        self.identified_controllers = [
+            d
+            for d in self.identified_controllers
+            if not (
+                (host is not None and d.host == host)
+                or (mac_key is not None and _mac_str_to_key(d.mac) == mac_key)
+            )
+        ]
 
     # ============================
     # PACKET SENDING
@@ -657,7 +718,88 @@ class ZenProtocol:
                 if ctrl.mac_bytes == mac:
                     return ctrl
         return None
-    
+
+    async def _handle_unknown_controller(self, event: ZenEvent) -> None:
+        """Identify a new controller from multicast, query its label, and remember it."""
+        mac_str = _mac_bytes_to_str(event.mac_address)
+        mac_key = _mac_str_to_key(mac_str)
+        host = event.ip_address
+
+        if self.get_identified_by_ip_mac(host, event.mac_address) is not None:
+            return
+        if mac_key in self._discovery_pending_macs or host in self._discovery_pending_ips:
+            return
+
+        self._discovery_pending_macs.add(mac_key)
+        self._discovery_pending_ips.add(host)
+        label: Optional[str] = None
+        temp: Optional[ZenController] = None
+        try:
+            temp = ZenController(
+                id=f"discover-{mac_key}",
+                name=f"_discover_{mac_key}",
+                label="",
+                host=host,
+                port=DEFAULT_CONTROLLER_PORT,
+                mac=mac_str,
+                protocol=self,
+            )
+            try:
+                label = await self.query_controller_label(temp)
+            except ZenTimeoutError:
+                self.logger.info(
+                    "Discovered controller %s (%s) but label query timed out",
+                    host,
+                    mac_str,
+                )
+            except Exception as err:
+                self.logger.warning(
+                    "Discovered controller %s (%s) but label query failed: %s",
+                    host,
+                    mac_str,
+                    err,
+                )
+
+            # Re-check in case a race registered the controller meanwhile
+            if self.get_controller_by_ip_mac(host, event.mac_address) is not None:
+                return
+            if self.get_identified_by_ip_mac(host, event.mac_address) is not None:
+                return
+
+            discovered = DiscoveredController(
+                host=host,
+                mac=mac_str,
+                label=label,
+                port=DEFAULT_CONTROLLER_PORT,
+            )
+            self.identified_controllers.append(discovered)
+            self.logger.info(
+                "Identified controller %s mac=%s label=%r",
+                host,
+                mac_str,
+                label,
+            )
+
+            callback = self.controller_discovered_callback
+            if callback is None and callable(self.callbacks.controller_discovered):
+                callback = self.callbacks.controller_discovered
+            if callable(callback):
+                try:
+                    await callback(discovered)
+                except Exception as err:
+                    self.logger.error(
+                        "controller_discovered callback error: %s", err, exc_info=err
+                    )
+        finally:
+            self._discovery_pending_macs.discard(mac_key)
+            self._discovery_pending_ips.discard(host)
+            if temp is not None and temp.client is not None:
+                try:
+                    await temp.client.close()
+                except Exception:
+                    pass
+                temp.client = None
+
     async def _process_zen_event(self, event: ZenEvent):
         """Process received ZenEvent from ZenListener"""
         typecast = "unicast" if self.unicast else "multicast"
@@ -665,7 +807,7 @@ class ZenProtocol:
         # Find the controller that sent this event
         controller = self.get_controller_by_ip_mac(event.ip_address, event.mac_address)
         if not controller:
-            self.logger.warning(f"Received {typecast} packet from unknown controller: {event.ip_address}: [{' '.join(f'0x{b:02X}' for b in event.raw_data)}]")
+            await self._handle_unknown_controller(event)
             return
 
         ip_address = event.ip_address

{zencontrol_python-0.1.0 → zencontrol_python-0.1.1}/zencontrol/interface/interface.py

@@ -8,6 +8,7 @@ from typing import Any, Optional, Callable, Awaitable, cast, Self
 from collections.abc import Coroutine
 
 from ..api import ZenProtocol, ZenController as SuperZenController, ZenAddress, ZenInstance, ZenAddressType, ZenColour, ZenColourType, ZenInstanceType
+from ..api.models import DiscoveredController
 from ..api.protocol import ZenCallbacks
 from ..api.types import Const
 
@@ -217,6 +218,18 @@ class ZenControl:
     def system_variable_change(self, func: "CallbackSystemVariableChange | None") -> None:
         self.protocol.callbacks.system_variable_change = func
 
+    @property
+    def controller_discovered(self) -> "CallbackControllerDiscovered | None":
+        return self.protocol.callbacks.controller_discovered
+    @controller_discovered.setter
+    def controller_discovered(self, func: "CallbackControllerDiscovered | None") -> None:
+        self.protocol.callbacks.controller_discovered = func
+
+    @property
+    def discovered_controllers(self) -> list[DiscoveredController]:
+        """Controllers identified from multicast but not yet registered."""
+        return list(self.protocol.identified_controllers)
+
     # ============================
     # Setup / Start / Stop
     # ============================
@@ -228,6 +241,31 @@ class ZenControl:
         self.protocol.set_controllers(cast(list[SuperZenController], self.controllers))
         return controller
 
+    async def discover(self, timeout: float = 5.0) -> list[DiscoveredController]:
+        """Listen for multicast and return controllers identified within ``timeout`` seconds.
+
+        Starts event monitoring if needed. Works with zero registered controllers
+        and also reports controllers that are not already registered while running.
+        """
+        before = {
+            (d.mac.upper().replace("-", ":"), d.host)
+            for d in self.protocol.identified_controllers
+        }
+        started_here = False
+        if self._supervisor_task is None or self._supervisor_task.done():
+            await self.start()
+            started_here = True
+        try:
+            await asyncio.sleep(timeout)
+        finally:
+            if started_here:
+                await self.stop()
+        return [
+            d
+            for d in self.protocol.identified_controllers
+            if (d.mac.upper().replace("-", ":"), d.host) not in before
+        ]
+
     async def start(self) -> None:
         """Start event monitoring with automatic reconnect on unexpected loss."""
         self._stopping = False
@@ -315,8 +353,9 @@ class ZenControl:
             try:
                 await event_task
             except asyncio.CancelledError:
-                if self._stopping:
-                    return
+                # HA (and asyncio) cancel tasks on shutdown before unload can set
+                # _stopping. Never reconnect on cancel — always exit.
+                raise
             except Exception as err:
                 self.logger.error(f"Event monitor task error: {err}")
 
@@ -336,7 +375,7 @@ class ZenControl:
             try:
                 await asyncio.sleep(delay)
             except asyncio.CancelledError:
-                return
+                raise
 
     async def _prepare_for_reconnect(self) -> None:
         """Drop stale clients and refresh DNS before binding the listener again."""
@@ -1577,3 +1616,4 @@ CallbackButtonPress = Callable[[ZenButton], Awaitable[None]]
 CallbackButtonLongPress = Callable[[ZenButton], Awaitable[None]]
 CallbackMotionEvent = Callable[[ZenMotionSensor, bool], Awaitable[None]]
 CallbackSystemVariableChange = Callable[[ZenSystemVariable, int, bool, bool], Awaitable[None]]
+CallbackControllerDiscovered = Callable[[DiscoveredController], Awaitable[None]]