ebus-panel-sim 0.3.0__py3-none-any.whl

ebus_panel_sim/__init__.py

@@ -0,0 +1,119 @@
+"""ebus-panel-sim — producer-side Homie wire publisher with native-device runtime.
+
+Architecture (v0.3.0):
+
+- **Wire layer** (``wire/``): vendored Homie 5 device profiles + mapping descriptors,
+  graph builder, diff-only publisher, /set setter fan-in, and the property/bag diff
+  cache over a thin ebus-sdk seam (ebus-sdk owns $description/$state/LWT/encoding).
+- **Native devices** (``native_devices/``): emitter-resident, configured-and-self-driving
+  device runtimes (BESS dispatch, load shedding).
+- **Manifest physics** (``manifest_physics.py``): typed accessor over
+  ``DeviceInstance.metadata`` for physics-relevant fields (voltage, breaker rating,
+  tabs/legs, placement, default priority, relay behaviour).
+- **Tick pipeline** (``relay_resolver.py`` + ``energy_integrator.py`` + ``panel_meter.py``
+  + ``conventions/tab_legs.py``): per-tick state machinery the emitter uses to
+  resolve circuit relay state, integrate energy, derive per-leg currents, and
+  aggregate panel-level fields.
+
+Producer contract (v0.3.0): build a ``DeviceManifest`` once at startup, then call
+``Emitter.publish_tick(TickInputs)`` each tick with signed circuit/EVSE powers,
+``current_time``, and ``grid_online``. The emitter does the rest."""
+
+from ebus_panel_sim.conventions.tab_legs import Leg, legs_for_tabs
+from ebus_panel_sim.emitter import Emitter
+from ebus_panel_sim.exceptions import (
+    EmitterError,
+    EmitterStateError,
+    ManifestValidationError,
+    MissingSetterError,
+    ProfileValidationError,
+    RuntimeSpecValidationError,
+)
+from ebus_panel_sim.manifest import DeviceInstance, DeviceManifest
+from ebus_panel_sim.manifest_physics import (
+    BessPhysics,
+    CircuitPhysics,
+    EvsePhysics,
+    LugsPhysics,
+    ManifestPhysicsView,
+    PanelPhysics,
+    PvPhysics,
+)
+from ebus_panel_sim.native_devices import (
+    BESSConfig,
+    BESSDevice,
+    LoadSheddingConfig,
+    LoadSheddingDevice,
+    NativeDevice,
+    NativeTickContext,
+)
+from ebus_panel_sim.relay_resolver import RelayRequester, RelayResolver, RelayState
+from ebus_panel_sim.snapshot import (
+    EbusBatterySnapshot,
+    EbusCircuitSnapshot,
+    EbusEvseSnapshot,
+    EbusLugsSnapshot,
+    EbusPanelDoor,
+    EbusPanelInfo,
+    EbusPanelMeter,
+    EbusPanelPcs,
+    EbusPanelPowerFlows,
+    EbusPanelSnapshot,
+    EbusPanelStatus,
+    EbusPvSnapshot,
+)
+from ebus_panel_sim.tick_inputs import PanelEnvelopeTick, TickInputs
+from ebus_panel_sim.wire.set_router import SetterHandler, SetterRegistry
+
+# Single source of truth for the distribution version: pyproject reads it from here
+# via `[tool.hatch.version]`, and publish.yml refuses to release when the git tag
+# disagrees. Bump it in this one place. Note this is the PACKAGE version and is
+# distinct from the producer-contract version the docstrings above refer to.
+__version__ = "0.3.0"
+
+__all__ = [
+    "BESSConfig",
+    "BESSDevice",
+    "BessPhysics",
+    "CircuitPhysics",
+    "DeviceInstance",
+    "DeviceManifest",
+    "EbusBatterySnapshot",
+    "EbusCircuitSnapshot",
+    "EbusEvseSnapshot",
+    "EbusLugsSnapshot",
+    "EbusPanelDoor",
+    "EbusPanelInfo",
+    "EbusPanelMeter",
+    "EbusPanelPcs",
+    "EbusPanelPowerFlows",
+    "EbusPanelSnapshot",
+    "EbusPanelStatus",
+    "EbusPvSnapshot",
+    "Emitter",
+    "EmitterError",
+    "EmitterStateError",
+    "EvsePhysics",
+    "Leg",
+    "LoadSheddingConfig",
+    "LoadSheddingDevice",
+    "LugsPhysics",
+    "ManifestPhysicsView",
+    "ManifestValidationError",
+    "MissingSetterError",
+    "NativeDevice",
+    "NativeTickContext",
+    "PanelEnvelopeTick",
+    "PanelPhysics",
+    "ProfileValidationError",
+    "PvPhysics",
+    "RelayRequester",
+    "RelayResolver",
+    "RelayState",
+    "RuntimeSpecValidationError",
+    "SetterHandler",
+    "SetterRegistry",
+    "TickInputs",
+    "__version__",
+    "legs_for_tabs",
+]

