ebus-panel-sim 0.3.0__tar.gz

ebus_panel_sim-0.3.0/.ebus-spec.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://ebus.energy/schemas/ebus-spec.json",
+  "spec_repo": "https://github.com/electrification-bus/specification",
+  "synced_commit": "6e582c994fff4c77853a79d8bab26ef9924e22c7",
+  "synced_date": "2026-08-01",
+  "role": "publisher",
+  "framework": "0.7",
+  "implements": {
+    "capabilities": {
+      "info": "0.2",
+      "meter": "0.2",
+      "switch": "0.1",
+      "breaker": "0.1",
+      "connection": "0.1",
+      "load-shed": "0.3",
+      "pcs": "0.3",
+      "shed": "0.2",
+      "shed-forecast": "0.1",
+      "grid": "0.1",
+      "power-flows": "0.1",
+      "door": "0.1",
+      "status": "0.1",
+      "soc": "0.1"
+    },
+    "devices": {
+      "distribution-enclosure": "0.12",
+      "circuit": "0.3",
+      "bess": "0.14"
+    },
+    "registries": {
+      "capability-types": "0.19",
+      "device-types": "0.4"
+    }
+  },
+  "notes": "role=publisher: ebus-panel-sim publishes a full Homie 5 distribution-enclosure tree (enclosure + circuits + upstream/downstream lugs + bess/pv/evse/mid children) as a producer-side reference/test fixture for the eBus convention. The wire type contract is single-sourced from the vendored spec capability catalogs (src/ebus_panel_sim/wire/catalogs/, byte copies of the spec capabilities/ at synced_commit); base profiles are light selections hydrated against them, guarded by tests/test_catalog_drift.py (lockfile-vs-catalog versions always; vendored-vs-source content when a ../specification checkout is present). ebus-panel-sim ships two variants: 'reference' publishes the spec-conformant surface; 'span' (the default) deep-merges a SPAN-vendor overlay (src/ebus_panel_sim/wire/profiles/span/) and is the SPAN-faithful fixture. Capabilities are pinned to what the profiles publish AND that exist in the current spec catalog. Deliberate SPAN-variant deviations, carried in the overlay and absent from 'reference': panel status diagnostics (relay/ethernet/wifi/wifi-ssid/cloud-connection/postal-code/time-zone); shed/policy published read-only (settable=false), because a SPAN panel does not accept policy writes, whereas the spec catalog and the 'reference' variant make it settable and the Emitter accepts policy writes there; the legacy evse `config` grab-bag (the spec `charge-limit` catalog is vendored but not yet composed into the evse profile, DESIM-a5p.15.1, hence `charge-limit` is not pinned); circuit info/name + info/spaces; lugs info/direction. Remaining spec reconciliation: pv omits `meter` (DESIM-a5p.15.4). Device coverage: pv/evse/mid/lugs have no standalone versioned device model yet (pv gated on SPEC-730, evse on SPEC-a8e, mid Planned on SPEC-9jz, lugs unmodeled) and are covered transitively as child device_types of distribution-enclosure 0.12, so they are not separately pinned. The property-JSON shape contract (conventions/property-json, property-schema-v1 v0.1) is NOT pinned here because spec-provenance's implements schema has only capabilities/devices/registries slots (no conventions slot); to be added once the provenance schema gains implements.conventions."
+}

ebus_panel_sim-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Bill Flood (@cayossarian) created this simulator and is the default owner.
+* @cayossarian @dcj

ebus_panel_sim-0.3.0/.github/workflows/ci.yaml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Ruff format
+        run: uv run ruff format --check src tests
+
+      - name: Mypy
+        run: uv run mypy --strict src tests
+
+      - name: Pytest
+        run: uv run pytest tests --tb=short

