ebus-panel-sim 0.3.3__tar.gz → 0.4.0__tar.gz

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-08
+
+Adds bring-your-own-transport: a producer that already owns its MQTT connection can publish an eBus tree through it. Additive, so nothing existing changes; the minor bump reflects new public API rather than a break.
+
+The caller obligations are the part to read before using it. An injected client bypasses the SDK's connect path, so the Last Will and the on-(re)connect republish are yours to wire, and the emitter cannot do either on your behalf. `Notes on the bring-your-own-transport path` below states each one and what it costs to skip it; the README carries the wiring order as a recipe that the test suite executes from the file itself.
+
+### Added
+
+- **Bring-your-own-transport.** `Emitter(..., mqttc=client)` publishes the tree through a client the caller already owns, instead of having one built from `mqtt_cfg`. The two are mutually exclusive and passing both raises. This mirrors ebus-sdk's `Device(mqttc=...)` contract, and the case it serves is a host that cannot afford a second connection — a Home Assistant add-on, whose MQTT integration is `single_config_entry` and which forbids background threads (`ebus-mqtt-client` 0.4.0's `asyncio_driver()` covers pumping the loop). See the README's "Bring your own transport" section for the required wiring order, and the notes below for the behaviour that differs from the `mqtt_cfg` path.
+- **`Emitter.lwt_settings(manifest)`** returns the Last Will to register on a client you intend to inject. A `staticmethod` because it has to be answerable before an `Emitter` exists: the will rides the MQTT CONNECT packet, so it must be on the client before the client connects, which is before that client can be handed to a constructor. The descriptor comes from the SDK's own `Device.will()` — the same function the SDK passes as `lwt=` when it builds a client itself — so a caller-registered will is identical to an SDK-registered one rather than merely similar, and the shape drops into `MqttClient(lwt=...)` unchanged. Without it an injected tree has no will at all, and an unclean death leaves consumers reading a stale retained `ready` indefinitely.
+- **`Emitter.republish_tree()`** re-announces the whole retained tree, for wiring to an injected client's on-connect handler. The SDK registers this itself only for a client it built.
+
+### Fixed
+
+- **`stop(graceful=False)` left the root Device holding `ready` on an injected transport.** 0.3.3 moved the state before publishing but sourced that call through `owned_client()`, which returns None for a caller-supplied client, so the whole ungraceful teardown was a no-op there: object on `ready`, nothing on the wire. Latent in 0.3.3, because `mqttc=` did not exist to reach it; reachable the moment this release adds it. `set_state` now runs before the ownership split. This is the one entry here describing a defect in released code, and it could not be triggered by a 0.3.3 user.
+
+### Notes on the bring-your-own-transport path
+
+Behaviour that is specific to `mqttc=` and easy to get wrong. None of it is a change to the `mqtt_cfg` path, whose wire output is byte-identical to 0.3.3.
+
+- **`start()` does not wait, and there is nothing to wait for.** The SDK never starts a client it did not build, so polling `is_connected()` would stall the very event loop such a client is likely driven on without changing the outcome. Values are retained; the tree goes out on the first `publish_tick`.
+- **`stop()` never stops your client, on either path.** Ownership decides, not type — an injected client can itself be an `MqttClient`. It does still go mute: ebus-sdk's `Device.stop()` clears the root's transport reference regardless of ownership, so `republish_tree()` publishes nothing afterwards and an on-connect hook wired to it becomes a silent no-op on a still-live client. Build a new `Emitter` to resume.
+- **Nothing re-announces your tree unless you wire it.** The SDK registers its on-(re)connect republish inside `connect_broker()`, below an `if self.mqttc` early return that an injected client always takes. Measured against a real broker with the retained store wiped: an injected tree came back 5 topics of 56, every `$description` missing, where an owned one came back all 56. `republish_tree()` is the remedy; the README recipe wires it.
+- **Let your event loop turn before closing the client.** `stop(graceful=False)` queues the `lost` rather than flushing it — `wait_for_publish` would block the very thread that has to run `loop_write` for a client pumped by `asyncio_driver`. Closing the client in the same synchronous breath drops the message and leaves the retained tree on `ready`: deterministic, not a race. There is nothing to await; one turn of the loop is the whole remedy.
+
 ## [0.3.3] - 2026-08-07
 
 ### Fixed

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/DESIGN.md

