ebus-sdk 0.2.2__tar.gz → 0.3.1__tar.gz

{ebus_sdk-0.2.2/src/ebus_sdk.egg-info → ebus_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-sdk
-Version: 0.2.2
+Version: 0.3.1
 Summary: Python SDK for Homie MQTT Convention (eBus)
 Author: Clark Communications Corporation
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ebus-mqtt-client>=0.1.2
+Requires-Dist: ebus-mqtt-client>=0.1.6
 Requires-Dist: paho-mqtt>=1.5.0
 Provides-Extra: mdns
 Requires-Dist: zeroconf>=0.131.0; extra == "mdns"
@@ -131,6 +131,28 @@ for root in roots:
         print(f'{descendant.device_id}: {controller.get_effective_state(descendant.device_id)}')
 ```
 
+Three controller discovery modes select what the controller listens for:
+
+```python
+# Wildcard (default) — every device on the broker
+Controller(mqtt_cfg=cfg)
+
+# Single-device — subscribe to exactly one device, no children, no wildcards
+Controller(mqtt_cfg=cfg, device_id='panel-1')
+
+# Tree-rooted — subscribe to a root and auto-subscribe to its descendants
+# as they're announced; subscription changes are gated on the parent's
+# $state init→ready edge per the Homie 5 spec.
+Controller(mqtt_cfg=cfg, root_device_id='panel-1')
+```
+
+Tree-rooted mode is the right pick for consumers that want exactly one
+device's tree on a multi-publisher broker — wildcard would re-introduce
+multi-panel scope creep at the application layer, and single-device would
+see the root and none of its children. As the publisher mutates the tree
+(`Device(parent=...)` to add, `child.delete()` to remove), descendants are
+subscribed or dropped on the parent's next init→ready transition.
+
 ## Module Structure
 
 ```

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/README.md

@@ -101,6 +101,28 @@ for root in roots:
         print(f'{descendant.device_id}: {controller.get_effective_state(descendant.device_id)}')
 ```
 
+Three controller discovery modes select what the controller listens for:
+
+```python
+# Wildcard (default) — every device on the broker
+Controller(mqtt_cfg=cfg)
+
+# Single-device — subscribe to exactly one device, no children, no wildcards
+Controller(mqtt_cfg=cfg, device_id='panel-1')
+
+# Tree-rooted — subscribe to a root and auto-subscribe to its descendants
+# as they're announced; subscription changes are gated on the parent's
+# $state init→ready edge per the Homie 5 spec.
+Controller(mqtt_cfg=cfg, root_device_id='panel-1')
+```
+
+Tree-rooted mode is the right pick for consumers that want exactly one
+device's tree on a multi-publisher broker — wildcard would re-introduce
+multi-panel scope creep at the application layer, and single-device would
+see the root and none of its children. As the publisher mutates the tree
+(`Device(parent=...)` to add, `child.delete()` to remove), descendants are
+subscribed or dropped on the parent's next init→ready transition.
+
 ## Module Structure
 
 ```

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ebus-sdk"
-version = "0.2.2"
+version = "0.3.1"
 description = "Python SDK for Homie MQTT Convention (eBus)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-    "ebus-mqtt-client>=0.1.2",
+    "ebus-mqtt-client>=0.1.6",
     "paho-mqtt>=1.5.0",
 ]
 

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/setup.py

@@ -13,7 +13,7 @@ from setuptools import setup
 
 setup(
     name="ebus-sdk",
-    version="0.1.10",
+    version="0.3.1",
     package_dir={"": "src"},
     packages=["ebus_sdk"],
 )

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/src/ebus_sdk/__init__.py

