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

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

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [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.
+
+### 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

{ebus_panel_sim-0.3.1 → ebus_panel_sim-0.3.3}/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.1 → ebus_panel_sim-0.3.3}/DESIGN.md

@@ -17,7 +17,7 @@ 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.
 
 ## Native devices
 

{ebus_panel_sim-0.3.1 → ebus_panel_sim-0.3.3}/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.3/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: ebus-panel-sim
+Version: 0.3.3
+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.1 → ebus_panel_sim-0.3.3}/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.1 → ebus_panel_sim-0.3.3}/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.1 → ebus_panel_sim-0.3.3}/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.1"
+__version__ = "0.3.3"
 
 __all__ = [
     "BESSConfig",

{ebus_panel_sim-0.3.1 → ebus_panel_sim-0.3.3}/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 EBUS_HOMIE_MQTT_QOS, MqttClient, PropertyDatatype, Unit
+from ebus_sdk import EBUS_HOMIE_MQTT_QOS, DeviceState, MqttClient, PropertyDatatype, Unit
 
 
 def make_property(
@@ -74,12 +74,26 @@ def publish_will_now(root: ebus_sdk.Device) -> bool:
     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.
+
+    That call also publishes ``$state``, so the flushed publish below is the same
+    retained value a second time. The duplicate is deliberate and costs one message
+    at teardown: ``set_state`` goes through the ordinary unflushed path, and on the
+    owned path the connection closes immediately behind this function, so only a
+    flushed publish is actually guaranteed to land.
+
     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
+    root.set_state(DeviceState.LOST)
     will = root.will()
     return bool(
         client.publish_and_flush(

{ebus_panel_sim-0.3.1 → ebus_panel_sim-0.3.3}/tests/test_teardown.py

@@ -71,3 +71,25 @@ def test_ungraceful_stop_publishes_lost_retained(rec: PahoRecorder) -> None:
     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)
+
+
+def test_ungraceful_stop_moves_the_device_state_not_just_the_wire(rec: PahoRecorder) -> None:
+    """Publishing `lost` while the Device object still holds `ready` leaves the two
+    disagreeing, and anything that re-announces from the object undoes the publish.
+    `Device.stop()` sets `_state` for `disconnected`; this must match."""
+    emitter = _started()
+    emitter.stop(graceful=False)
+    assert rec.retained[ROOT_STATE] == "lost"
+    assert emitter._root.state().value == "lost"
+
+
+def test_a_later_refresh_tree_re_announces_lost_not_ready(rec: PahoRecorder) -> None:
+    """`refresh_tree()` republishes from the Device's own state, and the SDK asks a
+    bring-your-own-transport caller to wire it onto their client's on-connect
+    handler. If the ungraceful stop left `_state` on `ready`, that hook would
+    resurrect `ready` over the `lost` and restore the very stale-tree bug 0.3.1
+    removed."""
+    emitter = _started()
+    emitter.stop(graceful=False)
+    emitter._root.refresh_tree()
+    assert rec.retained[ROOT_STATE] == "lost"

ebus_panel_sim-0.3.1/PKG-INFO

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: ebus-panel-sim
-Version: 0.3.1
-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