@@ -19,6 +19,8 @@ The enclosure is a Homie root device (`energy.ebus.device.distribution-enclosure
 
 Placement is declarative. Each `wire/mapping/*.yaml` descriptor says whether its device class is the `root-device` or a `child-of-parent`; `graph_builder` walks the manifest, mappings, and profiles to build the SDK device graph, and the SDK's `Device` owns the `$state` cascade: `graph_builder` wraps each device's node/property build in a `state_transition()` that coalesces the description republish into a single `init` then `ready` cycle, while `Emitter.start()`/`stop()` drive connect and disconnect. A graceful `stop()` publishes only the root's `$state=disconnected` (by Homie's effective-state rule that covers every child); `stop(graceful=False)` publishes the root's `$state=lost` itself, because the registered LWT cannot deliver it (a will fires only on an *unclean* disconnect, and every teardown path here closes cleanly, deliberately, so an orderly shutdown is not reported as a crash); retained topics are cleared only when `stop(clear_retained=True)` is passed, which is graceful-only, since a producer that died clears nothing. The vendored `wire/profiles/*.json` are the schema (capabilities, properties, datatypes, units, `$format`, settability); `bag_builder` maps each profile-declared property to a snapshot accessor and fails loud at construction if any declared property has no source.
 
+That description assumes the emitter owns the connection. With an injected transport (`Emitter(mqttc=...)`) the same teardown still moves the root to `$state=lost` and publishes it, but three things move to the caller, because the emitter never starts or stops a client it did not build. The LWT is registered by the caller before they connect (`Emitter.lwt_settings(manifest)` answers it without an instance, since the will rides the CONNECT packet); the on-(re)connect whole-tree republish is wired by the caller (`Emitter.republish_tree`), the SDK registering its own only inside `connect_broker()`, below the `if self.mqttc` early return an injected client always takes; and the ungraceful `lost` is *queued* on the caller's loop rather than flushed, since flushing would block the thread running `loop_write`, so the caller must let the loop turn before closing the client. Absent the first, the tree has no will and an unclean death leaves consumers on a stale retained `ready`; absent the second, a broker that loses its retained store never gets the tree back.
+
 ## Native devices
 
 Two device classes are not pure publishers: their behaviour runs inside the emitter.

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-panel-sim
-Version: 0.3.3
+Version: 0.4.0
 Summary: Producer-side Homie publisher with embedded behaviour runtime for the eBus convention
 Project-URL: Homepage, https://ebus.energy
 Project-URL: Repository, https://github.com/electrification-bus/distribution-enclosure-simulator
@@ -148,10 +148,11 @@ def main() -> None:
     bess_cfg = BESSConfig(instance_id="abc-123-bess", nameplate_capacity_kwh=13.5,
                           max_charge_w=3500.0, max_discharge_w=3500.0)
 
-    # The emitter owns the MQTT connection: ebus-sdk builds the client from
-    # mqtt_cfg and sets the enclosure's LWT. Empty SetterRegistry -> the emitter
-    # installs internal default /set handlers; register your own before
-    # construction to override them.
+    # With mqtt_cfg the emitter owns the MQTT connection: ebus-sdk builds the
+    # client and sets the enclosure's LWT. (Injecting your own client instead
+    # moves both of those to you — see "Bring your own transport" below.)
+    # Empty SetterRegistry -> the emitter installs internal default /set
+    # handlers; register your own before construction to override them.
     emitter = Emitter(
         manifest, SetterRegistry(),
         mqtt_cfg={"host": "127.0.0.1", "port": 1883},
@@ -176,6 +177,53 @@ main()
 
 Read the most recently published state back through `emitter.last_snapshot`. `mqtt_cfg` is handed straight to ebus-sdk: beyond `host`/`port` it takes the ebus-mqtt-client TLS and authentication keys for secured brokers (e.g. broker-quickstart's mTLS `discovery`/`strict` profiles).
 
+### Bring your own transport
+
+A host that already owns an MQTT connection can publish through it instead of having a second one opened underneath: pass `Emitter(..., mqttc=client)` in place of `mqtt_cfg=`. The two are mutually exclusive. This mirrors ebus-sdk's own `Device(mqttc=...)`, and the case it exists for is a host like a Home Assistant add-on, whose MQTT integration is `single_config_entry` and which forbids background threads (`ebus-mqtt-client` 0.4.0's `asyncio_driver()` pumps paho's loop on yours).
+
+**The emitter never starts or stops a client it did not build.** Two things it consequently cannot do for you — register the Last Will, and re-announce the tree on reconnect — are automatic on the `mqtt_cfg` path and yours here. They are steps 1 and 4 below, and the order is forced rather than stylistic:
+
+```python
+from ebus_panel_sim import Emitter, SetterRegistry
+from ebus_mqtt_client import MqttClient
+
+# 1. The Last Will must exist before the client connects — it rides the CONNECT
+#    packet, so it cannot be attached afterwards. This is why it is a
+#    staticmethod: there is no Emitter yet, and cannot be.
+lwt = Emitter.lwt_settings(manifest)
+
+# 2. Build your client with it, still unconnected.
+client = MqttClient.from_config({"host": "127.0.0.1", "port": 1883}, client_id="my-host", lwt=lwt)
+
+# 3. Now the emitter, publishing through it.
+emitter = Emitter(manifest, SetterRegistry(), mqttc=client)
+
+# 4. Re-announce the whole tree on every (re)connect. Assigned after construction
+#    rather than passed to from_config, because the callback needs the emitter and
+#    the emitter needs the client. Invoked with no arguments.
+client.on_connect_callback = emitter.republish_tree
+
+# 5. You connect, not the emitter — it never starts a client it did not build.
+client.start()
+emitter.start()           # returns immediately; it has no connection to wait for
+```
+
+To pump paho on your own event loop instead of its background thread — the case a
+Home Assistant add-on needs — replace step 5's `client.start()` with the driver,
+which is `async` and mutually exclusive with `start()`:
+
+```python
+driver = client.asyncio_driver()   # must be called from inside a running loop
+await driver.start()
+emitter.start()
+```
+
+What each buys, and one obligation that is about timing rather than wiring. All three are silent when they bite:
+
+- **No will means no liveness signal.** Skip step 1 and the tree has no LWT at all: a host that dies leaves every consumer reading a stale retained `ready`, indefinitely. `stop(graceful=False)` publishes `$state=lost` itself, but that only covers an orderly teardown — the case where the process *didn't* die.
+- **No re-announce means the tree does not come back.** Skip step 4 and a broker that loses its retained store never sees the tree again; what returns is whatever later ticks happen to republish. Measured after wiping a real broker's retained store: 5 topics of 56, every `$description` missing.
+- **Let your loop turn before you close the client.** `stop(graceful=False)` *queues* the `lost` on your loop rather than flushing it — flushing would block the very thread that has to run `loop_write`. Closing the client in the same synchronous breath drops the message and leaves the retained tree on `ready`.
+
 ## Layout
 
 - `src/ebus_panel_sim/` — the package (`emitter.py`, `manifest.py`, `wire/` profiles + publishing, `native_devices/`); see [DESIGN.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DESIGN.md).

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/README.md

@@ -122,10 +122,11 @@ def main() -> None:
     bess_cfg = BESSConfig(instance_id="abc-123-bess", nameplate_capacity_kwh=13.5,
                           max_charge_w=3500.0, max_discharge_w=3500.0)
 
-    # The emitter owns the MQTT connection: ebus-sdk builds the client from
-    # mqtt_cfg and sets the enclosure's LWT. Empty SetterRegistry -> the emitter
-    # installs internal default /set handlers; register your own before
-    # construction to override them.
+    # With mqtt_cfg the emitter owns the MQTT connection: ebus-sdk builds the
+    # client and sets the enclosure's LWT. (Injecting your own client instead
+    # moves both of those to you — see "Bring your own transport" below.)
+    # Empty SetterRegistry -> the emitter installs internal default /set
+    # handlers; register your own before construction to override them.
     emitter = Emitter(
         manifest, SetterRegistry(),
         mqtt_cfg={"host": "127.0.0.1", "port": 1883},
@@ -150,6 +151,53 @@ main()
 
 Read the most recently published state back through `emitter.last_snapshot`. `mqtt_cfg` is handed straight to ebus-sdk: beyond `host`/`port` it takes the ebus-mqtt-client TLS and authentication keys for secured brokers (e.g. broker-quickstart's mTLS `discovery`/`strict` profiles).
 
+### Bring your own transport
+
+A host that already owns an MQTT connection can publish through it instead of having a second one opened underneath: pass `Emitter(..., mqttc=client)` in place of `mqtt_cfg=`. The two are mutually exclusive. This mirrors ebus-sdk's own `Device(mqttc=...)`, and the case it exists for is a host like a Home Assistant add-on, whose MQTT integration is `single_config_entry` and which forbids background threads (`ebus-mqtt-client` 0.4.0's `asyncio_driver()` pumps paho's loop on yours).
+
+**The emitter never starts or stops a client it did not build.** Two things it consequently cannot do for you — register the Last Will, and re-announce the tree on reconnect — are automatic on the `mqtt_cfg` path and yours here. They are steps 1 and 4 below, and the order is forced rather than stylistic:
+
+```python
+from ebus_panel_sim import Emitter, SetterRegistry
+from ebus_mqtt_client import MqttClient
+
+# 1. The Last Will must exist before the client connects — it rides the CONNECT
+#    packet, so it cannot be attached afterwards. This is why it is a
+#    staticmethod: there is no Emitter yet, and cannot be.
+lwt = Emitter.lwt_settings(manifest)
+
+# 2. Build your client with it, still unconnected.
+client = MqttClient.from_config({"host": "127.0.0.1", "port": 1883}, client_id="my-host", lwt=lwt)
+
+# 3. Now the emitter, publishing through it.
+emitter = Emitter(manifest, SetterRegistry(), mqttc=client)
+
+# 4. Re-announce the whole tree on every (re)connect. Assigned after construction
+#    rather than passed to from_config, because the callback needs the emitter and
+#    the emitter needs the client. Invoked with no arguments.
+client.on_connect_callback = emitter.republish_tree
+
+# 5. You connect, not the emitter — it never starts a client it did not build.
+client.start()
+emitter.start()           # returns immediately; it has no connection to wait for
+```
+
+To pump paho on your own event loop instead of its background thread — the case a
+Home Assistant add-on needs — replace step 5's `client.start()` with the driver,
+which is `async` and mutually exclusive with `start()`:
+
+```python
+driver = client.asyncio_driver()   # must be called from inside a running loop
+await driver.start()
+emitter.start()
+```
+
+What each buys, and one obligation that is about timing rather than wiring. All three are silent when they bite:
+
+- **No will means no liveness signal.** Skip step 1 and the tree has no LWT at all: a host that dies leaves every consumer reading a stale retained `ready`, indefinitely. `stop(graceful=False)` publishes `$state=lost` itself, but that only covers an orderly teardown — the case where the process *didn't* die.
+- **No re-announce means the tree does not come back.** Skip step 4 and a broker that loses its retained store never sees the tree again; what returns is whatever later ticks happen to republish. Measured after wiping a real broker's retained store: 5 topics of 56, every `$description` missing.
+- **Let your loop turn before you close the client.** `stop(graceful=False)` *queues* the `lost` on your loop rather than flushing it — flushing would block the very thread that has to run `loop_write`. Closing the client in the same synchronous breath drops the message and leaves the retained tree on `ready`.
+
 ## Layout
 
 - `src/ebus_panel_sim/` — the package (`emitter.py`, `manifest.py`, `wire/` profiles + publishing, `native_devices/`); see [DESIGN.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DESIGN.md).

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/src/ebus_panel_sim/__init__.py

@@ -63,13 +63,19 @@ from ebus_panel_sim.snapshot import (
     EbusPvSnapshot,
 )
 from ebus_panel_sim.tick_inputs import PanelEnvelopeTick, TickInputs
+
+# `Emitter(mqttc=...)` is public API typed with this, so the name has to be
+# nameable from here. Without it a downstream annotating what it passes must
+# import from `ebus_sdk` directly, which is exactly the coupling the wire seam
+# exists to spare it.
+from ebus_panel_sim.wire._sdk_seam import MqttDeviceTransport
 from ebus_panel_sim.wire.set_router import SetterHandler, SetterRegistry
 
 # Single source of truth for the distribution version: pyproject reads it from here
 # via `[tool.hatch.version]`, and publish.yml refuses to release when the git tag
 # disagrees. Bump it in this one place. Note this is the PACKAGE version and is
 # distinct from the producer-contract version the docstrings above refer to.
-__version__ = "0.3.3"
+__version__ = "0.4.0"
 
 __all__ = [
     "BESSConfig",
@@ -101,6 +107,7 @@ __all__ = [
     "ManifestPhysicsView",
     "ManifestValidationError",
     "MissingSetterError",
+    "MqttDeviceTransport",
     "NativeDevice",
     "NativeTickContext",
     "PanelEnvelopeTick",

{ebus_panel_sim-0.3.3 → ebus_panel_sim-0.4.0}/src/ebus_panel_sim/emitter.py

@@ -49,9 +49,14 @@ from ebus_panel_sim.snapshot import (
     EbusPvSnapshot,
 )
 from ebus_panel_sim.tick_inputs import TickInputs
-from ebus_panel_sim.wire._sdk_seam import owned_client, publish_will_now
+from ebus_panel_sim.wire._sdk_seam import (
+    MqttDeviceTransport,
+    owned_client,
+    publish_will_now,
+    will_for_root_id,
+)
 from ebus_panel_sim.wire.bag_builder import BagBuilder
-from ebus_panel_sim.wire.graph_builder import build_graph
+from ebus_panel_sim.wire.graph_builder import build_graph, root_instance_of
 from ebus_panel_sim.wire.mapping_loader import load_mapping_table
 from ebus_panel_sim.wire.profile_loader import Variant, load_profiles
 from ebus_panel_sim.wire.publisher import Publisher
@@ -74,12 +79,34 @@ class Emitter:
         setter_registry: SetterRegistry,
         *,
         mqtt_cfg: dict[str, Any] | None = None,
+        mqttc: MqttDeviceTransport | None = None,
         bess_configs: tuple[BESSConfig, ...] = (),
         load_shedding_config: LoadSheddingConfig | None = None,
         variant: Variant = "span",
     ) -> None:
         self._manifest = manifest
-        self._mqtt_cfg = dict(mqtt_cfg) if mqtt_cfg is not None else dict(_DEFAULT_MQTT_CFG)
+        # Bring-your-own-transport: a caller that already owns a connected client
+        # passes it as ``mqttc`` and the SDK publishes through it, never starting
+        # or stopping it. Mutually exclusive with ``mqtt_cfg``, which has the SDK
+        # build a client it owns.
+        #
+        # Registering the Last Will on an injected client is the CALLER'S job, and
+        # has to happen before they connect it: the will rides the MQTT CONNECT
+        # packet, so neither the SDK nor this emitter can attach one to a client
+        # handed over already connected (``Device.will()`` is exposed for exactly
+        # this, and returns the descriptor to register). Without it the tree can
+        # still reach ``$state=lost`` through ``stop(graceful=False)``, which
+        # publishes the same payload itself — but that covers orderly teardown
+        # only. A caller that wants a *dropped* process to show as lost, which is
+        # what a will is for, must register it.
+        if mqttc is not None and mqtt_cfg is not None:
+            raise EmitterStateError("Emitter takes mqtt_cfg= or mqttc=, not both")
+        self._mqttc = mqttc
+        self._owns_client = mqttc is None
+        if mqttc is not None:
+            self._mqtt_cfg = None
+        else:
+            self._mqtt_cfg = dict(mqtt_cfg) if mqtt_cfg is not None else dict(_DEFAULT_MQTT_CFG)
 
         # variant="span" (default) publishes the SPAN-faithful surface (status
         # diagnostics, read-only shed/policy, the legacy evse config); "reference"
@@ -88,9 +115,13 @@ class Emitter:
         self._mapping = load_mapping_table()
         self._mapping.validate_against(self._profiles)
 
-        # The root device owns the shared MQTT connection built from mqtt_cfg;
-        # children share it. Construction opens no socket (deferred to start()).
-        self._graph = build_graph(manifest, self._mapping, self._profiles, mqtt_cfg=self._mqtt_cfg)
+        # The root device holds the shared connection — built from mqtt_cfg, or
+        # the caller's when injected — and children publish through it either
+        # way. Construction opens no socket: an owned client connects in start(),
+        # an injected one is already the caller's to connect.
+        self._graph = build_graph(
+            manifest, self._mapping, self._profiles, mqtt_cfg=self._mqtt_cfg, mqttc=self._mqttc
+        )
         self._root = self._graph.devices[self._graph.root_id]
 
         # ---- native-device + physics state (must exist before internal /set
@@ -188,14 +219,104 @@ class Emitter:
                     )
                 )
 
-    def start(self, *, connect_timeout_s: float = 5.0) -> None:
-        """Open the MQTT connection and publish the retained device tree.
+    @staticmethod
+    def lwt_settings(manifest: DeviceManifest) -> dict[str, str]:
+        """The Last Will to register on a client you intend to inject.
+
+        A ``staticmethod`` taking the manifest, because it has to be answerable
+        *before* there is an ``Emitter`` to ask: the will rides the MQTT CONNECT
+        packet, so it must be on the client before the client connects, which is
+        before you can hand that client to a constructor. An instance method here
+        would be unusable by definition.
+
+        The root is derived from the same mapping table ``build_graph`` uses, so
+        the will names the device the tree will actually publish as, and the
+        descriptor itself comes from the SDK's ``Device.will()`` — the very
+        function the SDK passes as ``lwt=`` when it builds a client of its own.
+        A caller-registered will is therefore identical to an SDK-registered one
+        rather than merely similar.
+
+        The shape drops into ``MqttClient(lwt=...)`` unchanged. The full wiring,
+        in the order it has to happen::
+
+            from ebus_mqtt_client import MqttClient
 
-        ebus-sdk publishes each device's ``$description`` + ``$state`` and
-        subscribes the ``/set`` topics itself once the link comes up (on_connect
-        -> refresh_tree). We start the root's shared client and wait, bounded,
-        for the link so the first ``publish_tick`` lands live; publishing before
-        connect is still safe (values are retained and republished on connect)."""
+            from ebus_panel_sim import Emitter, SetterRegistry
+
+            lwt = Emitter.lwt_settings(manifest)
+            client = MqttClient.from_config(
+                {"host": "127.0.0.1", "port": 1883}, client_id="my-host", lwt=lwt
+            )
+            emitter = Emitter(manifest, SetterRegistry(), mqttc=client)
+            client.on_connect_callback = emitter.republish_tree
+            client.start()
+
+        ``on_connect_callback`` is assigned after construction rather than passed
+        to ``from_config`` because the callback needs the emitter and the emitter
+        needs the client; omitting it leaves the tree unable to come back after a
+        broker restart. See the README's "Bring your own transport" section for
+        what each step buys.
+
+        Without the will the tree has none at all on an injected transport, and an
+        ungraceful death leaves consumers reading a stale retained ``ready``
+        indefinitely. ``stop(graceful=False)`` covers only orderly teardown.
+        """
+        root = root_instance_of(manifest, load_mapping_table())
+        return will_for_root_id(root.instance_id)
+
+    def republish_tree(self) -> None:
+        """Re-announce the whole retained tree. Wire this to your client's
+        on-connect handler when you inject a transport.
+
+        For a client the SDK builds, it registers this itself inside
+        ``connect_broker()`` and every reconnect republishes automatically. That
+        registration sits *below* an ``if self.mqttc: return``, so an injected
+        client never reaches it — the SDK says as much, and asks the caller to
+        call it from their own on-connect handler.
+
+        Nothing else covers the gap. Retained values survive on the broker, but a
+        broker that loses its retained store (restart, eviction, a fresh
+        deployment) drops the tree, and only a re-announce brings it back. What
+        comes back without this is whatever later ticks happen to republish:
+        measured against a real broker, 5 topics of 56, with every
+        ``$description`` missing.
+        """
+        self._root.refresh_tree()
+
+    def start(self, *, connect_timeout_s: float = 5.0) -> None:
+        """Mark the emitter ready to publish; with ``mqtt_cfg=``, open the connection too.
+
+        The two paths differ in almost everything this method does, so the
+        summary above deliberately promises only what both deliver.
+
+        **Owned (``mqtt_cfg=``)** — opens the MQTT connection and publishes the
+        retained device tree. ebus-sdk publishes each device's ``$description`` +
+        ``$state`` and subscribes the ``/set`` topics itself once the link comes
+        up (on_connect -> refresh_tree). We start the root's shared client and
+        wait, bounded, for the link so the first ``publish_tick`` lands live;
+        publishing before connect is still safe, since values are retained and
+        the SDK's own on-connect hook republishes the tree.
+
+        **Injected (``mqttc=``)** — opens nothing and publishes nothing. The
+        caller connects their own client, and the tree goes out on the first
+        ``publish_tick``. Returns immediately; see the comment below for why
+        waiting would be wrong rather than merely pointless."""
+        if not self._owns_client:
+            # The caller owns the connection and its timing. Blocking here would
+            # stall the very loop an injected client is likely being driven on,
+            # and the SDK never starts a client it did not build, so there is
+            # nothing to wait for.
+            #
+            # Note what does NOT rescue an early publish here: the SDK registers
+            # its on-connect republish inside connect_broker(), which returns at
+            # `if self.mqttc` before reaching that registration for an injected
+            # client. So nothing republishes on reconnect unless the caller wired
+            # `republish_tree` themselves -- see that method, and the README's
+            # "Bring your own transport" wiring order. Measured against a real
+            # broker: after wiping the retained store, an injected tree came back
+            # 5 topics of 56, an owned one all 56.
+            self._started = True
+            return
         self._root.start_mqtt_client()
         deadline = time.monotonic() + connect_timeout_s
         while not self._root.is_connected() and time.monotonic() < deadline:
@@ -248,11 +369,25 @@ class Emitter:
         self._bess[instance_id].set_soe(soe_kwh)
 
     def stop(self, *, graceful: bool = True, clear_retained: bool = False) -> None:
-        """Tear down the MQTT connection.
-
-        Graceful (default): publish the root's ``$state=disconnected`` then stop
-        the shared client (ebus-sdk's bounded teardown; per Homie's
-        effective-state rule the root going disconnected covers every child).
+        """Take the tree down. With ``mqtt_cfg=``, tear down the connection too.
+
+        Graceful (default): publish the root's ``$state=disconnected``; per
+        Homie's effective-state rule the root going disconnected covers every
+        child. For a client this emitter built, that is followed by ebus-sdk's
+        bounded teardown, which stops it.
+
+        A caller-injected client is **never** stopped — the emitter did not build
+        it and may not be its only user. Two consequences a BYO caller has to
+        know, because neither is visible:
+
+        * The connection stays open and connected after this returns. Closing it
+          is yours to do, and yours to time (see the non-graceful note below).
+        * The emitter goes mute regardless. ebus-sdk's ``Device.stop()`` clears
+          the root's transport reference on both paths, so ``republish_tree()``
+          silently publishes nothing afterwards. If you wired it to your client's
+          on-connect handler, as the README's recipe does, that hook is still
+          attached to a live client and is now a no-op. Build a new ``Emitter``
+          to resume publishing.
 
         Non-graceful: leave the tree looking like a producer that died, by
         publishing the root's ``$state=lost`` retained before dropping the
@@ -268,13 +403,31 @@ class Emitter:
         waits on keepalive expiry. A consumer exercising the *retained* view sees
         the same thing either way; one exercising live will delivery does not.
 
+        **On an injected transport, let the loop turn before you close the
+        client.** The ``lost`` is queued on the caller's loop, not flushed — the
+        emitter cannot flush it, and would not want to: ``wait_for_publish``
+        blocks the very thread that has to run ``loop_write`` for a client pumped
+        by ``asyncio_driver``. Closing the client in the same synchronous breath
+        as this call therefore drops the message and leaves the retained tree on
+        ``ready``, deterministically. There is nothing to await: letting the loop
+        turn once before you close the client is the whole remedy.
+
         ``clear_retained`` additionally clears every device's retained values +
         ``$description`` before disconnecting, for a clean-slate re-run. It
         applies to the graceful path only, since a producer that died clears
         nothing."""
         if not graceful:
-            publish_will_now(self._root)
-            client = owned_client(self._root.mqttc)
+            # Only ever stop a client this emitter had built for it. Stopping an
+            # injected one would tear down a connection the caller owns and may
+            # be using for other things. Ownership is what decides, not the type:
+            # an injected client can itself be an ``MqttClient`` (a caller driving
+            # one on its own event loop via ``asyncio_driver``), so the narrowing
+            # below only makes the ``stop()`` call well-typed.
+            client = owned_client(self._root.mqttc) if self._owns_client else None
+            # Before the stop, not after: an owned client's connection is gone
+            # once it returns. The injected path publishes too — see
+            # ``publish_will_now``, which is where the two differ.
+            publish_will_now(self._root, owned=client)
             if client is not None:
                 client.stop()
             return

ebus_panel_sim-0.4.0/src/ebus_panel_sim/wire/_sdk_seam.py

@@ -0,0 +1,169 @@
+"""Internal seam over ebus_sdk property construction.
+
+Localises Property construction so a future SDK change to the property-dict
+shape touches one file. NOT an abstraction layer: other modules hold and mutate
+``ebus_sdk.Property`` instances directly (the publisher calls ``Property.set_value``;
+the SDK owns ``/set`` decode and value encoding).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import ebus_sdk
+from ebus_sdk import (
+    EBUS_HOMIE_MQTT_QOS,
+    DeviceState,
+    MqttClient,
+    MqttDeviceTransport,
+    PropertyDatatype,
+    Unit,
+)
+
+# Re-exported so ``emitter.py`` can name the injection point's type without
+# importing ebus_sdk itself, which is the property this seam exists to preserve.
+__all__ = [
+    "MqttDeviceTransport",
+    "make_property",
+    "owned_client",
+    "publish_will_now",
+    "will_for_root_id",
+]
+
+
+def make_property(
+    *,
+    node: ebus_sdk.Node,
+    key: str,
+    name: str,
+    datatype: PropertyDatatype,
+    unit: Unit | None,
+    format_str: str | None,
+    settable: bool,
+) -> ebus_sdk.Property:
+    """Construct an ebus_sdk.Property from a profile property and attach it to a node."""
+    spec: dict[str, Any] = {
+        "id": key,
+        "name": name,
+        "datatype": datatype,
+    }
+    if unit is not None:
+        spec["unit"] = unit
+    if format_str is not None:
+        spec["format"] = format_str
+    if settable:
+        spec["settable"] = True
+    return node.add_property_from_dict(spec)
+
+
+def owned_client(mqttc: object) -> MqttClient | None:
+    """Return *mqttc* when it is a client the SDK built and therefore owns.
+
+    ebus-sdk 0.18 narrowed the injected-transport contract: ``MqttDeviceTransport``
+    deliberately omits ``start`` / ``stop``, because those resolve only on the
+    concrete client the SDK constructs for an ``mqtt_cfg=`` root — never on one the
+    caller injected and still owns. The SDK makes the same distinction internally
+    (``Controller.stop`` stops via its owned handle, "never via self.mqttc").
+
+    Narrowing to the concrete class states that rule in the types instead of
+    assuming it: a bring-your-own-transport root returns None here and is left for
+    its owner to stop, which is the behaviour the SDK's contract asks for.
+    """
+    return mqttc if isinstance(mqttc, MqttClient) else None
+
+
+def will_for_root_id(root_id: str) -> dict[str, str]:
+    """The Last Will descriptor for a tree rooted at *root_id*, before any tree exists.
+
+    A bring-your-own-transport caller has to register the will on their client
+    *before connecting*, because it rides the CONNECT packet — which is earlier
+    than they can hand that client to an ``Emitter``, and earlier than there is a
+    root ``Device`` to ask. So this answers the question from the id alone.
+
+    It does so by building a throwaway transport-free ``Device`` and returning its
+    own ``will()``, rather than formatting the topic here. Construction opens no
+    socket, and sourcing the descriptor from the SDK function that the SDK itself
+    registers (``connect_broker`` passes ``lwt=self.will()``) is what makes a
+    caller-registered will provably identical to an SDK-registered one. Formatting
+    the topic locally would be the same string today and a silent divergence the
+    day the SDK changes it.
+
+    The shape is ``Device.will()``'s and therefore ``MqttClient(lwt=...)``'s, so
+    it drops straight in where either is expected.
+    """
+    return ebus_sdk.Device(root_id).will()
+
+
+def publish_will_now(root: ebus_sdk.Device, *, owned: MqttClient | None) -> bool:
+    """Publish the root's will payload (``$state=lost``) as a retained message, now.
+
+    A Last Will fires only when the broker sees an UNCLEAN disconnect. Every
+    orderly teardown path here sends a clean DISCONNECT, and ebus-mqtt-client does
+    that deliberately (``MqttClient.stop`` -> ``mqttc.disconnect()``), precisely so
+    a normal shutdown is not reported to consumers as a crash. The consequence is
+    that a simulator asked to *act* like a producer that died cannot get there by
+    letting the will fire: it has to publish the will's own payload itself.
+
+    Topic and payload come from ``Device.will()``, the same descriptor the SDK
+    registers as the LWT, so this cannot drift from what a real will would have
+    delivered.
+
+    QoS deliberately follows the rest of the tree's ``$state`` publishes rather
+    than the ``qos=0`` default the will registration uses: a registered will is
+    delivered by the broker from its own state, whereas this goes out over a live
+    connection that is about to close and has to actually land first.
+
+    ``set_state`` moves the root's own state to ``LOST`` first, mirroring what
+    ``Device.stop()`` does for ``DISCONNECTED``. Publishing a state the device
+    object does not itself hold leaves the two disagreeing, and anything that later
+    re-announces from that object (``refresh_tree()``, which the SDK asks a
+    bring-your-own-transport caller to wire onto their client's on-connect handler)
+    republishes ``ready`` straight over the ``lost`` we just sent.
+
+    It runs before the ownership split rather than after, because that
+    re-announce is only *reachable* on the injected path. An owned client's
+    connection closes immediately behind this call, so nothing survives to
+    re-announce from; a caller-supplied one stays up, reconnects, and does. Both
+    paths need the state moved, and the path that needs it most is the one an
+    ownership guard would have skipped.
+
+    ``set_state`` also publishes ``$state`` itself, retained and at the device's
+    QoS, through whichever transport the root holds — so on an injected transport
+    that one call is the entire job, and nothing follows it here.
+
+    An earlier revision added an explicit ``transport.publish`` after it, to hand
+    the caller a paho ``MQTTMessageInfo`` to wait on. That is removed, because it
+    was a byte-identical duplicate of what ``set_state`` had just sent and the
+    handle it produced was unusable: waiting on it from the loop thread blocks for
+    the full timeout and never completes, which is the same reason
+    ``publish_and_flush`` is wrong on this path. Publishing twice to widen a
+    window the caller cannot observe is not a service to them.
+
+    The owned path does still repeat the value, for a different and real reason:
+    ``set_state`` goes through the ordinary unflushed path, the socket closes
+    immediately behind this function, and only a flushed publish is guaranteed to
+    land first.
+
+    **Caller obligation on an injected transport.** The ``lost`` is *queued* on
+    the caller's loop, not flushed, and the emitter cannot flush it for them.
+    Tearing the client down in the same synchronous breath as
+    ``stop(graceful=False)`` drops it — measured as deterministic against a real
+    broker with an ``asyncio_driver``-pumped client: an immediate ``driver.stop()``
+    leaves the retained root at ``ready``, while letting the loop turn first
+    leaves it at ``lost``. Letting the loop turn is the whole remedy; there is
+    nothing to await.
+
+    Returns whether the ``lost`` is on the wire as far as this function can tell:
+    for an owned client, whether the flush completed; for an injected one,
+    whether ``set_state`` moved the state and published (False when it was
+    already ``LOST``, in which case the wire already carries it).
+    """
+    moved = root.set_state(DeviceState.LOST)
+    if owned is None:
+        return moved
+    will = root.will()
+    return bool(
+        owned.publish_and_flush(
+            will["topic"], will["payload"], qos=EBUS_HOMIE_MQTT_QOS, retain=True
+        )
+    )