ebus_panel_sim-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,105 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  # Re-run the full gate set against the tag. A tag can point anywhere, so a green
+  # CI run on the branch is not evidence about the commit being released.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync --group dev
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy --strict src tests
+      - run: uv run pytest tests --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    # Names the PyPI trusted publisher's environment. PyPI checks this claim on the
+    # OIDC token, so it must match the "Environment name" registered there.
+    environment: pypi
+    permissions:
+      # Mints the OIDC token trusted publishing exchanges for an upload token. No
+      # PyPI API token is stored anywhere.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v3
+
+      # The version lives in one place, but the tag is typed by hand. Refuse to
+      # publish an artifact whose version disagrees with the tag that triggered it,
+      # rather than burning a version number on PyPI (uploads are not replaceable).
+      - name: Verify the tag matches the package version
+        run: |
+          pkg="v$(uv run python -c 'import re,pathlib; print(re.search(r"__version__ = \"([^\"]+)\"", pathlib.Path("src/ebus_panel_sim/__init__.py").read_text()).group(1))')"
+          echo "tag=${GITHUB_REF_NAME} package=${pkg}"
+          test "${pkg}" = "${GITHUB_REF_NAME}"
+
+      - name: Build the sdist and wheel
+        run: uv build
+
+      # Guards the packaging fault that kept this package unbuildable until #8: the
+      # wheel must actually carry the YAML/JSON wire data, since every profile and
+      # mapping lookup resolves from it at runtime and the test suite reads the
+      # source tree instead.
+      - name: Verify the wheel carries its wire data
+        run: |
+          python - <<'PY'
+          import glob, zipfile, sys
+          names = zipfile.ZipFile(sorted(glob.glob("dist/*.whl"))[0]).namelist()
+          missing = [d for d in ("wire/profiles", "wire/mapping", "wire/catalogs")
+                     if not any(d in n for n in names)]
+          dupes = len(names) - len(set(names))
+          if missing or dupes:
+              sys.exit(f"missing={missing} duplicate_entries={dupes}")
+          print(f"ok: {len(names)} entries, no duplicates, all wire data present")
+          PY
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+
+  # Mirror the release to GitHub Releases, using the tag's CHANGELOG section as the
+  # notes. Idempotent (create, else edit).
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create the GitHub Release from the CHANGELOG section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          python3 - "$version" > notes.md <<'PY'
+          import re, sys, pathlib
+          v = re.escape(sys.argv[1])
+          text = pathlib.Path("CHANGELOG.md").read_text()
+          m = re.search(rf"^## \[{v}\][^\n]*\n(.*?)(?=^## \[|\Z)", text, re.S | re.M)
+          body = (m.group(1).strip() if m else "") or "See CHANGELOG.md."
+          sys.stdout.write(body + "\n")
+          PY
+          gh release create "${GITHUB_REF_NAME}" --title "${GITHUB_REF_NAME}" \
+            --notes-file notes.md --verify-tag \
+            || gh release edit "${GITHUB_REF_NAME}" --notes-file notes.md

ebus_panel_sim-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+/certs/
+.local/
+.claude/
+.DS_Store
+.envrc

ebus_panel_sim-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  # Run mypy through the project venv rather than a pre-commit-managed one. The
+  # isolated env would need `ebus-sdk` restated in `additional_dependencies`, and
+  # a copy of the pin that nothing keeps in sync silently drifts from pyproject.
+  # Typing the ebus-sdk seam correctly depends on resolving the SDK's real types
+  # (it has shipped `py.typed` since 0.13.0), so this hook now runs exactly what
+  # CI runs, against exactly the pinned SDK. It also checks `src`, not just
+  # `src/ebus_panel_sim`, matching CI.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy --strict (project venv)
+        language: system
+        types: [python]
+        pass_filenames: false
+        entry: uv run mypy --strict src tests
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

ebus_panel_sim-0.3.0/.python-version

@@ -0,0 +1 @@
+3.14.4

ebus_panel_sim-0.3.0/AUTHORS

@@ -0,0 +1,7 @@
+# Authors
+
+This project is a fork of, and builds on, the original simulator created by Bill Flood.
+
+Bill Flood (@cayossarian): creator and principal developer of the original work.
+
+Clark Communications Corporation (@dcj): fork maintainer; updates to track the latest eBus specification.