@@ -43,7 +43,7 @@ from .property import (
 # MQTT client
 from ebus_mqtt_client import MqttClient
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"
 
 __all__ = [
     # Homie classes

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/src/ebus_sdk/homie.py

@@ -1704,24 +1704,51 @@ class Controller:
         homie_domain: str = EBUS_HOMIE_DOMAIN,
         auto_start: bool = False,
         device_id: Optional[str] = None,
+        root_device_id: Optional[str] = None,
         qos: int = EBUS_HOMIE_MQTT_QOS,
     ):
         """
         Initialize a Homie Controller
 
+        Three discovery modes are mutually exclusive:
+        - Wildcard (default): device_id=None, root_device_id=None — sees every
+          device on the broker by subscribing to {domain}/5/+/$state.
+        - Single-device: device_id=<id> — subscribes to exactly that device's
+          four topic patterns; no children, no wildcard in the device-id slot.
+        - Tree-rooted: root_device_id=<id> — starts at the named root, then
+          walks $description.children and subscribes to each descendant as it
+          announces. Subscription changes are gated on the parent's init→ready
+          state edge (per Homie 5: $state=ready is the trust signal).
+
         Args:
             mqtt_cfg: MQTT broker configuration (same format as Device class)
             homie_domain: Homie domain to monitor (default: 'ebus')
             auto_start: If True, automatically start discovery on init
             device_id: If set, subscribe only to this specific device (no wildcards)
+            root_device_id: If set, subscribe to this root and auto-subscribe to
+                its descendants as the tree is announced (SDK-o1h)
             qos: MQTT QoS level for all subscribe/publish operations (default: EBUS_HOMIE_MQTT_QOS)
         """
+        if device_id is not None and root_device_id is not None:
+            raise ValueError(
+                "device_id and root_device_id are mutually exclusive; "
+                "pick single-device mode (device_id) or tree-rooted mode (root_device_id)"
+            )
+
         self.homie_domain = homie_domain
         self.device_id = device_id
+        self.root_device_id = root_device_id
         self._qos = qos
         self._mqtt_cfg = mqtt_cfg
         self.mqttc = None
         self.devices = {}  # {device_id: DiscoveredDevice}
+        # Tree-rooted mode: {parent_device_id: set_of_subscribed_child_ids}.
+        # Authoritative record of what we've subscribed for under each parent,
+        # independent of any child's own description (which may not have
+        # arrived yet). Reconcile diffs against this rather than walking
+        # parent_id linkages so a pre-created-but-not-yet-described child
+        # doesn't look "missing" and get re-subscribed every reconcile.
+        self._subscribed_children: dict = {}
 
         # Callbacks
         self._on_device_discovered = None
@@ -1736,6 +1763,11 @@ class Controller:
         if auto_start:
             self.start_discovery()
 
+    @property
+    def is_tree_rooted(self) -> bool:
+        """True if this controller was created in tree-rooted mode (SDK-o1h)."""
+        return self.root_device_id is not None
+
     def _connect_broker(self) -> None:
         """Connect to MQTT broker"""
         if self.mqttc:
@@ -1759,20 +1791,37 @@ class Controller:
         return self._qos
 
     def _on_connect(self) -> None:
-        """Called when controller connects to MQTT broker"""
+        """Called when controller connects to MQTT broker.
+
+        MqttClient re-subscribes its own sub_callbacks dict on reconnect, so
+        topic-level recovery is already handled. In tree-rooted mode, the
+        controller's own bookkeeping (devices dict, current children) is reset
+        here so the retained $state/$description that paho delivers on the
+        fresh subscriptions drives a clean re-walk of the tree from the root,
+        identical to first-connect.
+        """
         logger.info("reason=controllerOnConnect")
-        # Re-subscribe to all topics on reconnect
-        if self.devices:
-            for device_id in self.devices.keys():
-                self._subscribe_to_device(device_id)
+        if self.is_tree_rooted:
+            # Cold restart of tree-rooted bookkeeping. paho-mqtt's MqttClient
+            # has already re-subscribed our root's four filters; retained
+            # state/description will arrive momentarily and the state-edge
+            # handler will reconcile descendants from scratch. Wipe the
+            # in-memory device registry so the init→ready edge sees the
+            # transition (the previous state would otherwise short-circuit it).
+            self.devices = {}
+            self._subscribed_children = {}
+            device = DiscoveredDevice(self.root_device_id, self.homie_domain)
+            self.devices[self.root_device_id] = device
 
     def start_discovery(self, homie_domain: Optional[str] = None) -> None:
         """
         Start auto-discovery of Homie devices
 
-        When device_id is set, subscribes to exact topics for that single device
-        (no wildcard in the device-id position). Otherwise, subscribes to the
-        wildcard discovery topic pattern: {domain}/5/+/$state
+        Behavior depends on the constructor-selected mode:
+        - root_device_id: tree-rooted — subscribe to root, then auto-subscribe
+          to descendants on the root's init→ready edge (SDK-o1h).
+        - device_id: single-device — subscribe to exact topics for that device.
+        - neither: wildcard — subscribe to {domain}/5/+/$state.
 
         Args:
             homie_domain: Optional specific domain to monitor (default: uses instance domain)
@@ -1783,46 +1832,56 @@ class Controller:
 
         domain = homie_domain or self.homie_domain
 
-        if self.device_id:
+        if self.is_tree_rooted:
+            logger.info(f"reason=startDiscoveryTreeRooted,rootDeviceID={self.root_device_id}")
+            # Pre-create the root entry; descendants are added as they're
+            # discovered via the parent's $description.children
+            device = DiscoveredDevice(self.root_device_id, domain)
+            self.devices[self.root_device_id] = device
+            self._subscribe_device_topics(self.root_device_id)
+        elif self.device_id:
             # Single-device mode: subscribe to exact topics, no wildcard
             # in the device-id position
-            base = f"{domain}/{EBUS_HOMIE_VERSION_MAJOR}/{self.device_id}"
             logger.info(f"reason=startDiscoverySingleDevice,deviceID={self.device_id}")
-
             # Pre-create the DiscoveredDevice entry
             device = DiscoveredDevice(self.device_id, domain)
             self.devices[self.device_id] = device
-
-            # Subscribe to $state
-            self.mqttc.subscribe(
-                f"{base}/$state",
-                param=self._on_state_message,
-                qos=self._qos,
-            )
-            # Subscribe to $description
-            self.mqttc.subscribe(
-                f"{base}/$description",
-                param=partial(self._on_description_message, self.device_id),
-                qos=self._qos,
-            )
-            # Subscribe to all properties: {base}/{node_id}/{property_id}
-            self.mqttc.subscribe(
-                f"{base}/+/+",
-                param=partial(self._on_property_message, self.device_id),
-                qos=self._qos,
-            )
-            # Subscribe to all property targets
-            self.mqttc.subscribe(
-                f"{base}/+/+/$target",
-                param=partial(self._on_target_message, self.device_id),
-                qos=self._qos,
-            )
+            self._subscribe_device_topics(self.device_id)
         else:
             # Wildcard discovery mode (original behavior)
             discovery_topic = f"{domain}/{EBUS_HOMIE_VERSION_MAJOR}/+/$state"
             logger.info(f"reason=startDiscovery,topic={discovery_topic}")
             self.mqttc.subscribe(discovery_topic, param=self._on_state_message, qos=self._qos)
 
+    def _subscribe_device_topics(self, device_id: str) -> None:
+        """Subscribe to the four exact-device topic patterns for device_id.
+
+        Used by single-device mode, tree-rooted mode (for the root and each
+        discovered descendant). The wildcard $state subscription path uses a
+        different shape and bypasses this.
+        """
+        base = f"{self.homie_domain}/{EBUS_HOMIE_VERSION_MAJOR}/{device_id}"
+        self.mqttc.subscribe(
+            f"{base}/$state",
+            param=self._on_state_message,
+            qos=self._qos,
+        )
+        self.mqttc.subscribe(
+            f"{base}/$description",
+            param=partial(self._on_description_message, device_id),
+            qos=self._qos,
+        )
+        self.mqttc.subscribe(
+            f"{base}/+/+",
+            param=partial(self._on_property_message, device_id),
+            qos=self._qos,
+        )
+        self.mqttc.subscribe(
+            f"{base}/+/+/$target",
+            param=partial(self._on_target_message, device_id),
+            qos=self._qos,
+        )
+
     def _on_state_message(self, topic: str, payload: bytes) -> None:
         """
         Handle device $state messages
@@ -1854,11 +1913,12 @@ class Controller:
         # New or existing device
         if device_id not in self.devices:
             # New device discovered (wildcard mode only; single-device mode
-            # pre-creates the entry in start_discovery)
+            # and tree-rooted mode pre-create their entries in start_discovery)
             logger.info(
                 f"reason=deviceDiscovered,deviceID={device_id},state={payload_str},knownDevices={list(self.devices.keys())}"
             )
             device = DiscoveredDevice(device_id, homie_domain)
+            old_state = None
             device.update_state(payload_str)
             self.devices[device_id] = device
 
@@ -1868,10 +1928,13 @@ class Controller:
             if self._on_device_discovered:
                 self._on_device_discovered(device)
         elif self.devices[device_id].state is None:
-            # Pre-created entry (single-device mode): first $state message
+            # Pre-created entry (single-device or tree-rooted mode):
+            # first $state message
             device = self.devices[device_id]
+            old_state = None
             device.update_state(payload_str)
-            logger.info(f"reason=deviceDiscovered,deviceID={device_id},state={payload_str},mode=singleDevice")
+            mode = "treeRooted" if self.is_tree_rooted else "singleDevice"
+            logger.info(f"reason=deviceDiscovered,deviceID={device_id},state={payload_str},mode={mode}")
             if self._on_device_discovered:
                 self._on_device_discovered(device)
         else:
@@ -1892,8 +1955,22 @@ class Controller:
                 device.update_state(payload_str)
                 logger.debug(f"reason=deviceStateRefreshed,deviceID={device_id},state={payload_str}")
 
+        # Tree-rooted mode: any device transitioning INTO ready is the trust
+        # signal to act on its $description.children. Per Homie 5, only the
+        # init→ready edge guarantees a consistent description; mid-flight
+        # description updates while state=init are stashed but not acted on.
+        if self.is_tree_rooted and payload_str == DeviceState.READY.value and old_state != DeviceState.READY.value:
+            self._reconcile_descendants(device_id)
+
     def _subscribe_to_device(self, device_id: str) -> None:
-        """Subscribe to all topics for a discovered device"""
+        """Subscribe to all topics for a discovered device (wildcard-mode helper).
+
+        Wildcard discovery hears a device's $state via the {domain}/5/+/$state
+        subscription; once it knows the device exists, it needs three more
+        filters (description, properties, targets) to track everything else.
+        Tree-rooted and single-device modes don't go through here — they call
+        _subscribe_device_topics directly to get all four filters at once.
+        """
         if not self.mqttc:
             return
 
@@ -1923,6 +2000,82 @@ class Controller:
             qos=self._qos,
         )
 
