homie: type the Device injection point with MqttDeviceTransport

Follow-up to #14, on top of #12's MqttTransport base. Adds a Device-side
structural type and mirrors #12's owned/injected client split onto Device, so
"the SDK never starts or stops a client it did not build" is enforced by the
types rather than a convention.

- transport.py: MqttDeviceTransport(MqttTransport) adds is_connected + is_running
  (the members the device publish path reads); omits start/stop/publish_and_flush,
  which are owned-only. Exported from ebus_sdk.
- Device.mqttc is retyped Optional[MqttDeviceTransport]; the SDK-built client is
  kept on a separate Device._owned_client (concrete MqttClient), and every
  owned-only call (start/stop/publish_and_flush, incl. Property.start_mqtt_client)
  routes through it. get_mqtt_client() returns the transport type.

+4 tests (MqttDeviceTransport protocol + the _owned_client handle). Full suite
and ruff green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dcj

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to `ebus-sdk` are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- `MqttDeviceTransport`: the structural (`Protocol`) type for a client injected into a root `Device`, re-exported from `ebus_sdk`. It derives from the shared `MqttTransport` base (`publish` + `subscribe`) and adds `is_connected` + `is_running`, the members the device publish path reads; it omits `start` / `stop` / `publish_and_flush`, which are owned-only. `Device`'s `mqttc=` parameter is now annotated with it instead of the concrete `MqttClient` (parallel to `Controller`'s `MqttControllerTransport`), so a consumer injecting its own client type-checks once `ebus-mqtt-client` ships `py.typed` (today `MqttClient` resolves to `Any`, so injection already type-checks; the protocol keeps it working past that release). The SDK keeps the client it builds on a separate `Device._owned_client` handle, so the owned-only lifecycle methods resolve on the concrete type and "the SDK never starts or stops a client it did not build" is enforced by the types rather than a convention. Additive.
 - `Device` bring-your-own-transport: `Device(..., mqttc=<client>)` accepts a pre-built MQTT client instead of constructing one from `mqtt_cfg`, so a host that already owns its MQTT connection (e.g. a Home Assistant integration, whose MQTT integration is `single_config_entry` and forbids background threads) can publish an eBus device tree over its own transport and event loop. This is the producer-side mirror of the `Controller` seam added in 0.13.0. An injected client is used as-is: the SDK never `start()`s or `stop()`s it, and `stop()` publishes a final retained `$state=disconnected` through it and returns without flushing or closing (non-blocking on the caller's loop). Root-only, and mutually exclusive with `mqtt_cfg=` / `parent=`. Property publishing now gates on connectivity (`is_connected()`) rather than only the SDK-owned run flag, so a caller-driven client that never calls the SDK's `start()` still publishes property values (owned behavior is unchanged: there, connected implies running). Because an injected client bypasses the SDK's connect path (where the LWT, the reconnect republish, and the disconnect hook are wired), the caller wires the Homie-correctness pieces itself using `Device.will()` and `Device.refresh_tree()` (below); `on_disconnect=` is inert for an injected client (documented, and warned at construction). Additive: the default (no `mqttc`) path constructs, starts, owns, and stops a client exactly as before. Thanks to @cayossarian (GH #7). (#14)
 - `Device.will()`: returns the tree root's Last Will and Testament descriptor (topic ending in `/$state`, payload `lost`), exposed so a bring-your-own-transport caller can set it on their client before connecting: the will rides the MQTT CONNECT packet, so the SDK cannot add it to a client it is merely handed. The SDK uses it for any client it builds. `Device.refresh_tree()` (which republishes the whole tree) is documented as the companion on-connect hook a BYO caller wires so the retained tree re-announces after a reconnect. Additive. (#13)
 - `Controller.resync()`: the tree-rooted discovery bookkeeping reset, extracted from the owned-client on-connect handler and made public so a bring-your-own-transport tree-rooted controller can re-walk the tree from a broker reconnect it drives itself (an injected client bypasses the SDK's on-connect, where the reset is otherwise wired). A no-op in wildcard and single-device modes. Additive. (#13)

src/ebus_sdk/__init__.py

@@ -79,7 +79,7 @@
 from ebus_mqtt_client import MqttClient
 
 # Structural types for a caller-supplied MQTT client
-from ebus_sdk.transport import MqttControllerTransport, MqttTransport
+from ebus_sdk.transport import MqttControllerTransport, MqttDeviceTransport, MqttTransport
 
 __version__ = "0.15.0"
 
@@ -135,4 +135,5 @@
     "MqttClient",
     "MqttTransport",
     "MqttControllerTransport",
+    "MqttDeviceTransport",
 ]

src/ebus_sdk/homie.py

@@ -62,7 +62,7 @@ class StrEnum(str, Enum):
 from typing import Any, Callable, List, Optional, Type, Union
 from ebus_mqtt_client import MqttClient
 
-from ebus_sdk.transport import MqttControllerTransport
+from ebus_sdk.transport import MqttControllerTransport, MqttDeviceTransport
 
 # Optional: JSONSchema validation of a `json` property's `$format`. Kept optional
 # (see `ebus-sdk[validation]`) so a constrained build can omit it; absent it,
@@ -667,7 +667,7 @@ def datatype(self) -> str:
         logger.debug(f"reason=getDatatype,datatype={datatype}")
         return datatype
 
-    def get_mqtt_client(self) -> MqttClient:
+    def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
         """
         Who calls this function, and why?
         """
@@ -689,16 +689,17 @@ def start_mqtt_client(self) -> None:
             logger.warning(f"reason=propertyStartMqttClientNoMqttClient,propertyID={self._id}")
             return
         # Never start a caller-owned client (bring-your-own-transport): mirror the
-        # ownership guard on Device.start_mqtt_client(). Resolve the root via
-        # node -> device -> root; an incomplete chain falls through as owned.
+        # ownership guard on Device.start_mqtt_client(), and start via the concrete
+        # owned handle (start() is owned-only, off the MqttDeviceTransport surface).
+        # Resolve the root via node -> device -> root; an incomplete chain is a no-op.
         node = self.node()
         device = node.device() if node else None
         root = device.root() if device else None
-        if root is not None and not root._owns_client:
+        if root is None or not root._owns_client or root._owned_client is None:
             return
         try:
-            if not mqttc.is_running:
-                mqttc.start()
+            if not root._owned_client.is_running:
+                root._owned_client.start()
         except Exception as e:
             logger.warning(f"reason=propertyStartMqttClientException,e={e}")
 
@@ -1056,7 +1057,7 @@ def device(self) -> Device:
     def set_device(self, device: Device) -> None:
         self._device = device
 
-    def get_mqtt_client(self) -> MqttClient:
+    def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
         device = self.device()
         if not device:
             logger.warning(f"reason=nodeGetMqttClientNoDevice,nodeID={self._id}")
@@ -1289,7 +1290,7 @@ def __init__(
         extensions: Optional[List] = None,
         description_extras: Optional[dict] = None,
         mqtt_cfg: Optional[dict] = None,
-        mqttc: Optional[MqttClient] = None,
+        mqttc: Optional[MqttDeviceTransport] = None,
         qos: int = EBUS_HOMIE_MQTT_QOS,
         on_disconnect: Optional[Callable[[bool], None]] = None,
     ):
@@ -1324,8 +1325,13 @@ def __init__(
         # Controller's bring-your-own-transport seam). mqttc=None is the owned path
         # (the SDK builds the client from mqtt_cfg) or transport-free (mqtt_cfg=None,
         # no socket). Only the root holds a client; children read root._owns_client.
-        self.mqttc = mqttc
+        self.mqttc: Optional[MqttDeviceTransport] = mqttc
         self._owns_client = mqttc is None
+        # The SDK-constructed client, kept as its concrete type so start() / stop() /
+        # publish_and_flush() -- which exist only on a client we own -- stay callable.
+        # Stays None for an injected client, which makes "never started, never stopped"
+        # a property of the types rather than a promise in a comment (mirrors Controller).
+        self._owned_client: Optional[MqttClient] = None
         self._state = None
         self._qos = qos
         # Optional consumer hook: called on the ROOT's MQTT (dis)connect. Only a
@@ -1487,7 +1493,7 @@ def nodes(self) -> dict:
         """
         return self._nodes
 
-    def get_mqtt_client(self) -> MqttClient:
+    def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
         """
         Return the MQTT client for this device's tree.
         For root devices, returns self.mqttc. For children, ascends to root.
@@ -1510,8 +1516,10 @@ def start_mqtt_client(self) -> None:
             # Bring-your-own-transport: the caller owns the client's lifecycle, so
             # the SDK never starts it (it is expected to be connected already).
             return
-        if not root.mqttc.is_running:
-            root.mqttc.start()
+        # Owned path: start via the concrete handle (start() is owned-only, off the
+        # MqttDeviceTransport surface). _owned_client is set whenever _owns_client is True.
+        if root._owned_client is not None and not root._owned_client.is_running:
+            root._owned_client.start()
 
     def is_connected(self) -> bool:
         """
@@ -1566,8 +1574,8 @@ def stop(self, *, flush_timeout: float = 1.0, stop_timeout: float = 2.0) -> None
         if mqttc.is_connected():
             root._state = DeviceState.DISCONNECTED
             state_topic = f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/{root._id}/$state"
-            if root._owns_client:
-                flushed = mqttc.publish_and_flush(
+            if root._owns_client and root._owned_client is not None:
+                flushed = root._owned_client.publish_and_flush(
                     state_topic, DeviceState.DISCONNECTED.value, qos=root._qos, retain=True, timeout=flush_timeout
                 )
                 logger.info(f"reason=deviceStopDisconnectedPublished,id={root._id},flushed={flushed}")
@@ -1581,9 +1589,10 @@ def stop(self, *, flush_timeout: float = 1.0, stop_timeout: float = 2.0) -> None
                 logger.info(f"reason=deviceStopDisconnectedPublishedInjected,id={root._id}")
         else:
             logger.info(f"reason=deviceStopBrokerUnreachable,id={root._id}")
-        if root._owns_client:
-            mqttc.stop(timeout=stop_timeout)
+        if root._owns_client and root._owned_client is not None:
+            root._owned_client.stop(timeout=stop_timeout)
         root.mqttc = None
+        root._owned_client = None
 
     def description(self) -> dict:
         """
@@ -2111,13 +2120,18 @@ def connect_broker(self) -> None:
             # If we already have a mqtt client, don't reconnect...
             return
         try:
-            self.mqttc = MqttClient.from_config(
+            # Bind to a local of the concrete type so start() / stop() resolve later:
+            # self.mqttc is MqttDeviceTransport, which deliberately has neither. Both
+            # references are set before any start(), so behavior is unchanged.
+            client = MqttClient.from_config(
                 mqtt_cfg=self._mqtt_cfg,
                 client_id=self._id,
                 lwt=self.will(),
                 on_connect_callback=partial(self.on_connect),
                 on_disconnect_callback=self._handle_disconnect,
             )
+            self._owned_client = client
+            self.mqttc = client
         except Exception:
             logger.exception(f"reason=deviceConnectBrokerFailed,id={self._id}")
             raise

src/ebus_sdk/transport.py

@@ -51,7 +51,27 @@ class MqttControllerTransport(MqttTransport, Protocol):
 
     ``is_connected``, ``is_running`` and ``publish_and_flush`` are absent because nothing on
     the ``Controller`` path calls them — they belong to the ``Device`` / ``Property`` path,
-    which has no injection point today.
+    which types its own injection point with ``MqttDeviceTransport`` below.
     """
 
     def unsubscribe(self, sub: str) -> object: ...
+
+
+@runtime_checkable
+class MqttDeviceTransport(MqttTransport, Protocol):
+    """What the SDK calls on a client injected into a root ``Device``.
+
+    ``MqttTransport`` plus ``is_connected()`` and the ``is_running`` attribute, which the
+    device publish path reads to gate publishing on connectivity. Like
+    ``MqttControllerTransport`` it omits ``start`` / ``stop`` (and ``publish_and_flush``):
+    those are owned-only and resolve on the concrete client the SDK builds
+    (``Device._owned_client``), never on an injected one, so the no-start/no-stop guarantee
+    is a property of the types rather than a promise in a comment.
+
+    This protocol has a data member (``is_running``), so use ``isinstance`` for runtime
+    checks; ``issubclass`` is unsupported for protocols with non-method members.
+    """
+
+    def is_connected(self) -> bool: ...
+
+    is_running: bool

tests/test_homie_device.py

@@ -1972,6 +1972,62 @@ def test_parent_and_empty_mqtt_cfg_are_mutually_exclusive(self, mock_paho):
             Device(id="circuit-1", parent=root, mqtt_cfg={})
 
 
+class TestMqttDeviceTransportProtocol:
+    """The Device injection point is typed by what the SDK calls on an injected client (#14).
+
+    MqttDeviceTransport = MqttTransport (publish/subscribe) + is_connected() + is_running.
+    It has a data member (is_running), so use isinstance, not issubclass.
+    """
+
+    def test_protocol_is_exported_from_the_package_root(self):
+        import ebus_sdk
+
+        assert "MqttDeviceTransport" in ebus_sdk.__all__
+        assert ebus_sdk.MqttDeviceTransport is not None
+
+    def test_a_minimal_client_is_a_valid_device_transport(self):
+        """publish / subscribe / is_connected / is_running is the whole injected-Device
+        contract. Deliberately no start / stop / publish_and_flush: the SDK never calls
+        those on an injected client, so a minimal client that lacks them still works."""
+        from ebus_sdk import MqttDeviceTransport
+
+        class Minimal:
+            is_running = True
+
+            def publish(self, topic, data, qos=1, retain=False):
+                return None
+
+            def subscribe(self, sub, param, qos=1):
+                return None
+
+            def is_connected(self):
+                return True
+
+        client = Minimal()
+        assert isinstance(client, MqttDeviceTransport)
+
+        device = Device(id="panel-1", type="dev.test", mqttc=client)
+        device.stop()  # must not reach start()/stop() on a client that has neither
+
+    def test_owned_client_handle_is_none_when_injected(self):
+        client = _mock_mqtt_client()
+        device = Device(id="panel-1", mqttc=client)
+        assert device._owned_client is None
+        device.start_mqtt_client()  # no-op for an injected client
+        client.start.assert_not_called()
+
+    def test_owned_client_handle_is_set_and_cleared_for_an_sdk_built_client(self):
+        with patch("ebus_sdk.homie.MqttClient.from_config") as mock_from_config:
+            client = _mock_mqtt_client()
+            client.is_connected.return_value = True
+            mock_from_config.return_value = client
+            device = Device(id="panel-1", mqtt_cfg={"host": "x"})
+            assert device._owned_client is client
+            device.stop()
+            client.stop.assert_called_once()  # stops via the owned handle
+            assert device._owned_client is None
+
+
 class TestDeviceWithoutTransport:
     """`mqtt_cfg=None` — the declared default — builds a device tree with no transport."""