ebus_panel_sim/conventions/__init__.py

@@ -0,0 +1,11 @@
+"""Centralized panel-wiring conventions used across the emitter.
+
+Each module in this package isolates a single physical-layer convention so the
+rest of the codebase can be convention-agnostic. Convention changes (e.g.,
+supporting European single-phase or 3-phase commercial panels) land here without
+rippling into ``PanelMeter``, ``EnergyIntegrator``, or per-property derivations.
+"""
+
+from ebus_panel_sim.conventions.tab_legs import Leg, legs_for_tabs
+
+__all__ = ["Leg", "legs_for_tabs"]

ebus_panel_sim/conventions/tab_legs.py

@@ -0,0 +1,47 @@
+"""Tab-to-leg assignment convention for US residential split-phase panels.
+
+US residential load centers alternate breaker slots between L1 and L2: odd-numbered
+tabs land on L1, even-numbered tabs land on L2. A 240 V dipole circuit occupies
+two adjacent tabs (e.g. 1 and 2) — one per leg.
+
+This module is the single source of truth for that convention. Per-leg current
+calculations in ``PanelMeter`` and the per-circuit ``current_a`` derivation go
+through ``legs_for_tabs`` rather than reaching for ``tab % 2`` directly.
+
+Future support for non-US panels (European single-phase, 3-phase commercial) lands
+here as an additional ``Convention`` enum + dispatch, without touching call sites."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Leg(StrEnum):
+    """A panel power leg. ``L1`` and ``L2`` are the two 120 V legs of a US
+    residential split-phase service; line-to-line voltage between them is 240 V."""
+
+    L1 = "L1"
+    L2 = "L2"
+
+
+def legs_for_tabs(tabs: tuple[int, ...]) -> tuple[Leg, ...]:
+    """Return the leg assignment for each tab in ``tabs``, US residential
+    convention: odd tabs → L1, even tabs → L2.
+
+    Examples:
+        >>> legs_for_tabs((1,))
+        (<Leg.L1: 'L1'>,)
+        >>> legs_for_tabs((2,))
+        (<Leg.L2: 'L2'>,)
+        >>> legs_for_tabs((1, 2))     # standard dipole
+        (<Leg.L1: 'L1'>, <Leg.L2: 'L2'>)
+        >>> legs_for_tabs((1, 3))     # both on L1 — invalid for a dipole
+        (<Leg.L1: 'L1'>, <Leg.L1: 'L1'>)
+
+    The function does not enforce dipole leg-spanning — that's the validation
+    job of ``ManifestPhysicsView``, which sees the ``dipole`` flag.
+
+    Raises ``ValueError`` if any tab is < 1 (panel tabs are 1-indexed)."""
+    if any(t < 1 for t in tabs):
+        raise ValueError(f"tab numbers must be >= 1; got {tabs!r}")
+    return tuple(Leg.L1 if t % 2 == 1 else Leg.L2 for t in tabs)