+    def _reconcile_descendants(self, device_id: str) -> None:
+        """Diff a device's announced children against what's subscribed (SDK-o1h).
+
+        Fired on the init→ready edge in tree-rooted mode. Added children get
+        full topic subscriptions (their own retained $state/$description then
+        cascade through this same handler, surfacing grandchildren). Removed
+        children are unsubscribed and dropped from the registry recursively.
+
+        The state-edge gate (in _on_state_message) guarantees we only act when
+        $state=ready confirms the description is current — never on a partial
+        view stashed during $state=init.
+        """
+        if not self.mqttc:
+            return
+        device = self.devices.get(device_id)
+        if device is None:
+            return
+
+        declared = set(device.children_ids)
+        current = set(self._subscribed_children.get(device_id, set()))
+
+        added = declared - current
+        removed = current - declared
+
+        for child_id in added:
+            logger.info(f"reason=treeRootedAddDescendant,parentID={device_id},childID={child_id}")
+            # Pre-create child entry; its own retained $state/$description
+            # arrive via the new subscriptions and drive update + cascade.
+            if child_id not in self.devices:
+                self.devices[child_id] = DiscoveredDevice(child_id, self.homie_domain)
+            self._subscribed_children.setdefault(device_id, set()).add(child_id)
+            self._subscribe_device_topics(child_id)
+
+        for child_id in removed:
+            logger.info(f"reason=treeRootedRemoveDescendant,parentID={device_id},childID={child_id}")
+            self._unsubscribe_and_drop(child_id)
+
+    def _unsubscribe_and_drop(self, device_id: str) -> None:
+        """Recursively drop a descendant and all of its own descendants (SDK-o1h).
+
+        Unsubscribes the four topic filters, removes the entry from the
+        registry, and fires on_device_removed (leaves-first so callbacks see a
+        consistent view: when fired for a parent, its children are already
+        gone). No-op if the device isn't tracked.
+        """
+        if device_id not in self.devices:
+            return
+        # Snapshot before mutating: collect this device's transitive
+        # descendants from our subscription registry (the authoritative record
+        # of what we subscribed for; doesn't depend on the child's own
+        # description having arrived). Recurse leaves-first.
+        children = list(self._subscribed_children.get(device_id, set()))
+        for child_id in children:
+            self._unsubscribe_and_drop(child_id)
+
+        # This device is no longer a parent in our tree
+        self._subscribed_children.pop(device_id, None)
+        # Remove this device from any parent's subscribed-children set
+        for siblings in self._subscribed_children.values():
+            siblings.discard(device_id)
+
+        device = self.devices.pop(device_id, None)
+        if device is None:
+            return
+
+        if self.mqttc:
+            base = f"{self.homie_domain}/{EBUS_HOMIE_VERSION_MAJOR}/{device_id}"
+            for suffix in ("$state", "$description", "+/+", "+/+/$target"):
+                self.mqttc.unsubscribe(f"{base}/{suffix}")
+
+        if self._on_device_removed:
+            try:
+                self._on_device_removed(device)
+            except Exception:
+                logger.exception(f"reason=onDeviceRemovedCallbackException,deviceID={device_id}")
+
     def _on_description_message(self, device_id: str, topic: str, payload: bytes) -> None:
         """Handle device $description messages"""
         if device_id not in self.devices:
