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

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/.github/workflows/ci.yaml

@@ -3,8 +3,13 @@ name: CI
 on:
   push:
     branches: [main]
+  # Deliberately unfiltered by base branch. A `branches:` filter here means a PR
+  # targeting anything other than `main` gets no checks at all, silently: the PR
+  # simply reports "no checks reported" and reads as unvalidated rather than
+  # failing. That hides every stacked PR, which is exactly when a second pair of
+  # eyes is worth most. Every other repo in the eBus family already runs
+  # unfiltered; this one was the outlier.
   pull_request:
-    branches: [main]
 
 jobs:
   lint-and-test:

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

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [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.
+
+### Fixed
+
+- **The PyPI project page was blank.** `pyproject.toml` declared no `readme`, so the published metadata carried no description at all: the page showed the summary line and nothing else. It now carries the README (`description_content_type: text/markdown`). The README's repo-relative links (`DESIGN.md`, `DEVELOPER.md`, `CONTRIBUTING.md`, `LICENSE`, `AUTHORS`) are absolutised, since those resolve on GitHub but 404 when the same Markdown is rendered on PyPI.
+- **No licence was declared.** The README badge claimed MIT and a `LICENSE` file was present, but nothing said so in the metadata. Now `license = "MIT"` (an SPDX expression) with `license-files = ["LICENSE"]`, so the wheel carries `License-Expression: MIT` and `License-File: LICENSE`. No `License :: OSI Approved` classifier is paired with it, per PEP 639.
+- **No classifiers.** PyPI indexed nothing about the package. Now covers 3.11 through 3.14, audience, topic, and `Typing :: Typed` — the last being how PyPI surfaces the `py.typed` marker shipped in 0.3.0, on the page and in the "Typed" search filter.
+- The `hatchling` build requirement is floored at `>=1.27`, the version that supports PEP 639. Below it the build **succeeds** and quietly emits legacy metadata instead (measured on 1.26.3: `License: MIT`, no `License-Expression`, no `License-File`), so an unpinned backend would have degraded the published artifact without failing anything. ([#15](https://github.com/electrification-bus/distribution-enclosure-simulator/pull/15))
+
+### Changed
+
+- The README's Python badge is now the dynamic `pypi/pyversions` one used across the eBus family, replacing a hardcoded `3.11+`. It reads classifiers from the published release, so it could not be adopted until this release carried them.
+
+## [0.3.1] - 2026-08-07
+
+### Fixed
+
+- **`Emitter.stop(graceful=False)` now leaves the tree at `$state=lost`, as it always claimed to.** It documented itself as "leaving the LWT to fire `$state=lost`", which cannot happen: a Last Will fires only on an *unclean* disconnect, and `MqttClient.stop()` sends a clean DISCONNECT deliberately, so that an orderly shutdown is not reported to consumers as a crash. The will was therefore suppressed on every teardown, and an ungraceful stop published nothing at all: verified against a real broker, a consumer joining afterwards read the entire retained tree as `ready`, indefinitely. For a simulator this is the mode's whole purpose, since "act like a producer that died" is exactly what a consumer test needs, so the fix makes the behaviour real rather than deleting the promise. The root's `$state=lost` is now published retained before the connection drops, with topic and payload taken from the SDK's own `Device.will()` descriptor so it cannot drift from what a broker-delivered will would have carried. The difference from a real will is timing and delivery, not content: this lands immediately over the live connection, where a broker-delivered will waits on keepalive expiry, so a consumer exercising the *retained* view sees the same thing either way while one exercising live will delivery does not. `clear_retained` is documented as graceful-only, since a producer that died clears nothing.
+
+### Added
+
+- `tests/test_teardown.py`: both teardown modes now have tests, which neither had before. That absence is why a docstring could promise behaviour the code had never performed. Three of the five fail against 0.3.0.
+
 ## [0.3.0] - 2026-08-07
 
 First release published to PyPI, as **`ebus-panel-sim`**.

ebus_panel_sim-0.3.2/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: ebus-panel-sim
+Version: 0.3.2
+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
+Project-URL: Issues, https://github.com/electrification-bus/distribution-enclosure-simulator/issues
+Author: Bill Flood, Clark Communications Corporation
+License-Expression: MIT
+License-File: LICENSE
+Keywords: distribution-enclosure,ebus,energy,homie,homie5,iot,mqtt,simulator,span
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: ebus-sdk<0.20,>=0.19
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# ebus-panel-sim
+
+[![PyPI](https://img.shields.io/pypi/v/ebus-panel-sim)](https://pypi.org/project/ebus-panel-sim/)
+[![CI](https://github.com/electrification-bus/distribution-enclosure-simulator/actions/workflows/ci.yaml/badge.svg)](https://github.com/electrification-bus/distribution-enclosure-simulator/actions/workflows/ci.yaml)
+[![Python versions](https://img.shields.io/pypi/pyversions/ebus-panel-sim.svg)](https://pypi.org/project/ebus-panel-sim/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![eBus spec](https://img.shields.io/badge/eBus%20spec-6e582c9-green)](https://github.com/electrification-bus/specification/tree/6e582c994fff4c77853a79d8bab26ef9924e22c7)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A fully-loaded, spec-conformant **distribution-enclosure simulator** and producer-side Homie 5 publisher for the eBus convention. It publishes a complete eBus Homie device tree (the enclosure plus a device for every circuit, lugs pair, and integrated DER: BESS, PV, EVSE, and MID) so external developers can build and test their consumers against a realistic SPAN-like panel without beta firmware, a live panel, or the commissioned add-ons (SPAN Drive/EVSE, BESS, PV, MID) a real installation would have.
+
+It serves two roles:
+
+- **Simulator / test fixture.** Drive it from a small YAML definition and it publishes a spec-conformant, fully-commissioned enclosure to any MQTT broker. Consumers (Home Assistant integrations, dashboards, SDK code) validate against it before shipping to the field.
+- **Producer library.** The canonical eBus Homie publisher. A producer (a simulator, a real panel gateway, an LLM-driven model) hands the emitter a small per-tick driving signal (signed power per circuit, current time, grid-online flag) via `TickInputs`; the emitter derives all telemetry and publishes Homie-conformant retained MQTT with diff-only updates. The split is **identity = manifest (once at startup), telemetry = derived from TickInputs (per tick)**.
+
+For the internals (the per-tick pipeline, the native BESS/load-shed devices, `/set` handling, the wire model) see [DESIGN.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DESIGN.md); for the dev setup see [DEVELOPER.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DEVELOPER.md).
+
+## Requirements
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/)
+- An MQTT broker reachable at `localhost:1883` (plaintext). The companion [broker-quickstart](https://github.com/electrification-bus/broker-quickstart) bundle brings one up in one command; any `mosquitto` works too.
+
+## Install
+
+```bash
+pip install ebus-panel-sim    # or: uv add ebus-panel-sim
+```
+
+The import package is `ebus_panel_sim`. During local development, pin a path instead:
+
+```toml
+ebus-panel-sim = { path = "../distribution-enclosure-simulator", editable = true }
+```
+
+It depends on `ebus-sdk`.
+
+> Before 0.3.0 this package was named `panel-sim`, importing as `panel_sim`, and was
+> installable only from git. Update both the dependency and your imports.
+
+## Run
+
+The repo ships a runnable example: it builds an emitter from a YAML definition, publishes a couple of ticks to an MQTT broker, then reads the retained tree back through an ebus-sdk `Controller` and prints it. It expects a plaintext broker on `localhost:1883`.
+
+The quickest broker is the companion [broker-quickstart](https://github.com/electrification-bus/broker-quickstart) in its `open` profile (plaintext, anonymous, port 1883):
+
+```bash
+# in a broker-quickstart checkout — a plaintext :1883 broker (anon read + write)
+python -m laptop.run --profile open
+```
+
+Then, in this repo, publish to it and print the retained tree:
+
+```bash
+uv sync --group dev
+uv run python examples/run_forty_tab_minimal.py                        # print the retained tree
+uv run python examples/run_forty_tab_minimal.py --broker 127.0.0.1:1883 --ticks 2 > tree.txt
+```
+
+Any broker that accepts anonymous connections on `localhost:1883` works; `--broker host:port` points the example elsewhere.
+
+The definition is `examples/forty_tab_minimal.yaml`: a fully-commissioned enclosure with circuits, upstream/downstream lugs, a BESS (plus its MID), PV, and SPAN Drive EVSEs. Each node is its own Homie device: the enclosure at `ebus/5/<enclosure-id>/…` and each circuit, lugs pair, and DER at its own topic root, for example `ebus/5/<circuit-id>/switch/relay`, `ebus/5/<lugs-id>/meter/current-a`, `ebus/5/<bess-id>-mid/grid/islanding-state`.
+
+## Configure
+
+The simulator is driven by a config that says which enclosure, which add-ons, and which circuits. There are two entry points.
+
+### 1. Example YAML
+
+`examples/forty_tab_minimal.yaml` is the quickest path. Top-level sections:
+
+- `panel_config` — enclosure identity plus `total_tabs`, `main_size`, `postal_code`, `time_zone`, and `islandable`. A grid-forming BESS in an islandable enclosure automatically exposes an integrated MID (the islanding authority), mirroring a real SPAN panel.
+- `circuit_templates` and `circuits` — per-circuit `tabs`, breaker rating, priority, relay behavior, and an optional `device_type` (`evse` or `pv`) to land a DER on a circuit.
+- `bess` — nameplate capacity, charge mode, charge/discharge limits.
+- `ticks` — the per-tick driving signal: signed watts per circuit and the grid-online flag.
+
+### 2. DeviceManifest (programmatic)
+
+A producer can build `DeviceInstance`s directly instead of using the YAML loader. Each device class's identity and static attributes live in the instance's `metadata`, validated once at startup by `ManifestPhysicsView` (missing required keys or malformed values raise `ManifestValidationError` naming the offending instance). The metadata keys per device class:
+
+| entity_class | required keys | optional keys |
+| --- | --- | --- |
+| `panel` | `vendor-name`, `serial-number`, `firmware-version` (or `software-version`), `hardware-version`, `panel-size`, `main-breaker-rating-a`, `panel-model`, `postal-code`, `time-zone` | `service-voltage-v` (240), `line-voltage-v` (120), `islandable` (false) |
+| `lugs` | `direction` (`upstream` \| `downstream`) | |
+| `circuit` | `tab-numbers` (CSV ints), `breaker-rating-a`, `default-priority`, `relay-behavior`, `placement` (`upstream-of-lugs` \| `downstream-of-lugs`) | `always-on`, `pcs-priority` (0), `initial-consumed-wh` (0), `initial-produced-wh` (0) |
+| `bess` | `vendor-name`, `nameplate-capacity-kwh` | `product-name`, `model`, `serial-number`, `firmware-version`/`software-version`, `relative-position` (`UPSTREAM`), `feed`, `initial-soe-kwh` |
+| `pv` | `vendor-name`, `nameplate-capacity-w`, `inverter-type` (`hybrid` \| `ac-coupled`) | `product-name`, `serial-number`, `firmware-version`/`software-version`, `relative-position` (`IN_PANEL`), `feed` |
+| `evse` | `vendor-name`, `product-name`, `part-number`, `serial-number`, `firmware-version` (or `software-version`), `max-current-a` | `feed` |
+| `mid` | (none) | `vendor-name`, `serial-number`, `product-name`, `model`, `firmware-version`/`software-version`, `hardware-version` |
+
+## Usage (as a producer library)
+
+```python
+import time
+
+from ebus_panel_sim import (
+    BESSConfig, DeviceInstance, DeviceManifest, Emitter,
+    LoadSheddingConfig, SetterRegistry, TickInputs,
+)
+
+
+def main() -> None:
+    manifest = DeviceManifest(instances=(
+        DeviceInstance("panel", "abc-123", "Span Panel", metadata={
+            "vendor-name": "Span", "serial-number": "abc-123",
+            "firmware-version": "sim/v0.1.0", "hardware-version": "rev2",
+            "panel-size": "40", "main-breaker-rating-a": "200",
+            "panel-model": "MAIN_40", "postal-code": "94103",
+            "time-zone": "America/Los_Angeles", "islandable": "true",
+        }),
+        DeviceInstance("lugs", "abc-123-lugs-up", "Upstream lugs", {"direction": "upstream"}),
+        DeviceInstance("circuit", "kitchen", "Kitchen", metadata={
+            "tab-numbers": "1", "breaker-rating-a": "20",
+            "default-priority": "NICE_TO_HAVE", "relay-behavior": "controllable",
+            "placement": "downstream-of-lugs",
+        }),
+        DeviceInstance("bess", "abc-123-bess", "Battery", metadata={
+            "vendor-name": "Span", "nameplate-capacity-kwh": "13.5",
+        }),
+    ))
+    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.
+    emitter = Emitter(
+        manifest, SetterRegistry(),
+        mqtt_cfg={"host": "127.0.0.1", "port": 1883},
+        bess_configs=(bess_cfg,),
+        load_shedding_config=LoadSheddingConfig(soc_threshold_pct=20.0),
+    )
+    emitter.start()
+    try:
+        while True:
+            emitter.publish_tick(TickInputs(
+                current_time=time.time(),
+                grid_online=True,
+                circuits=collect_powers_from_your_model(),  # instance_id -> signed watts
+            ))
+            time.sleep(1.0)
+    finally:
+        emitter.stop()
+
+
+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).
+
+## 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).
+- `examples/` — the runnable example and its YAML definition.
+- `tests/` — the pytest suite.
+
+## Tests
+
+```bash
+uv run pytest
+uv run mypy --strict src/ebus_panel_sim tests
+uv run ruff check src tests
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/CONTRIBUTING.md) for how to file issues, start a [discussion](https://github.com/electrification-bus/distribution-enclosure-simulator/discussions), and open pull requests, plus the local quality gates (ruff, mypy `--strict`, pytest).
+
+## Credits
+
+A fork of, and building on, the original simulator created by **Bill Flood** ([@cayossarian](https://github.com/cayossarian)); since updated to track the latest eBus specification. See [AUTHORS](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/AUTHORS).
+
+## License
+
+See [LICENSE](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/LICENSE).

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/README.md

@@ -1,7 +1,8 @@
 # ebus-panel-sim
 
+[![PyPI](https://img.shields.io/pypi/v/ebus-panel-sim)](https://pypi.org/project/ebus-panel-sim/)
 [![CI](https://github.com/electrification-bus/distribution-enclosure-simulator/actions/workflows/ci.yaml/badge.svg)](https://github.com/electrification-bus/distribution-enclosure-simulator/actions/workflows/ci.yaml)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ebus-panel-sim.svg)](https://pypi.org/project/ebus-panel-sim/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![eBus spec](https://img.shields.io/badge/eBus%20spec-6e582c9-green)](https://github.com/electrification-bus/specification/tree/6e582c994fff4c77853a79d8bab26ef9924e22c7)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,7 +14,7 @@ It serves two roles:
 - **Simulator / test fixture.** Drive it from a small YAML definition and it publishes a spec-conformant, fully-commissioned enclosure to any MQTT broker. Consumers (Home Assistant integrations, dashboards, SDK code) validate against it before shipping to the field.
 - **Producer library.** The canonical eBus Homie publisher. A producer (a simulator, a real panel gateway, an LLM-driven model) hands the emitter a small per-tick driving signal (signed power per circuit, current time, grid-online flag) via `TickInputs`; the emitter derives all telemetry and publishes Homie-conformant retained MQTT with diff-only updates. The split is **identity = manifest (once at startup), telemetry = derived from TickInputs (per tick)**.
 
-For the internals (the per-tick pipeline, the native BESS/load-shed devices, `/set` handling, the wire model) see [DESIGN.md](DESIGN.md); for the dev setup see [DEVELOPER.md](DEVELOPER.md).
+For the internals (the per-tick pipeline, the native BESS/load-shed devices, `/set` handling, the wire model) see [DESIGN.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DESIGN.md); for the dev setup see [DEVELOPER.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/DEVELOPER.md).
 
 ## Requirements
 
@@ -151,7 +152,7 @@ Read the most recently published state back through `emitter.last_snapshot`. `mq
 
 ## Layout
 
-- `src/ebus_panel_sim/` — the package (`emitter.py`, `manifest.py`, `wire/` profiles + publishing, `native_devices/`); see [DESIGN.md](DESIGN.md).
+- `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).
 - `examples/` — the runnable example and its YAML definition.
 - `tests/` — the pytest suite.
 
@@ -165,12 +166,12 @@ uv run ruff check src tests
 
 ## Contributing
 
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues, start a [discussion](https://github.com/electrification-bus/distribution-enclosure-simulator/discussions), and open pull requests, plus the local quality gates (ruff, mypy `--strict`, pytest).
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/CONTRIBUTING.md) for how to file issues, start a [discussion](https://github.com/electrification-bus/distribution-enclosure-simulator/discussions), and open pull requests, plus the local quality gates (ruff, mypy `--strict`, pytest).
 
 ## Credits
 
-A fork of, and building on, the original simulator created by **Bill Flood** ([@cayossarian](https://github.com/cayossarian)); since updated to track the latest eBus specification. See [AUTHORS](AUTHORS).
+A fork of, and building on, the original simulator created by **Bill Flood** ([@cayossarian](https://github.com/cayossarian)); since updated to track the latest eBus specification. See [AUTHORS](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/AUTHORS).
 
 ## License
 
-See [LICENSE](LICENSE).
+See [LICENSE](https://github.com/electrification-bus/distribution-enclosure-simulator/blob/main/LICENSE).

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/pyproject.toml

@@ -1,5 +1,10 @@
 [build-system]
-requires = ["hatchling"]
+# PEP 639 floor: `license = "MIT"` as an SPDX expression plus `license-files` needs
+# hatchling >= 1.27. Below it the build SUCCEEDS and quietly emits the legacy
+# metadata instead (measured on 1.26.3: `License: MIT`, no `License-Expression`,
+# no `License-File`), so an unpinned backend would degrade the published metadata
+# without failing anything.
+requires = ["hatchling>=1.27"]
 build-backend = "hatchling.build"
 
 [project]
@@ -9,11 +14,32 @@ name = "ebus-panel-sim"
 # git tag disagrees. Matches the convention across the eBus family.
 dynamic = ["version"]
 description = "Producer-side Homie publisher with embedded behaviour runtime for the eBus convention"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     {name = "Bill Flood"},
     {name = "Clark Communications Corporation"},
 ]
 keywords = ["homie", "homie5", "mqtt", "iot", "ebus", "simulator", "span", "distribution-enclosure", "energy"]
+# `requires-python` is what pip enforces; these are what PyPI indexes and what the
+# README's Python badge reads. Kept in step with the floor above, not with the CI
+# matrix, which tests the ends of the range (3.11 and 3.14) rather than every point
+# in it.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Topic :: System :: Emulators",
+    # The package ships py.typed; this is how PyPI surfaces that, on the page and
+    # in the "Typed" search filter.
+    "Typing :: Typed",
+]
 requires-python = ">=3.11"
 dependencies = [
     "ebus-sdk>=0.19,<0.20",

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/src/ebus_panel_sim/__init__.py

@@ -69,7 +69,7 @@ from ebus_panel_sim.wire.set_router import SetterHandler, SetterRegistry
 # 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.0"
+__version__ = "0.3.2"
 
 __all__ = [
     "BESSConfig",

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/src/ebus_panel_sim/emitter.py

@@ -49,7 +49,7 @@ 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
+from ebus_panel_sim.wire._sdk_seam import owned_client, publish_will_now
 from ebus_panel_sim.wire.bag_builder import BagBuilder
 from ebus_panel_sim.wire.graph_builder import build_graph
 from ebus_panel_sim.wire.mapping_loader import load_mapping_table
@@ -253,11 +253,27 @@ class Emitter:
         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).
-        Non-graceful: stop the client without the disconnected publish, leaving
-        the LWT to fire ``$state=lost``. ``clear_retained`` additionally clears
-        every device's retained values + ``$description`` before disconnecting,
-        for a clean-slate re-run."""
+
+        Non-graceful: leave the tree looking like a producer that died, by
+        publishing the root's ``$state=lost`` retained before dropping the
+        connection. This is what a consumer test wants from a simulator, and it
+        is emphatically NOT what a bare disconnect gives you: the Last Will fires
+        only on an *unclean* disconnect, and every teardown here closes cleanly,
+        so relying on the will would leave the whole retained tree claiming
+        ``ready`` forever. See ``publish_will_now``, which sources the topic and
+        payload from ``Device.will()`` so this cannot drift from the real thing.
+
+        The difference from a real will is timing and delivery, not content: this
+        lands immediately over the live connection, where a broker-delivered will
+        waits on keepalive expiry. A consumer exercising the *retained* view sees
+        the same thing either way; one exercising live will delivery does not.
+
+        ``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)
             if client is not None:
                 client.stop()

{ebus_panel_sim-0.3.0 → ebus_panel_sim-0.3.2}/src/ebus_panel_sim/wire/_sdk_seam.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Any
 
 import ebus_sdk
-from ebus_sdk import MqttClient, PropertyDatatype, Unit
+from ebus_sdk import EBUS_HOMIE_MQTT_QOS, MqttClient, PropertyDatatype, Unit
 
 
 def make_property(
@@ -53,3 +53,36 @@ def owned_client(mqttc: object) -> MqttClient | None:
     its owner to stop, which is the behaviour the SDK's contract asks for.
     """
     return mqttc if isinstance(mqttc, MqttClient) else None
+
+
+def publish_will_now(root: ebus_sdk.Device) -> 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.
+
+    Returns True when the broker acknowledged it, False if there is no owned
+    client or the publish did not flush in time.
+    """
+    client = owned_client(root.mqttc)
+    if client is None:
+        return False
+    will = root.will()
+    return bool(
+        client.publish_and_flush(
+            will["topic"], will["payload"], qos=EBUS_HOMIE_MQTT_QOS, retain=True
+        )
+    )

ebus_panel_sim-0.3.2/tests/test_teardown.py

@@ -0,0 +1,73 @@
+"""Teardown semantics: what the retained tree looks like after ``Emitter.stop()``.
+
+Both modes were previously untested. The non-graceful path had documented itself as
+"leaving the LWT to fire ``$state=lost``", which cannot happen: a Last Will fires
+only on an *unclean* disconnect, and ``MqttClient.stop()`` sends a clean DISCONNECT
+(deliberately, so an orderly shutdown is not reported as a crash). Verified against
+a real mosquitto broker before this suite existed: a consumer joining after an
+ungraceful teardown read the whole tree as ``ready``.
+
+These tests pin the observable outcome, the effective retained ``$state`` a
+late-joining consumer sees, rather than the mechanism.
+"""
+
+from __future__ import annotations
+
+from ebus_panel_sim import Emitter
+from ebus_panel_sim.wire.set_router import SetterRegistry
+
+from .conftest import PahoRecorder
+from .test_emitter_public_surface import _manifest
+
+ROOT_STATE = "ebus/5/p1/$state"
+
+
+def _started() -> Emitter:
+    emitter = Emitter(_manifest(), SetterRegistry())
+    emitter.start()
+    return emitter
+
+
+def test_ungraceful_stop_leaves_the_root_lost(rec: PahoRecorder) -> None:
+    """A producer that died must not leave the tree claiming ``ready``."""
+    _started().stop(graceful=False)
+    assert rec.retained[ROOT_STATE] == "lost"
+
+
+def test_graceful_stop_leaves_the_root_disconnected(rec: PahoRecorder) -> None:
+    """An orderly shutdown is a different signal from a crash, and consumers act
+    on the difference: ``disconnected`` is expected, ``lost`` is a fault."""
+    _started().stop(graceful=True)
+    assert rec.retained[ROOT_STATE] == "disconnected"
+
+
+def test_the_two_modes_do_not_agree(rec: PahoRecorder) -> None:
+    """Guards against a future change collapsing the two teardown modes into one.
+
+    Note this test passed before the fix too, for the wrong reason: ungraceful left
+    the root on ``ready``, which does differ from ``disconnected``. The bug was
+    never that the modes agreed, it was that one of them lied. The two tests above
+    are what pin the actual values; this one only pins that they stay distinct."""
+    _started().stop(graceful=False)
+    ungraceful = rec.retained[ROOT_STATE]
+    rec.reset()
+    _started().stop(graceful=True)
+    assert ungraceful != rec.retained[ROOT_STATE]
+
+
+def test_ungraceful_stop_uses_the_sdk_will_descriptor(rec: PahoRecorder) -> None:
+    """The synthesised ``lost`` must be byte-identical to what the broker would
+    have delivered from the registered will, or the simulation is a fiction."""
+    emitter = _started()
+    will = emitter._root.will()
+    emitter.stop(graceful=False)
+    assert rec.retained[will["topic"]] == will["payload"]
+
+
+def test_ungraceful_stop_publishes_lost_retained(rec: PahoRecorder) -> None:
+    """Retained, or a consumer joining after the death sees nothing at all and
+    cannot distinguish a dead producer from one that never existed."""
+    _started().stop(graceful=False)
+    lost = [(t, d, q, r) for (t, d, q, r) in rec.published if t == ROOT_STATE and d == "lost"]
+    assert lost, "no $state=lost publish reached the transport"
+    assert all(retain for (_t, _d, _q, retain) in lost)

ebus_panel_sim-0.3.0/PKG-INFO

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: ebus-panel-sim
-Version: 0.3.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
-Project-URL: Issues, https://github.com/electrification-bus/distribution-enclosure-simulator/issues
-Author: Bill Flood, Clark Communications Corporation
-License-File: AUTHORS
-License-File: LICENSE
-Keywords: distribution-enclosure,ebus,energy,homie,homie5,iot,mqtt,simulator,span
-Requires-Python: >=3.11
-Requires-Dist: ebus-sdk<0.20,>=0.19
-Requires-Dist: pyyaml>=6.0