ebus_panel_sim-0.3.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-07
+
+First release published to PyPI, as **`ebus-panel-sim`**.
+
+### Added
+
+- **Published to PyPI.** Releases are tag-triggered and use PyPI trusted publishing (OIDC), so no API token is stored anywhere. The workflow re-runs the full gate set against the tag rather than trusting a green branch run, since a tag can point at any commit, and it refuses to publish when the tag disagrees with `__version__` or when the built wheel is missing its wire data. Consumers pinning by git URL can now `pip install ebus-panel-sim` instead. (#10)
+- **`py.typed`.** The package is `mypy --strict` throughout but shipped no PEP 561 marker, so none of its annotations reached consumers: an installed `panel_sim` resolved to `Any`. This is the same class of gap that let the `Device.mqttc` teardown bug below sit unnoticed here until `ebus-sdk` shipped its own marker. Verified from outside: a consumer installing the wheel now types `Emitter.publish_tick` as `(TickInputs) -> EbusPanelSnapshot`. (#10)
+
+### Changed
+
+- **BREAKING (package): renamed to `ebus-panel-sim`, importing as `ebus_panel_sim`.** Was `panel-sim`/`panel_sim`. Update imports and any git-URL or path pin. Across the eBus family the repository name and the distribution name differ freely, but the distribution name always equals the import package under an `ebus` prefix (`ebus-sdk`/`ebus_sdk`, `ebus-tools`/`ebus_tools`, `ebus-service-discovery`/`ebus_service_discovery`), and this package was the outlier. The unprefixed name was also actively misleading: PyPI's `panel` is HoloViz's dashboard framework, with an established `panel-*` plugin ecosystem, so `panel-sim` read as a plugin for it. Done now because it is free before the first release and a breaking change for every consumer after it. (#8)
+- `ebus-sdk` pin moved from `>=0.18,<0.19` to `>=0.19,<0.20`. The motivating fix is in **0.18.1**, which the old range already permitted but `uv.lock` had never picked up: `Device.refresh_tree()` published a device's own `$state` before recursing to its children, so a device could announce `ready` while the children it vouches for had published nothing ([python-sdk#31](https://github.com/electrification-bus/python-sdk/issues/31)). That matters here specifically because this package publishes a parent/child tree, which is the shape that exhibits it. **0.19.0** additionally makes the `refresh_tree()` cascade best-effort per child, so one raising descendant can no longer abort the rest of a reconnect republish; with an enclosure plus a device per circuit, lugs pair and DER, this tree has many descendants to abort. Its other changes do not reach us: `Controller.is_tree_complete()`/`on_tree_ready` is consumer-side, and the `Node.delete_property()` `$description` fix applies to an API this package never calls. No source changes. The emitted wire surface is unchanged between `0.18.0` and `0.19.0`: identical publish order, identical subscriptions, and identical retained payloads once the `$description` `version` wall-clock stamp is normalised (it differs run to run regardless of SDK version). Suite is `158 passed` under both.
+- `ebus-sdk` pin moved from `>=0.12,<0.13` to `>=0.18,<0.19`. The old range excluded the release carrying the [python-sdk#27](https://github.com/electrification-bus/python-sdk/issues/27) fixes — the `battery` capability key removed in favour of `soc`, and `energy` → `energy_storage` / `total_increasing` → `measurement` for `soe`, `total-energy-storage` and `loadup-headroom` — so a downstream needing those could not stay inside the pin. No source changes: the published tree is byte-identical on `0.12.0` and `0.18.0` (197 retained topics, identical topic sets, zero payload differences once the `$description` `version` timestamp is normalised), and the suite is `158 passed` under both. `uv.lock` also moves `ebus-mqtt-client` 0.1.8 → 0.4.0, which `ebus-sdk` 0.18.0 requires. (#4, closes #3)
+- The package version is now single-sourced from `ebus_panel_sim.__version__` and read by `[tool.hatch.version]`, rather than being restated in `pyproject.toml`. Note this is the *package* version, which is distinct from the producer-contract version the module docstrings refer to. (#10)
+- `pre-commit` runs mypy from the project venv instead of a pre-commit-managed one. The isolated environment could never see `ebus-sdk` at all, so the hook silently checked less than CI did; restating the pin in `additional_dependencies` would have put a second copy of it somewhere nothing keeps in sync. (#7)
+
+### Fixed
+
+- **The package could not be built at all.** `packages` already carries everything under the package directory, so the `force-include` table naming the profiles/mapping/catalogs trees re-added each file at a path the wheel already held, which hatchling treats as fatal. Every `uv build` failed, on every commit this project has ever had. Nothing caught it because the test suite exercises the source tree rather than the built artifact, so `publish.yml` now asserts the wheel's contents directly. The sdist additionally excludes the agent and issue-tracker symlinks, which are untracked and absent from a clean checkout but break a local build on their absolute link targets. (#8)
+- `Emitter.stop(graceful=False)` did not type-check, leaving `main` red from the 0.18 pin bump onward. `ebus-sdk` 0.18 ships a `py.typed` marker, so mypy stopped resolving the SDK to `Any` and started reading its real types, and `Device.mqttc` is typed `MqttDeviceTransport`, which deliberately omits `start`/`stop`: that omission *is* the SDK's no-start/no-stop guarantee, expressed as a type. `stop` resolves only on the concrete client the SDK builds and owns. Now narrowed at runtime in the SDK seam. Thanks to [@cayossarian](https://github.com/cayossarian), who found this independently and contributed the fix. (#7)
+
+## [0.2.0] - 2026-08-01
+
+### Fixed
+
+- **BREAKING (wire):** circuit `meter/imported-energy` and `meter/exported-energy` are now published in the enclosure reference frame, matching the already-enclosure-framed `meter/active-power` and real panel firmware. Previously a load circuit published a rising `imported-energy` while its `active-power` was negative, so integrating the published power grew the opposite accumulator (every load looked like it produced energy). Consumers that compensated for the old inverted behaviour must drop the workaround; consumers written against real panel firmware need no change. Lugs metering is unchanged (the frames coincide there). (#2, fixes #1)
+
+## [0.1.0] — 2026-05-02
+
+### Added
+
+- Initial scaffolding of the `ebus-panel-sim` package: wire layer (manifest/mapping/profiles,
+  graph builder, lifecycle, set router, SDK seam, property bag diff) and schedule runner
+  (clock, energy package, simulated circuits, solar curve evaluation, override store,
+  tick orchestration).
+- Public `Emitter` API: `start()`, `tick()`, `stop()`, `set_property_override()`,
+  `clear_property_override()`, `force_grid_state()`, `last_snapshot`, `topology_version`,
+  static `lwt_settings()`.
+- Vendored Homie 5 device profiles for panel, circuit, lugs, BESS, PV, EVSE (v1_flat).
+- Four canonical example manifest + runtime-spec pairs.
+- End-to-end mosquitto integration test.
+- 132 passing tests across `wire/`, `scheduleRunner/`, and integration suites.
+
+### Deferred
+
+- Full lift of the simulator's `RealisticBehaviorEngine` with cycling state, smart-load
+  noise, and HVAC seasonal modulation. v0.1.0 ships a stub that applies the runtime-
+  spec's pre-baked hour/monthly factors directly with deterministic noise.
+- v2_children topology (parent-child Homie schema). Pending the upstream `ebus-sdk` adding
+  parent/child support.

ebus_panel_sim-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to distribution-enclosure-simulator
+
+Thanks for your interest in contributing! This project (`ebus-panel-sim`) is a producer-side [Homie 5](https://homieiot.github.io) publisher and a fully-loaded distribution-enclosure simulator for the [Electrification Bus (eBus)](https://ebus.energy) 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 consumers can build and test against a realistic SPAN-like panel without beta firmware or a live installation. It began as a fork of Bill Flood's original simulator and now tracks the latest eBus specification.
+
+## How to contribute
+
+### Discussions
+
+Use [Discussions](https://github.com/electrification-bus/distribution-enclosure-simulator/discussions) for:
+
+- Open-ended questions about the simulator's design, the producer/emitter split, or the wire model ("how should the producer drive circuit X?")
+- Integration questions ("I'm building a consumer / dashboard / Home Assistant integration against the published tree, what's the recommended pattern?")
+- Proposed new device types, native behaviours, or profile/mapping changes worth aligning on before writing the code
+- Questions about the relationship between this simulator and the [Electrification Bus specification](https://github.com/electrification-bus/specification) (this repo aims to be a faithful producer of the spec; spec-level questions belong in the spec repo's Discussions)
+- Thinking out loud about a proposed change before scoping it
+
+Discussions are open-ended: a good place to align on direction before something becomes a concrete change. Aligned outcomes often turn into one or more Issues or pull requests.
+
+### Issues
+
+Use [Issues](https://github.com/electrification-bus/distribution-enclosure-simulator/issues) for actionable changes:
+
+- Bug reports with reproduction steps (the YAML device definition, broker, and a code snippet or the published topics you saw versus expected)
+- Spec-conformance gaps where the published tree diverges from the [Electrification Bus specification](https://github.com/electrification-bus/specification) (note which spec document, capability catalog, and section)
+- Concrete feature requests with a clear scope and a use case
+- Documentation gaps where a specific README, example, or docstring change is intended
+- Discussion outcomes that have alignment and a clear scope
+
+If you're not sure whether something is an Issue or a Discussion, start with a Discussion: we can convert it later.
+
+### Pull requests
+
+Pull requests are welcome.
+
+- For small fixes (typos, docstring tweaks, version bumps, low-risk bug fixes with a test), open a PR directly.
+- For substantive changes (new public API surface, changes to `TickInputs` or the manifest contract, new device types, changes that alter discovery/topic structure or property semantics), open a Discussion or Issue first so we can align on scope before you invest the effort.
+- **Spec conformance is the north star.** This simulator exists to publish a spec-conformant eBus Homie tree. When a PR's behaviour is normative (device states, property contracts, topic structure, capability surface), point to the spec section it implements. The wire type contract is single-sourced from the vendored spec capability catalogs and guarded by `tests/test_catalog_drift.py`; if you touch a capability, keep the catalog and the lockfile (`.ebus-spec.json`) in sync. If the spec is ambiguous or wrong, file an Issue against the spec repo first and reference it from the PR here.
+- **Respect the producer/emitter boundary.** The producer computes generation-side physics and hands the emitter a per-tick driving signal via `TickInputs`; the emitter derives wire-facing telemetry and publishes it. Keep generation models out of the emitter (see `DESIGN.md` and `DEVELOPER.md`).
+- **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.
+
+## 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.
+
+```bash
+uv sync --group dev                       # create .venv, install runtime + dev deps
+uv run pre-commit install                 # install the pre-commit hooks
+uv run pytest                             # tests
+uv run ruff check --fix src/ tests/       # lint
+uv run ruff format src/ tests/            # format
+uv run mypy --strict src/ebus_panel_sim/       # type check (strict)
+```
+
+Every commit is validated by pre-commit and by the [`ci.yaml`](.github/workflows/ci.yaml) workflow (ruff, ruff-format, mypy `--strict`, pytest). Run the gates locally before pushing; new behaviour needs a test, and bug fixes need a regression test.
+
+## Releases
+
+`ebus-panel-sim` is published to [PyPI](https://pypi.org/project/ebus-panel-sim/). Releases are tag-triggered: pushing a `v*` tag runs `.github/workflows/publish.yml`, which re-runs the gates against the tag, builds, uploads via PyPI trusted publishing (OIDC, no stored token), and mirrors the release to GitHub Releases using the tag's `CHANGELOG.md` section.
+
+A release-worthy change bumps `__version__` in `src/ebus_panel_sim/__init__.py`, the single source of truth, and adds a `CHANGELOG.md` entry under a matching `## [x.y.z]` heading. Do not restate the version in `pyproject.toml`; `[tool.hatch.version]` reads it. The publish workflow refuses to upload when the tag and `__version__` disagree, because a PyPI upload can never be replaced.
+
+## Code of conduct
+
+Be respectful and constructive. We appreciate everyone who takes the time to file an issue, start a discussion, or send a pull request.
+
+## Maintenance posture
+
+This is an active alpha project. Updates and maintenance, including responses to issues filed on GitHub, happen on an "as time and resources permit" basis. It is maintained alongside the [Electrification Bus specification](https://github.com/electrification-bus/specification) and the eBus SDK.

ebus_panel_sim-0.3.0/DESIGN.md

@@ -0,0 +1,89 @@
+# ebus-panel-sim design
+
+Internals of the emitter. For what it is and how to run/configure it, see [README.md](README.md).
+
+## The per-tick pipeline
+
+The producer builds a `DeviceManifest` (identity plus physics keys per device) at startup and hands it to `Emitter` together with a `SetterRegistry`, an `mqtt_cfg` (the broker coordinates ebus-sdk connects with), zero or more `BESSConfig`s, and an optional `LoadSheddingConfig`. Each tick the producer builds a `TickInputs` (signed power per circuit, current time, grid-online flag, panel envelope) and calls `emitter.publish_tick(tick_inputs)`. Inside, the emitter:
+
+1. Resolves BESS dispatch (charge/discharge/idle) for every native BESS.
+2. Decides load-shedding (which circuits open when off-grid).
+3. Applies relay-state precedence and gates per-circuit power.
+4. Integrates energy per circuit/EVSE via `EnergyIntegrator`.
+5. Computes per-leg currents and panel meter aggregates via `PanelMeter`.
+6. Assembles an `EbusPanelSnapshot` and publishes the Homie diff to MQTT (only changed properties are retransmitted).
+
+## Wire model
+
+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.
+
+## Native devices
+
+Two device classes are not pure publishers: their behaviour runs inside the emitter.
+
+### BESS (`ebus_panel_sim.native_devices.bess`)
+
+Owns the dispatch decision, SOC/SOE accumulation, mode behaviour (self-consumption / backup-only), and the backup-reserve floor. (The `charge_hours` / `discharge_hours` config fields exist but are inert: the dispatch logic never reads them, and hour-of-day / TOU windows are explicitly not modelled.) Instantiated when `Emitter` is constructed with `bess_configs`, a tuple of `BESSConfig` (default empty). One `BESSDevice` is created per config, keyed by `BESSConfig.instance_id`; duplicate instance IDs raise `EmitterStateError`.
+
+Per-tick inputs (from `TickInputs`): `current_time` (received but not consulted by the current dispatch logic; hour-of-day windows are not modelled), `grid_online` (when false the BESS discharges to meet `load_demand - pv_available`), and the derived `load_demand_w` (sum of positive circuit powers) and `pv_available_w` (magnitude of the negative circuit powers).
+
+Per-tick outputs (into `snapshot.battery`): `soe_percentage`, `soe_kwh`, and `active_power_w` (positive = discharging, negative = charging).
+
+Mid-run config changes: `emitter.update_bess_config(new_config)` swaps the `BESSConfig` reference while SOC/SOE state persists (the path for dashboard edits to mode and max charge/discharge rates; the charge/discharge hour-window fields are carried but not yet applied by the dispatch logic). Persistence across restart: call `emitter.seed_bess_soe(instance_id, soe_kwh)` between `__init__` and `start()`, or declare `initial-soe-kwh` in the manifest. Subclassing `BESSDevice` is supported for vendor-variant behaviour without a plugin framework.
+
+### Load shedding (`ebus_panel_sim.native_devices.load_shedding`)
+
+When the grid is offline the policy returns the circuit instance-ids whose priority is `OFF_GRID`, plus those with `SOC_THRESHOLD` priority once the live SOC falls below `soc_threshold_pct`. The emitter writes that decision into the `RelayResolver` shed map; final relay state is then resolved by the precedence rules below. Mid-run config: `emitter.update_load_shedding_config(new_config)`.
+
+## Settable properties (`/set`)
+
+`/set` commands arrive on the child device's settable-property topics (for example `ebus/5/<circuit-id>/switch/relay/set`) and are dispatched through the `SetterRegistry`. The emitter installs internal default handlers for the settable properties when the producer has not supplied one; producer-supplied handlers always win.
+
+| Entity class | Property | Effect |
+|---|---|---|
+| circuit | `switch/relay` | Updates the `RelayResolver` user override |
+| circuit | `load-shed/priority` | Updates the emitter's per-circuit priority override |
+| panel | `shed/asserted-islanding-state` | Updates the consumer-asserted islanding override |
+| evse | `config/user-max-charge-current` | Updates the per-EVSE user charge-current ceiling |
+
+### Relay state precedence
+
+```text
+always-on > /set override > load-shed > default-CLOSED
+```
+
+- `always-on` circuits (`relay-behavior=always-on`) ignore both `/set` and load-shed; the relay is permanently CLOSED. `switch/relay-requester` reports `CONFIGURATION`.
+- A `/set` override takes effect on the next tick, with no debounce, and can override a safety-shed. `switch/relay-requester` reports `USER`.
+- Load-shed applies only when there is no `/set` override. `switch/relay-requester` reports `LOAD_SHED`.
+- Default-CLOSED is the resting state when no decision-maker has spoken. `switch/relay-requester` reports `NONE`.
+
+Relay changes reach the wire on the next `publish_tick`, bounded by the producer's tick cadence (typically 1.0 s).
+
+## Energy integration
+
+`EnergyIntegrator` accumulates per-circuit (and per-EVSE) `consumed_wh` / `produced_wh` across ticks using `dt = current_time - last_tick_time` per instance. Seed values at startup with `emitter.seed_energy("kitchen", consumed_wh=12345.0, produced_wh=0.0)`, or via the manifest `initial-consumed-wh` / `initial-produced-wh` keys. Either path adds a new circuit to a running deployment without zeroing existing accumulators.
+
+## Tab-to-leg convention
+
+`legs_for_tabs((tab, ...)) -> tuple[Leg, ...]` in `ebus_panel_sim.conventions.tab_legs` is the single source of truth for the US residential split-phase convention: odd-numbered tabs land on L1, even-numbered on L2, and a 240 V circuit occupies tabs on both legs. It is isolated so non-US / 3-phase support can land there later without touching `PanelMeter` or the per-leg current calculations.
+
+## Snapshot read-back
+
+`emitter.last_snapshot` returns the most recently published `EbusPanelSnapshot`. Consumers (dashboards, HA-API endpoints) read aggregated state through this property; they do not construct snapshots.
+
+## What lives where
+
+| Concern | Owner |
+|---|---|
+| Homie wire mechanics (`$description`/`$state`, parent-child arrays, retained topics + value encoding, LWT) | ebus-sdk (emitter builds the `Device` tree + capability nodes and drives the start/stop lifecycle) |
+| Device profiles + property graph + diff publishing | emitter |
+| Settable-property routing (`/set` to internal state) | emitter |
+| Relay state machine (always-on > /set > shed > default-CLOSED) | emitter |
+| BESS dispatch + SOC/SOE integration | emitter |
+| Load-shedding policy (SOC threshold, off-grid priority) | emitter |
+| Energy integration + per-leg current + panel meter aggregation | emitter |
+| Device identity + static attributes (vendor, serial, ratings, tabs) | producer (via manifest) |
+| Per-circuit / per-EVSE signed power, `current_time`, `grid_online`, envelope | producer (per tick) |
+| Weather, schedules, rates, modelling, recorder/replay history | producer |

ebus_panel_sim-0.3.0/DEVELOPER.md

@@ -0,0 +1,145 @@
+# Developer Guide
+
+## Prerequisites
+
+- Python >= 3.11 (`pyproject.toml` sets `requires-python = ">=3.11"`); developed and CI-tested on 3.11 and 3.14
+- [uv](https://docs.astral.sh/uv/) (`brew install uv` on macOS)
+
+## Setup
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/electrification-bus/distribution-enclosure-simulator.git
+cd distribution-enclosure-simulator
+
+# Create venv and install all dependencies (runtime + dev)
+# uv reads pyproject.toml and uv.lock, creates .venv/ automatically
+uv sync --group dev
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+That's it. The `.venv/` directory is created in the project root and `uv.lock` pins exact versions for reproducible installs.
+
+## Common Commands
+
+```bash
+# Run the standalone example (a producer driving the emitter over a broker)
+uv run python examples/run_forty_tab_minimal.py
+
+# Run tests
+uv run pytest
+
+# Lint + format
+uv run ruff check --fix src tests
+uv run ruff format src tests
+
+# Type check (strict; matches the pre-commit hook)
+uv run mypy --strict src/ebus_panel_sim tests
+
+# Add a new dependency
+uv add <package>          # runtime
+uv add --group dev <pkg>  # dev only
+```
+
+This package has no console entry point (`pyproject.toml` defines no `[project.scripts]`): it is a producer library. The `examples/` directory is the runnable demonstration of correct output.
+
+## Pre-commit Hooks
+
+Every commit is validated by:
+
+| Hook | What it checks |
+|---|---|
+| **ruff** | Lint rules (E, F, W, I, UP, B, SIM, TCH, RUF) with auto-fix |
+| **ruff-format** | Consistent formatting |
+| **mypy --strict** | Full strict type checking across `src/ebus_panel_sim` and `tests` |
+| **trailing-whitespace** | No trailing whitespace |
+| **end-of-file-fixer** | Files end with a newline |
+| **check-yaml** | Valid YAML syntax |
+| **check-added-large-files** | Prevents accidental large file commits |
+
+## Emitter Internals
+
+The emitter is the **publisher** half of the eBus producer/emitter split: the producer (a simulator, a real gateway, or a modelling agent) computes the generation-side physics (solar curves, HVAC modulation, weather, battery schedules) and hands the emitter a per-tick driving signal via `TickInputs`. The emitter derives wire-facing telemetry from that signal and publishes it. It does **not** run the generation models itself.
+
+### Per-tick flow
+
+Each tick, given `TickInputs` (signed power per circuit, current time, grid-online flag):
+
+1. Resolve per-circuit relay state, applying strict precedence across command sources (`relay_resolver.py`).
+2. Run native-device behaviours that own their own state (`native_devices/`): BESS dispatch (`bess.py`) and load shedding (`load_shedding.py`).
+3. Derive gated per-circuit power, then aggregate panel-level meter values (`panel_meter.py`, a pure function).
+4. Integrate energy in watt-hours per instance (`energy_integrator.py`).
+5. Translate the resulting snapshot into a `PropertyBag` and diff-publish (`wire/bag_builder.py`, `wire/property_bag.py`, `wire/publisher.py`).
+
+Device identity and static attributes come from the producer once at startup via the `DeviceManifest` (`manifest.py`); dynamic telemetry is derived here. The split is **identity = manifest, telemetry = derived from TickInputs**.
+
+### Energy Accumulation
+
+Energy integrates over time in watt-hours:
+
+```
+delta_energy = power_watts * delta_seconds / 3600
+```
+
+Consumed and produced energy are tracked separately per circuit, seeded from producer-supplied starting values.
+
+### Diffing
+
+Only changed property values are republished each tick (`wire/property_bag.py` holds the diff cache; `wire/publisher.py` owns the loop). Unchanged values are not retransmitted.
+
+## Directory Layout
+
+```
+distribution-enclosure-simulator/
+  pyproject.toml               # Package metadata, deps, ruff/mypy/pytest config
+  uv.lock                      # Pinned dependency versions
+  README.md                    # Overview and usage
+  DEVELOPER.md                 # This guide
+  CHANGELOG.md
+  LICENSE
+  AGENTS.md                    # Agent rules (no AI attribution in commits)
+  .pre-commit-config.yaml
+  .python-version
+  .github/workflows/
+    ci.yaml                    # CI: ruff, ruff-format, mypy --strict, pytest
+  examples/
+    forty_tab_minimal.yaml     # Example device manifest
+    run_forty_tab_minimal.py   # Minimal standalone producer + emitter demo
+  src/ebus_panel_sim/
+    __init__.py                # Public surface
+    emitter.py                 # Public Emitter facade (wire publisher + native runtime)
+    tick_inputs.py             # TickInputs: the producer/emitter per-tick contract
+    manifest.py                # Producer-supplied device identity manifest
+    manifest_physics.py        # Typed accessor over device metadata (physics fields)
+    relay_resolver.py          # Per-circuit relay state with strict command precedence
+    energy_integrator.py       # Per-instance watt-hour energy accumulator
+    panel_meter.py             # Panel-level aggregator (pure function)
+    snapshot.py                # Per-tick snapshot dataclasses (internal model)
+    exceptions.py              # Public exception hierarchy
+    conventions/
+      tab_legs.py              # Tab-to-leg convention for split-phase panels
+    native_devices/            # Emitter-native device behaviours
+      bess.py                  # Native BESS (configured, self-driving)
+      load_shedding.py         # Native load-shedding controller
+      protocol.py              # Native-device tick contract
+    wire/                      # Homie 5 wire production over ebus-sdk
+      graph_builder.py         # Manifest + mappings + profiles -> SDK Device graph
+      profile_loader.py        # Load vendored Homie 5 profile JSONs
+      mapping_loader.py        # Load vendored mapping descriptor YAMLs
+      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
+      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)
+    conftest.py
+    conventions/               # convention tests
+    wire/                      # wire-layer tests
+    test_*.py                  # unit tests (manifest, energy, relay, panel meter, ...)
+```

ebus_panel_sim-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bill Flood, Clark Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.