@@ -1936,6 +2089,17 @@ class Controller:
         if self._on_description_received:
             self._on_description_received(device)
 
+        # SDK-gsn: on initial connect with retained state+description, $state
+        # often arrives before $description (we subscribe to $state first, and
+        # paho delivers in subscription order). The state-edge reconcile in
+        # _on_state_message then sees an empty children list and subscribes to
+        # nothing. Catch the late-arriving description here: when the device
+        # is already ready, run reconcile against the now-current description.
+        # Idempotent — a no-op when children are already subscribed, so safe
+        # in the design-intended order (description-then-state) too.
+        if self.is_tree_rooted and device.state == DeviceState.READY.value:
+            self._reconcile_descendants(device_id)
+
     def _on_property_message(self, device_id: str, topic: str, payload: bytes) -> None:
         """
         Handle property value messages
@@ -2160,6 +2324,7 @@ class Controller:
             self.mqttc = None
         # Release DiscoveredDevice objects and their property dicts
         self.devices.clear()
+        self._subscribed_children.clear()
         # Clear callback references to break reference cycles
         self._on_device_discovered = None
         self._on_device_state_changed = None

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1/src/ebus_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-sdk
-Version: 0.2.2
+Version: 0.3.1
 Summary: Python SDK for Homie MQTT Convention (eBus)
 Author: Clark Communications Corporation
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ebus-mqtt-client>=0.1.2
+Requires-Dist: ebus-mqtt-client>=0.1.6
 Requires-Dist: paho-mqtt>=1.5.0
 Provides-Extra: mdns
 Requires-Dist: zeroconf>=0.131.0; extra == "mdns"
@@ -131,6 +131,28 @@ for root in roots:
         print(f'{descendant.device_id}: {controller.get_effective_state(descendant.device_id)}')
 ```
 
+Three controller discovery modes select what the controller listens for:
+
+```python
+# Wildcard (default) — every device on the broker
+Controller(mqtt_cfg=cfg)
+
+# Single-device — subscribe to exactly one device, no children, no wildcards
+Controller(mqtt_cfg=cfg, device_id='panel-1')
+
+# Tree-rooted — subscribe to a root and auto-subscribe to its descendants
+# as they're announced; subscription changes are gated on the parent's
+# $state init→ready edge per the Homie 5 spec.
+Controller(mqtt_cfg=cfg, root_device_id='panel-1')
+```
+
+Tree-rooted mode is the right pick for consumers that want exactly one
+device's tree on a multi-publisher broker — wildcard would re-introduce
+multi-panel scope creep at the application layer, and single-device would
+see the root and none of its children. As the publisher mutates the tree
+(`Device(parent=...)` to add, `child.delete()` to remove), descendants are
+subscribed or dropped on the parent's next init→ready transition.
+
 ## Module Structure
 
 ```

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/src/ebus_sdk.egg-info/requires.txt

@@ -1,4 +1,4 @@
-ebus-mqtt-client>=0.1.2
+ebus-mqtt-client>=0.1.6
 paho-mqtt>=1.5.0
 
 [dev]

{ebus_sdk-0.2.2 → ebus_sdk-0.3.1}/tests/test_controller.py

@@ -354,7 +354,7 @@ class TestControllerEffectiveState:
 # ── Controller ───────────────────────────────────────────────────────────
 
 
-def _make_controller(mock_paho, device_id=None, auto_start=False):
+def _make_controller(mock_paho, device_id=None, auto_start=False, root_device_id=None):
     """Helper to create a Controller with mocked MQTT."""
     with patch("ebus_sdk.homie.MqttClient.from_config") as mock_from_config:
         mock_client = MagicMock()
@@ -365,6 +365,7 @@ def _make_controller(mock_paho, device_id=None, auto_start=False):
             mqtt_cfg={"host": "localhost", "port": 1883},
             auto_start=auto_start,
             device_id=device_id,
+            root_device_id=root_device_id,
         )
         return ctrl, mock_client
 
@@ -802,3 +803,416 @@ class TestControllerQoS:
         for c in mock_client.subscribe.call_args_list:
             _, kwargs = c
             assert kwargs["qos"] == 1
+
+
+# ── Controller tree-rooted mode (SDK-o1h) ────────────────────────────────
+
+
+def _push_state(ctrl, device_id, state):
+    """Push a $state retained message into the controller."""
+    ctrl._on_state_message(
+        f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/{device_id}/$state",
+        state.encode() if isinstance(state, str) else state,
+    )
+
+
+def _push_description(ctrl, device_id, description):
+    """Push a $description retained message into the controller."""
+    ctrl._on_description_message(
+        device_id,
+        f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/{device_id}/$description",
+        json.dumps(description).encode(),
+    )
+
+
+def _filters_for(device_id):
+    """The four exact-device topic filters subscribed for one device."""
+    base = f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/{device_id}"
+    return {
+        f"{base}/$state",
+        f"{base}/$description",
+        f"{base}/+/+",
+        f"{base}/+/+/$target",
+    }
+
+
+class TestTreeRootedInit:
+    def test_mutually_exclusive_with_device_id(self, mock_paho):
+        with pytest.raises(ValueError):
+            _make_controller(mock_paho, device_id="panel-1", root_device_id="panel-1")
+
+    def test_root_device_id_stored(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        assert ctrl.root_device_id == "panel-1"
+        assert ctrl.is_tree_rooted is True
+        assert ctrl.device_id is None
+
+    def test_wildcard_mode_not_tree_rooted(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho)
+        assert ctrl.is_tree_rooted is False
+
+    def test_single_device_mode_not_tree_rooted(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, device_id="panel-1")
+        assert ctrl.is_tree_rooted is False
+
+
+class TestTreeRootedStartDiscovery:
+    def test_subscribes_four_root_filters(self, mock_paho):
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+
+        topics = {c[0][0] for c in mock_client.subscribe.call_args_list}
+        assert topics == _filters_for("panel-1")
+
+    def test_pre_creates_root_entry(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+
+        assert "panel-1" in ctrl.devices
+        assert ctrl.devices["panel-1"].state is None
+
+    def test_no_wildcard_subscription(self, mock_paho):
+        """Tree-rooted mode must not subscribe to the broker-wide +/$state."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+
+        wildcard = f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/+/$state"
+        topics = [c[0][0] for c in mock_client.subscribe.call_args_list]
+        assert wildcard not in topics
+
+
+class TestTreeRootedBootstrap:
+    """Retained-state bootstrap: tree announces all-at-once on connect."""
+
+    def test_root_only_no_children(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # Retained $description (no children) + retained $state=ready
+        _push_description(ctrl, "panel-1", {"homie": "5.0"})
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert set(ctrl.devices.keys()) == {"panel-1"}
+
+    def test_root_with_children_subscribes_each(self, mock_paho):
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # Pretend retained $description arrives first (matches MQTT typical
+        # delivery order on a fresh subscription), then $state=ready.
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1", "evse-1"]})
+        mock_client.subscribe.reset_mock()
+        _push_state(ctrl, "panel-1", "ready")
+
+        # init→ready edge → reconcile → subscribe to each child's 4 filters
+        topics = {c[0][0] for c in mock_client.subscribe.call_args_list}
+        assert _filters_for("bess-1") <= topics
+        assert _filters_for("evse-1") <= topics
+        assert "bess-1" in ctrl.devices
+        assert "evse-1" in ctrl.devices
+
+    def test_grandchild_cascade(self, mock_paho):
+        """3-level tree bootstraps from the root via cascading state-edges."""
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # Root: parent of bess-1
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        # bess-1's retained state/desc arrive after subscription
+        _push_description(
+            ctrl,
+            "bess-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "panel-1",
+                "children": ["mid-1"],
+            },
+        )
+        _push_state(ctrl, "bess-1", "ready")
+        # mid-1's retained state/desc
+        _push_description(
+            ctrl,
+            "mid-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "bess-1",
+            },
+        )
+        _push_state(ctrl, "mid-1", "ready")
+
+        assert set(ctrl.devices.keys()) == {"panel-1", "bess-1", "mid-1"}
+
+    def test_discovery_callbacks_fire_per_descendant(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        discovered = []
+        ctrl.set_on_device_discovered_callback(lambda d: discovered.append(d.device_id))
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(
+            ctrl,
+            "bess-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "panel-1",
+            },
+        )
+        _push_state(ctrl, "bess-1", "ready")
+
+        assert discovered == ["panel-1", "bess-1"]
+
+
+class TestTreeRootedStateGate:
+    """init→ready edge gates reconcile; mid-init updates are stashed."""
+
+    def test_init_state_does_not_reconcile(self, mock_paho):
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # First message is init — no children should be subscribed
+        _push_state(ctrl, "panel-1", "init")
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        mock_client.subscribe.reset_mock()
+        # Another init refresh — still no reconcile
+        _push_state(ctrl, "panel-1", "init")
+
+        assert "bess-1" not in ctrl.devices
+        assert mock_client.subscribe.call_count == 0
+
+    def test_init_then_ready_reconciles(self, mock_paho):
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_state(ctrl, "panel-1", "init")
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert "bess-1" in ctrl.devices
+
+    def test_ready_to_ready_does_not_reconcile(self, mock_paho):
+        """A retained $state=ready republish (no edge) must not re-walk."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        # bess-1's tree is now subscribed; reset to see whether the next
+        # ready→ready refresh triggers any subscription churn.
+        mock_client.subscribe.reset_mock()
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert mock_client.subscribe.call_count == 0
+
+
+class TestTreeRootedDynamicAdd:
+    def test_mid_flight_child_addition(self, mock_paho):
+        """Parent re-enters init, gets new description with extra child,
+        returns to ready → new descendant is auto-subscribed."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # Initial steady-state with one child
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(
+            ctrl,
+            "bess-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "panel-1",
+            },
+        )
+        _push_state(ctrl, "bess-1", "ready")
+        mock_client.subscribe.reset_mock()
+
+        # Mid-flight: parent goes to init, new description includes evse-1
+        _push_state(ctrl, "panel-1", "init")
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1", "evse-1"]})
+        # No reconcile yet
+        assert "evse-1" not in ctrl.devices
+        # Parent returns to ready → reconcile fires
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert "evse-1" in ctrl.devices
+        topics = {c[0][0] for c in mock_client.subscribe.call_args_list}
+        # evse-1's 4 filters subscribed; bess-1's were not re-subscribed
+        assert _filters_for("evse-1") <= topics
+        assert _filters_for("bess-1").isdisjoint(topics)
+
+
+class TestTreeRootedDynamicRemove:
+    def test_child_removal_unsubscribes_and_fires_callback(self, mock_paho):
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        removed = []
+        ctrl.set_on_device_removed_callback(lambda d: removed.append(d.device_id))
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1", "evse-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(ctrl, "bess-1", {"homie": "5.0", "root": "panel-1", "parent": "panel-1"})
+        _push_state(ctrl, "bess-1", "ready")
+        _push_description(ctrl, "evse-1", {"homie": "5.0", "root": "panel-1", "parent": "panel-1"})
+        _push_state(ctrl, "evse-1", "ready")
+
+        # Reset only AFTER full steady-state, so we see only the unsub for evse-1
+        mock_client.unsubscribe.reset_mock()
+
+        # Parent drops evse-1 mid-flight
+        _push_state(ctrl, "panel-1", "init")
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert "evse-1" not in ctrl.devices
+        assert "bess-1" in ctrl.devices
+        assert removed == ["evse-1"]
+        # 4 unsubscribe calls for evse-1's four filters
+        unsub_topics = {c[0][0] for c in mock_client.unsubscribe.call_args_list}
+        assert unsub_topics == _filters_for("evse-1")
+
+    def test_grandchild_dropped_recursively(self, mock_paho):
+        """Removing a middle device drops its descendants too."""
+        ctrl, _ = _make_controller(mock_paho, root_device_id="panel-1")
+        removed = []
+        ctrl.set_on_device_removed_callback(lambda d: removed.append(d.device_id))
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(
+            ctrl,
+            "bess-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "panel-1",
+                "children": ["mid-1"],
+            },
+        )
+        _push_state(ctrl, "bess-1", "ready")
+        _push_description(
+            ctrl,
+            "mid-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "bess-1",
+            },
+        )
+        _push_state(ctrl, "mid-1", "ready")
+
+        # Parent drops bess-1 — mid-1 must go too
+        _push_state(ctrl, "panel-1", "init")
+        _push_description(ctrl, "panel-1", {"homie": "5.0"})
+        _push_state(ctrl, "panel-1", "ready")
+
+        assert "bess-1" not in ctrl.devices
+        assert "mid-1" not in ctrl.devices
+        # Leaves-first ordering: mid-1 fires before bess-1
+        assert removed == ["mid-1", "bess-1"]
+
+
+class TestTreeRootedDescriptionRace:
+    """SDK-gsn: retained $state=ready may arrive before retained $description.
+
+    paho delivers retained messages in subscription order, and we subscribe
+    to $state before $description in _subscribe_device_topics. So on initial
+    connect to a broker holding both retained, the state-edge reconcile in
+    _on_state_message can fire while the device's description is still None,
+    seeing zero children and subscribing to nothing. The fix re-runs reconcile
+    from _on_description_message when the device is already ready.
+    """
+
+    def test_state_before_description_still_reconciles(self, mock_paho):
+        """Retained $state=ready arrives FIRST, then $description with children."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        # State arrives first — at this moment description is None, reconcile
+        # finds zero children and is effectively a no-op.
+        _push_state(ctrl, "panel-1", "ready")
+        assert "bess-1" not in ctrl.devices
+        mock_client.subscribe.reset_mock()
+
+        # Description arrives second — must trigger a fresh reconcile that
+        # sees the now-current children list.
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1", "evse-1"]})
+
+        assert "bess-1" in ctrl.devices
+        assert "evse-1" in ctrl.devices
+        topics = {c[0][0] for c in mock_client.subscribe.call_args_list}
+        assert _filters_for("bess-1") <= topics
+        assert _filters_for("evse-1") <= topics
+
+    def test_description_only_acts_when_ready(self, mock_paho):
+        """A $description arriving while $state=init must NOT reconcile."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_state(ctrl, "panel-1", "init")
+        mock_client.subscribe.reset_mock()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+
+        # State is still init — description-driven reconcile must be gated
+        assert "bess-1" not in ctrl.devices
+        assert mock_client.subscribe.call_count == 0
+
+    def test_repeat_description_in_ready_is_idempotent(self, mock_paho):
+        """A second $description with unchanged children must not re-subscribe."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        # bess-1's tree is established — reset and re-deliver the same
+        # description (e.g. a controller resubscribe). No subscription churn.
+        mock_client.subscribe.reset_mock()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+
+        assert mock_client.subscribe.call_count == 0
+
+    def test_grandchild_race_via_intermediate(self, mock_paho):
+        """The race recurs at every level — bess-1's children list may also
+        arrive after its $state=ready. The same fix must cover descendants."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        # bess-1 announces ready first, description second
+        _push_state(ctrl, "bess-1", "ready")
+        assert "mid-1" not in ctrl.devices
+        mock_client.subscribe.reset_mock()
+        _push_description(
+            ctrl,
+            "bess-1",
+            {
+                "homie": "5.0",
+                "root": "panel-1",
+                "parent": "panel-1",
+                "children": ["mid-1"],
+            },
+        )
+
+        assert "mid-1" in ctrl.devices
+        topics = {c[0][0] for c in mock_client.subscribe.call_args_list}
+        assert _filters_for("mid-1") <= topics
+
+
+class TestTreeRootedReconnect:
+    def test_reconnect_resets_devices_and_rewalks(self, mock_paho):
+        """On reconnect: registry is reset; retained state re-cascades the tree."""
+        ctrl, mock_client = _make_controller(mock_paho, root_device_id="panel-1")
+        ctrl.start_discovery()
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(ctrl, "bess-1", {"homie": "5.0", "root": "panel-1", "parent": "panel-1"})
+        _push_state(ctrl, "bess-1", "ready")
+        assert "bess-1" in ctrl.devices
+
+        # Simulate reconnect: paho re-subscribes our filters; controller
+        # resets its registry so the retained ready triggers init→ready.
+        ctrl._on_connect()
+
+        # bess-1 is gone from the in-memory registry but root entry exists
+        assert set(ctrl.devices.keys()) == {"panel-1"}
+        assert ctrl.devices["panel-1"].state is None
+
+        # Retained $state/$description re-arrive on the recovered subscriptions
+        _push_description(ctrl, "panel-1", {"homie": "5.0", "children": ["bess-1"]})
+        _push_state(ctrl, "panel-1", "ready")
+        _push_description(ctrl, "bess-1", {"homie": "5.0", "root": "panel-1", "parent": "panel-1"})
+        _push_state(ctrl, "bess-1", "ready")
+
+        assert set(ctrl.devices.keys()) == {"panel-1", "bess-1"}