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

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

@@ -2,6 +2,37 @@
 
 ## [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
+
+- **`stop(graceful=False)` published `$state=lost` but left the root Device still holding `ready`.** The wire and the object disagreed, so anything re-announcing from that object republished `ready` straight over the `lost`. It now goes through the SDK's public `Device.set_state(DeviceState.LOST)` first, mirroring what `Device.stop()` already does for `disconnected`. The flushed publish that follows is deliberately the same retained value a second time: `set_state` uses the ordinary unflushed path, and on the owned path the connection closes immediately behind the call, so only a flushed publish is guaranteed to land. Costs one message at teardown. The observable retained outcome is unchanged (confirmed against a real broker: `p1=lost`); what changes is that it now survives a subsequent re-announce. Two tests pin it, both failing against 0.3.2. Found by [@cayossarian](https://github.com/cayossarian) while building on this code in [#17](https://github.com/electrification-bus/distribution-enclosure-simulator/pull/17).
+
 ## [0.3.2] - 2026-08-07
 
 Metadata-only. No source changes, so the published tree and the public API are identical to 0.3.1; this release exists to get the packaging metadata below onto PyPI, where it only takes effect on a publish.

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.4.0}/CONTRIBUTING.md

@@ -39,6 +39,20 @@ Pull requests are welcome.
 - **Keep comments to a minimum.** The project style is self-explanatory code, with comments reserved for the non-obvious *why* (a spec quirk, a Homie nuance, a SPAN-variant deviation). Don't add comments that just restate the code.
 - One commit per logical change is fine; we don't require squash or any particular branch naming.
 
+## What "done" means
+
+This package is published to PyPI, and a PyPI upload can never be replaced. So an increment that lands behaviour and leaves its documentation for later is not a smaller version of the change: it is a release whose docs contradict its code, and the correction costs another release. Ship the whole thing.
+
+A change is done when, in the same PR:
+
+- **Prose it invalidates is fixed.** If a change makes a sentence in the README, `DESIGN.md`, `DEVELOPER.md`, or a docstring untrue, that sentence is part of the change. A new option whose README still describes the old single path is not finished.
+- **Types its signatures name are reachable.** A public parameter annotated with a type a caller cannot import from `ebus_panel_sim` forces them to depend on `ebus_sdk` directly, which is what the SDK seam exists to spare them.
+- **It carries its `CHANGELOG.md` entry**, under `[Unreleased]` or a version heading.
+- **New behaviour has a test that fails without it.** Say so in the PR, and say which. A test that passes against the previous commit is not evidence.
+- **Caller obligations are written down where the caller will look.** If correct use requires the caller to do something (wire a callback, set something before connecting, let an event loop turn), a `#` comment in our source does not reach them.
+
+Splitting a change is fine when the parts are genuinely independent, or when a decision is needed that only a maintainer can make. It is not fine as a way to defer the half that needs no decision. If you are unsure which you have, open the PR with the whole thing and let the review split it.
+
 ## Local development
 
 Python >= 3.11 (developed and CI-tested on 3.11 and 3.14), managed with [uv](https://docs.astral.sh/uv/). See [DEVELOPER.md](DEVELOPER.md) for the full guide.

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

@@ -17,7 +17,9 @@ The producer builds a `DeviceManifest` (identity plus physics keys per device) a
 
 The enclosure is a Homie root device (`energy.ebus.device.distribution-enclosure`); every circuit, lugs pair, and integrated DER (BESS, PV, EVSE, MID) is a separate child Homie device with `root` and `parent` back-references to the enclosure. Each device's properties are grouped into capability-typed nodes (`info`, `meter`, `switch`, `breaker`, `load-shed`, `pcs`, `connection`, `status`, `door`, `soc`, `shed`, `shed-forecast`, `grid`, `config`, `power-flows`), whose node `$type` is `energy.ebus.capability.<capability>`. A child device therefore publishes under its own topic root, for example `ebus/5/<circuit-id>/switch/relay` and `ebus/5/<bess-id>-mid/grid/islanding-state`.
 
-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); an ungraceful drop leaves the broker LWT to fire `$state=lost`; retained topics are cleared only when `stop(clear_retained=True)` is passed. 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.
+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
 

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.4.0}/DEVELOPER.md

@@ -131,13 +131,12 @@ distribution-enclosure-simulator/
       bag_builder.py           # Snapshot -> PropertyBag translator
       property_bag.py          # Per-tick property values + diff cache
       publisher.py             # Per-tick diff/publish loop
-      lifecycle.py             # $state, $description, /set subscription, LWT
       set_router.py            # Setter registry and /set dispatch
-      wire_paths.py            # Homie topic-template helpers
-      _sdk_seam.py             # Internal seam over ebus_sdk.property
+      _sdk_seam.py             # Internal seam over ebus_sdk (property build, owned-client narrowing, will publish)
       profiles/                # Vendored Homie 5 device profiles (JSON), per device type
       mapping/                 # Vendored mapping descriptors (YAML), per device type
-  tests/                       # pytest suite (asyncio auto; in-process amqtt broker)
+      catalogs/                # Vendored spec capability catalogs (JSON); the wire type contract
+  tests/                       # pytest suite; paho is patched, so no broker and no socket
     conftest.py
     conventions/               # convention tests
     wire/                      # wire-layer tests

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-panel-sim
-Version: 0.3.2
+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.2 → 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.2 → 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.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "BESSConfig",
@@ -101,6 +107,7 @@ __all__ = [
     "ManifestPhysicsView",
     "ManifestValidationError",
     "MissingSetterError",
+    "MqttDeviceTransport",
     "NativeDevice",
     "NativeTickContext",
     "PanelEnvelopeTick",

{ebus_panel_sim-0.3.2 → 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