ekm-proxy 0.1.0__py3-none-any.whl

ekm_proxy/__init__.py

@@ -0,0 +1,3 @@
+"""ekm-proxy: publish EKM Metering devices onto the Electrification Bus (Homie 5)."""
+
+__version__ = "0.1.0"

ekm_proxy/cli.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+import argparse
+import signal
+import sys
+
+from .config import load
+from .sources import build_source
+from .emitter import EbusEmitter
+
+
+def _install_sigterm(handler):
+    # SIGINT already surfaces as KeyboardInterrupt; translate SIGTERM (systemd
+    # stop / `kill`) into the same graceful path so the `finally` teardown runs.
+    signal.signal(signal.SIGTERM, handler)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="ekm-proxy")
+    ap.add_argument("--config", required=True)
+    args = ap.parse_args(argv)
+
+    cfg = load(args.config)
+    source = build_source(cfg)
+    emitter = EbusEmitter(cfg["ebus"])
+    print(f"ekm-proxy: source={cfg['source']['kind']} -> ebus/5", file=sys.stderr)
+
+    _install_sigterm(lambda *_: sys.exit(0))
+
+    try:
+        for reading in source.stream():
+            if reading.kind != "meter":
+                continue  # ioStack sensors deferred (homie/5); see README
+            emitter.publish(reading)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # Bounded clean shutdown: publish $state=disconnected, suppress the LWT.
+        emitter.stop()
+
+
+if __name__ == "__main__":
+    main()

ekm_proxy/config.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib  # type: ignore
+
+
+def load(path: str) -> dict:
+    with open(path, "rb") as f:
+        return tomllib.load(f)

ekm_proxy/emitter.py

@@ -0,0 +1,197 @@
+"""Homie 5 emitter/adapter: publish EKM meter-points onto eBus via ebus-sdk.
+
+The proxy is an eBus proxier of type `energy.ebus.device.bridge`: a single root
+"bridge" device anchors the Homie tree and owns the MQTT connection, and each
+proxied EKM meter is published as a child `energy.ebus.device.circuit` bearing
+the `meter` capability (behind-the-meter sub-metering is a capability on a host
+circuit, not a standalone device type; see the spec's data-models/circuit.md),
+named `{proxier-id}-{serial}` per the proxy convention. The bridge publishes only
+an `info` capability identifying the proxy publisher; the metering data lives on
+the child circuits.
+
+Each meter's fields are resolved with `ebus_sdk.resolve` (the EKM domain mapper
+`EKM_MAP` first, HA-discovery `ha_fallback` for the rest), and the result is
+built into an observable model + Homie tree in one call via
+`ebus_sdk.build_from_declarations` (see doc/building-a-proxy.md). Sources only
+update the model; publishing is a reactive side-effect.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from ebus_sdk import (
+    Device,
+    DeviceState,
+    GroupedPropertyDict,
+    PropertyDatatype,
+    PropertySpec,
+    build_from_declarations,
+    ebus_cfg_add_auth,
+    resolve,
+    sanitize_homie_id,
+    specs_and_values,
+)
+from ebus_sdk.ha import HA_ECOSYSTEM, imported_extension, imported_from_attribute
+
+from .mapping import CIRCUIT_TYPE, EKM_MAP, ha_fallback, normalize_fields
+
+ROOT_TYPE = "energy.ebus.device.bridge"
+INFO_CAPABILITY = "energy.ebus.capability.info"
+
+_CAP_NODE_NAMES = {
+    "info": "Meter identity",
+    "meter": "Electrical measurements",
+    "demand": "Demand",
+    "status": "Meter status",
+}
+
+
+def _node_name(capability: str) -> str:
+    return _CAP_NODE_NAMES.get(capability, capability)
+
+
+class EbusEmitter:
+    def __init__(self, cfg: dict):
+        self.proxier_id = sanitize_homie_id(cfg.get("proxier_id") or "ekm-proxy")
+        self.vendor_name = cfg.get("vendor_name", "ekm-proxy")
+        self.root_name = cfg.get("name", "EKM Proxy")
+        self._mqtt_cfg = self._build_mqtt_cfg(cfg)
+        self._root: Optional[Device] = None
+        self._models: dict[str, GroupedPropertyDict] = {}  # serial -> observable model
+        self._devices: dict[str, Device] = {}  # serial -> homie child device
+        self._available: dict[str, Optional[bool]] = {}  # serial -> last published availability
+
+    @staticmethod
+    def _build_mqtt_cfg(cfg: dict) -> dict:
+        mqtt_cfg = {
+            "host": os.path.expandvars(cfg.get("host", "localhost")),
+            "port": int(cfg.get("port", 1883)),
+        }
+        user = os.path.expandvars(cfg.get("username", "")) or None
+        if user:
+            ebus_cfg_add_auth(mqtt_cfg, user, os.environ.get("EBUS_MQTT_PASS"))
+        return mqtt_cfg
+
+    @staticmethod
+    def _wait_connected(device: Device, timeout: float = 5.0) -> None:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if device.mqttc is not None and device.mqttc.is_connected():
+                return
+            time.sleep(0.05)
+
+    def device_id(self, serial: str) -> str:
+        # {proxier-id}-{proxied-id} per proxy.md; sanitize each segment independently.
+        return f"{self.proxier_id}-{sanitize_homie_id(serial)}"
+
+    # ── root bridge ──
+
+    def _ensure_root(self) -> Device:
+        if self._root is not None:
+            return self._root
+        root = Device(self.proxier_id, name=self.root_name, type=ROOT_TYPE, mqtt_cfg=self._mqtt_cfg)
+        root.start_mqtt_client()
+        # Publish only once connected, so the first retained $description/$state
+        # the broker keeps is the correct one (not a pre-connect empty snapshot).
+        self._wait_connected(root)
+        with root.state_transition():
+            info = root.add_node_from_dict({"id": "info", "name": "Proxy identity", "type": INFO_CAPABILITY})
+            info.add_property_from_dict(
+                {"id": "vendor-name", "datatype": PropertyDatatype.STRING, "value": self.vendor_name}
+            )
+        self._root = root
+        return root
+
+    # ── per-meter circuit ──
+
+    def publish(self, reading) -> None:
+        """Create the circuit model+device on first sight, else update its values."""
+        self._ensure_root()
+        serial = reading.device_id
+        if serial not in self._models:
+            self._create_circuit(reading)
+        else:
+            self._apply_values(self._models[serial], reading)
+        self._update_state(reading)
+
+    def _resolve(self, reading):
+        field_names = reading.schema_fields or list(reading.fields.keys())
+        fields = normalize_fields(reading.fields)
+        return resolve(field_names, fields, EKM_MAP, fallback=ha_fallback(reading.components_by_field))
+
+    def _create_circuit(self, reading) -> None:
+        serial = reading.device_id
+        resolved = self._resolve(reading)
+
+        # info capability: device metadata (reading.info) plus any mapped info fields.
+        # On a circuit realized by a distinct instrument (a proxied EKM meter-point),
+        # the nameplate identity properties (vendor-name/serial-number/model/
+        # firmware-version) record the measuring instrument, alongside info/name for
+        # the conductor (capabilities/info.md §Nameplate versus conductor identity).
+        info_values = dict(reading.info or {})
+        for r in resolved:
+            if r.spec.capability == "info" and r.value is not None:
+                info_values.setdefault(r.spec.prop_id, r.value)
+        # Mirror the EKM serial into external-ids as a cross-system reference,
+        # complementary to the nameplate serial-number (circuit.md allows this).
+        info_values.setdefault("external-ids", f"ekm:{serial}")
+
+        info_specs = [PropertySpec("info", pid, PropertyDatatype.STRING) for pid in info_values]
+        non_info_specs, non_info_values = specs_and_values(r for r in resolved if r.spec.capability != "info")
+        specs = info_specs + non_info_specs
+        values = {("info", pid): val for pid, val in info_values.items()}
+        values.update(non_info_values)
+
+        # Each circuit is created from Home Assistant MQTT discovery, so mark it
+        # imported (Guard B): the `energy.ebus.imported` extension plus an
+        # `imported-from: ha` $description attribute. A co-resident eBus->HA
+        # bridge (ebus_sdk.ha.HaDiscoveryBridge, skip_reimport default) then skips
+        # these rather than echoing them back to Home Assistant.
+        device = Device(
+            self.device_id(serial),
+            name=reading.name or f"EKM {serial}",
+            type=CIRCUIT_TYPE,
+            parent=self._root,
+            extensions=[imported_extension()],
+            description_extras=imported_from_attribute(HA_ECOSYSTEM),
+        )
+        model = GroupedPropertyDict()
+        build_from_declarations(device, model, specs, node_name=_node_name, values=values)
+        self._models[serial] = model
+        self._devices[serial] = device
+
+    def _apply_values(self, model: GroupedPropertyDict, reading) -> None:
+        for r in self._resolve(reading):
+            if r.value is not None:
+                model.set_value(r.spec.capability, r.spec.prop_id, r.value)
+
+    def stop(self) -> None:
+        """Cleanly tear down the published tree on shutdown.
+
+        `Device.stop()` is a tree-level teardown: it publishes a final
+        `$state=disconnected` on the root (covering every child per the Homie 5
+        effective-state rule) and performs a clean MQTT disconnect that
+        suppresses the LWT, so consumers see a tidy exit rather than a stale
+        `ready` or a badly-disconnected `lost`. It is bounded even if the broker
+        is unreachable, so it never stalls a shutting-down process.
+        """
+        if self._root is not None:
+            self._root.stop()
+            self._root = None
+
+    def _update_state(self, reading) -> None:
+        if reading.available is None:
+            return
+        serial = reading.device_id
+        if self._available.get(serial) == reading.available:
+            return
+        device = self._devices.get(serial)
+        if device is None:
+            return
+        state = DeviceState.READY if reading.available else DeviceState.LOST
+        device.set_state(state)
+        device.publish_state(state)
+        self._available[serial] = reading.available

ekm_proxy/mapping.py

@@ -0,0 +1,122 @@
+"""EKM readMeter field -> eBus property mapping (the EKM domain-specific mapper).
+
+Every source normalizes to a readMeter-style dict ({ekm_field: value, ...}).
+`EKM_MAP` is the hand-authored, authoritative `{ekm_field: PropertySpec}` table
+for the `meter` (and `demand`) capability an EKM meter-point publishes as an
+`energy.ebus.device.circuit` (the eBus capability-on-host model): it fixes the
+eBus capability, property name, canonical unit, and any unit `scale` (EKM reports
+energy in kWh; eBus is Wh, so energy carries scale=1000; per-phase fields get
+-a/-b/-c suffixes, per the canonical catalog in the spec's capabilities/meter.md).
+
+The emitter passes `EKM_MAP` to `ebus_sdk.resolve` as the authoritative domain
+`mapping`, and `ha_fallback(...)` as the general-HA `fallback`, so a field with
+no EKM entry is still covered from its Home Assistant discovery metadata. Fields
+with neither an eBus home nor an HA hint are HELD (see ORPHANS), documented
+rather than silently dropped.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from ebus_sdk import PropertyDatatype, PropertySpec, Unit
+from ebus_sdk.ha import derive_spec
+
+# The eBus device type each proxied EKM meter-point is published as: a circuit
+# bearing the `meter` capability (behind-the-meter sub-metering is a capability on
+# a host device, not a standalone device type; see the spec's data-models/circuit.md
+# and capabilities/meter.md). Per-conductor legs are -a/-b/-c property suffixes on
+# the one device, not separate devices.
+CIRCUIT_TYPE = "energy.ebus.device.circuit"
+
+
+def _meas(capability: str, prop: str, unit: Unit, scale: float = 1.0) -> PropertySpec:
+    """A float physical-measurement property."""
+    return PropertySpec(capability, prop, PropertyDatatype.FLOAT, unit, scale)
+
+
+# ekm_field -> PropertySpec. Ln_1/2/3 -> phase suffix -a/-b/-c. EKM energy is
+# reported in kWh; eBus canonical energy is Wh, hence scale=1000 on energy.
+METER_MAP: dict[str, PropertySpec] = {
+    "kWh_Tot": _meas("meter", "imported-energy", Unit.WATT_HOUR, 1000.0),
+    "Rev_kWh_Tot": _meas("meter", "exported-energy", Unit.WATT_HOUR, 1000.0),
+    "RMS_Watts_Tot": _meas("meter", "active-power", Unit.WATT),
+    "Reactive_Pwr_Tot": _meas("meter", "reactive-power", Unit.VOLT_AMPERE_REACTIVE),
+    "Line_Freq": _meas("meter", "frequency", Unit.HERTZ),
+    "RMS_Volts_Ln_1": _meas("meter", "voltage-a", Unit.VOLTS),
+    "RMS_Volts_Ln_2": _meas("meter", "voltage-b", Unit.VOLTS),
+    "RMS_Volts_Ln_3": _meas("meter", "voltage-c", Unit.VOLTS),
+    "Amps_Ln_1": _meas("meter", "current-a", Unit.AMPERE),
+    "Amps_Ln_2": _meas("meter", "current-b", Unit.AMPERE),
+    "Amps_Ln_3": _meas("meter", "current-c", Unit.AMPERE),
+    "RMS_Watts_Ln_1": _meas("meter", "active-power-a", Unit.WATT),
+    "RMS_Watts_Ln_2": _meas("meter", "active-power-b", Unit.WATT),
+    "RMS_Watts_Ln_3": _meas("meter", "active-power-c", Unit.WATT),
+    "Reactive_Pwr_Ln_1": _meas("meter", "reactive-power-a", Unit.VOLT_AMPERE_REACTIVE),
+    "Reactive_Pwr_Ln_2": _meas("meter", "reactive-power-b", Unit.VOLT_AMPERE_REACTIVE),
+    "Reactive_Pwr_Ln_3": _meas("meter", "reactive-power-c", Unit.VOLT_AMPERE_REACTIVE),
+}
+
+DEMAND_MAP: dict[str, PropertySpec] = {
+    "RMS_Watts_Max_Demand": _meas("demand", "peak-demand-this-period", Unit.WATT),
+    # eBus `demand/integration-window` is an integer number of SECONDS. EKM reports
+    # it as a period-select CODE, translated to seconds by `normalize_fields` before
+    # resolve (a lookup, not the linear `scale` resolve applies).
+    "Max_Demand_Period": PropertySpec("demand", "integration-window", PropertyDatatype.INTEGER, Unit.SECONDS),
+}
+
+# EKM `Max_Demand_Period` is a period-select code, not a duration: 1 -> 15 min,
+# 2 -> 30 min, 3 -> 60 min (ekmmeters MaxDemandPeriod). eBus wants seconds.
+_MAX_DEMAND_PERIOD_SECONDS: dict[int, int] = {1: 900, 2: 1800, 3: 3600}
+
+INFO_MAP: dict[str, PropertySpec] = {
+    "Model": PropertySpec("info", "model", PropertyDatatype.STRING),
+    "Firmware": PropertySpec("info", "firmware-version", PropertyDatatype.STRING),
+}
+
+# No eBus home yet -> HELD. Documented so the gap is explicit, not a silent drop.
+ORPHANS: dict[str, list[str]] = {
+    "tou": [f"kWh_Tariff_{i}" for i in range(1, 5)] + [f"Rev_kWh_Tariff_{i}" for i in range(1, 5)],
+    "pulse": [f"Pulse_Cnt_{i}" for i in range(1, 4)] + [f"Pulse_Ratio_{i}" for i in range(1, 4)],
+    "dio": ["State_Inputs", "State_Out", "State_Watts_Dir"],
+}
+
+# The EKM domain-specific mapper, passed to ebus_sdk.resolve() as `mapping`.
+EKM_MAP: dict[str, PropertySpec] = {**METER_MAP, **DEMAND_MAP, **INFO_MAP}
+
+
+def normalize_fields(fields: dict) -> dict:
+    """Translate EKM code-valued fields to the canonical units `EKM_MAP` expects.
+
+    `ebus_sdk.resolve` only applies a linear `scale`; a field whose EKM encoding is
+    a lookup rather than a multiply is converted here first. Currently only
+    `Max_Demand_Period` (period-select code -> `integration-window` seconds). Returns
+    `fields` unchanged when there is nothing to normalize and never mutates the input;
+    an unrecognized code resolves to None (published as absent/unknown).
+    """
+    code = fields.get("Max_Demand_Period")
+    if code is None:
+        return fields
+    out = dict(fields)
+    try:
+        out["Max_Demand_Period"] = _MAX_DEMAND_PERIOD_SECONDS.get(int(code))
+    except (TypeError, ValueError):
+        out["Max_Demand_Period"] = None
+    return out
+
+
+def ha_fallback(components_by_field: Optional[dict]) -> Callable[[str], Optional[PropertySpec]]:
+    """A `resolve()` fallback that derives a PropertySpec from an HA discovery component.
+
+    Used as the general-HA `fallback` for fields not in `EKM_MAP`: it infers a
+    `PropertySpec` from the field's HA `device_class` / `unit_of_measurement`.
+    """
+    components_by_field = components_by_field or {}
+
+    def _fallback(field_name: str) -> Optional[PropertySpec]:
+        comp = components_by_field.get(field_name)
+        if comp is None:
+            return None
+        return derive_spec(comp.device_class, comp.unit_of_measurement, comp.value_field or field_name)
+
+    return _fallback

ekm_proxy/sources/__init__.py

@@ -0,0 +1,45 @@
+"""Pluggable EKM data sources. Each yields normalized readMeter-style Readings.
+
+A Source is any object with a `stream()` generator yielding Reading. Variants
+(cloud MQTT, cloud/local readMeter API, RS-485, on-device) differ ONLY here;
+the core mapping + emitter are shared.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Iterator, Optional, Protocol
+
+
+@dataclass
+class Reading:
+    device_id: str  # EKM serial, e.g. "000300004127"
+    kind: str  # "meter" | "iostack"
+    fields: dict  # {ekm_field: value} current values (may be partial)
+    name: str | None = None  # human name if the source knows it
+    # Optional richer structure a source may supply (e.g. from HA discovery),
+    # used by the emitter to build a typed device and its info capability.
+    info: dict = field(default_factory=dict)  # eBus info props (vendor-name, model, ...)
+    schema_fields: Optional[list] = None  # declared field names; default = fields.keys()
+    components_by_field: Optional[dict] = None  # ekm_field -> HA component (fallback semantics)
+    available: Optional[bool] = None  # source-reported availability, drives $state
+
+
+class Source(Protocol):
+    def stream(self) -> Iterator[Reading]: ...
+
+
+def build_source(cfg: dict) -> "Source":
+    kind = cfg["source"]["kind"]
+    if kind == "cloud_mqtt":
+        from .cloud_mqtt import CloudMqttSource
+
+        return CloudMqttSource(cfg["source"]["cloud_mqtt"])
+    if kind in ("cloud_api", "local_api"):
+        from .cloud_api import ReadMeterSource  # same poller, different base_url
+
+        return ReadMeterSource(cfg["source"][kind])
+    if kind == "rs485":
+        from .rs485 import Rs485Source
+
+        return Rs485Source(cfg["source"]["rs485"])
+    raise ValueError(f"unknown source kind: {kind!r}")

ekm_proxy/sources/cloud_api.py

@@ -0,0 +1,40 @@
+"""readMeter API source (full 71-field). Serves both the cloud variant
+(base_url https://api.ekmpush.com) and the local variant (http://<push3-ip>).
+
+TODO: verify the exact serial field on each ReadSet element against a real
+captured response.
+"""
+
+from __future__ import annotations
+import os
+import time
+from typing import Iterator
+
+import requests
+
+from . import Reading
+
+
+class ReadMeterSource:
+    def __init__(self, cfg: dict):
+        self.base_url = os.path.expandvars(cfg["base_url"]).rstrip("/")
+        self.key = os.path.expandvars(cfg.get("key", "")) or os.environ.get("EKM_PUSH_KEY", "")
+        self.meters = cfg.get("meters", [])
+        self.poll = int(cfg.get("poll_seconds", 60))
+
+    def _read_once(self) -> Iterator[Reading]:
+        params = {"key": self.key, "format": "json", "cnt": 1}
+        if self.meters:
+            params["devices"] = ",".join(self.meters)
+        r = requests.get(f"{self.base_url}/readMeter", params=params, timeout=15)
+        r.raise_for_status()
+        data = r.json()
+        for rs in data.get("readMeter", {}).get("ReadSet", []):
+            serial = str(rs.get("Meter", rs.get("Meter_Address", ""))).zfill(12)
+            for rd in rs.get("ReadData", []):
+                yield Reading(serial, "meter", rd, rs.get("Meter_Name"))
+
+    def stream(self) -> Iterator[Reading]:
+        while True:
+            yield from self._read_once()
+            time.sleep(self.poll)

ekm_proxy/sources/cloud_mqtt.py

@@ -0,0 +1,145 @@
+"""MVP source: subscribe the EKM Push3 Home Assistant MQTT discovery stream.
+
+Topics:
+  homeassistant/device/<id>/config   (retained) -> device structure + metadata
+  ekmdata/<id>/state                 -> field values (curated subset)
+  ekmdata/<id>/availability          -> online/offline
+
+The device structure is parsed with the vendor-neutral `ha_discovery` parser;
+this source only adds the EKM-specific topic/id conventions and turns each
+parsed device into an enriched `Reading` (values + declared schema + component
+semantics + info metadata + availability) for the shared emitter.
+
+NB: state payloads carry only the fields the operator exposed as HA entities
+(a curated subset, not the full readMeter field set). Use the readMeter source
+when full fidelity is needed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+from typing import Iterator
+
+import paho.mqtt.client as mqtt
+
+from ebus_sdk.ha import HADevice, is_ebus_sdk_origin, parse_device_config
+
+from . import Reading
+
+
+def _kind_of(object_id: str) -> str:
+    return "iostack" if "iostack" in object_id else "meter"
+
+
+def _info_from_device(dev: HADevice) -> dict:
+    """eBus info-capability properties from the HA device block (skip placeholders)."""
+    info = {}
+    if dev.manufacturer:
+        info["vendor-name"] = dev.manufacturer
+    if dev.model and dev.model.lower() != "n/a":
+        info["model"] = dev.model
+    if dev.serial_number:
+        info["serial-number"] = dev.serial_number
+    if dev.sw_version and dev.sw_version.lower() != "n/a":
+        info["firmware-version"] = dev.sw_version
+    return info
+
+
+class _DeviceStructure:
+    """Cached, parsed structure for one discovered device."""
+
+    __slots__ = ("serial", "kind", "name", "info", "schema_fields", "components_by_field")
+
+    def __init__(self, dev: HADevice, object_id: str):
+        self.serial = dev.serial_number or dev.primary_id or object_id
+        self.kind = _kind_of(object_id)
+        self.name = dev.name
+        self.info = _info_from_device(dev)
+        self.schema_fields: list[str] = []
+        self.components_by_field: dict = {}
+        for comp in dev.components.values():
+            if comp.removed or not comp.value_field:
+                continue
+            self.schema_fields.append(comp.value_field)
+            self.components_by_field[comp.value_field] = comp
+
+
+class CloudMqttSource:
+    def __init__(self, cfg: dict):
+        self.host = os.path.expandvars(cfg.get("host", "localhost"))
+        self.port = int(cfg.get("port", 1883))
+        self.user = os.path.expandvars(cfg.get("username", "")) or None
+        self.password = os.environ.get("EKM_MQTT_PASS")
+        self.data_prefix = cfg.get("data_prefix", "ekmdata")
+        self._structs: dict[str, _DeviceStructure] = {}  # object_id -> structure
+        self._values: dict[str, dict] = {}  # object_id -> last state payload
+        self._avail: dict[str, bool] = {}  # object_id -> availability
+        self._q: "queue.Queue[Reading]" = queue.Queue()
+
+    def _on_connect(self, client, *_):
+        client.subscribe("homeassistant/device/+/config")
+        client.subscribe(f"{self.data_prefix}/+/state")
+        client.subscribe(f"{self.data_prefix}/+/availability")
+
+    def _reading_for(self, object_id: str) -> Reading | None:
+        struct = self._structs.get(object_id)
+        if struct is None:
+            return None  # values/availability seen before config; wait for structure
+        return Reading(
+            device_id=struct.serial,
+            kind=struct.kind,
+            fields=dict(self._values.get(object_id, {})),
+            name=struct.name,
+            info=struct.info,
+            schema_fields=struct.schema_fields,
+            components_by_field=struct.components_by_field,
+            available=self._avail.get(object_id),
+        )
+
+    def _emit(self, object_id: str) -> None:
+        reading = self._reading_for(object_id)
+        if reading is not None:
+            self._q.put(reading)
+
+    def _on_message(self, client, userdata, msg):
+        parts = msg.topic.split("/")
+        if msg.topic.startswith("homeassistant/device/") and parts[-1] == "config":
+            object_id = parts[2]
+            result = parse_device_config(msg.payload, object_id=object_id)
+            if isinstance(result, HADevice):
+                # Guard A: ignore discovery the eBus SDK itself published (a
+                # co-resident eBus->HA bridge's own output), so we never
+                # re-import our own echo back onto eBus.
+                if is_ebus_sdk_origin(result):
+                    return
+                self._structs[object_id] = _DeviceStructure(result, object_id)
+                self._emit(object_id)
+            return
+        if len(parts) >= 3 and parts[0] == self.data_prefix:
+            object_id = parts[1]
+            leaf = parts[-1]
+            if leaf == "state":
+                try:
+                    self._values[object_id] = json.loads(msg.payload.decode())
+                except (ValueError, UnicodeDecodeError):
+                    return
+                self._emit(object_id)
+            elif leaf == "availability":
+                self._avail[object_id] = msg.payload.decode().strip().lower() == "online"
+                self._emit(object_id)
+
+    def stream(self) -> Iterator[Reading]:
+        c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
+        if self.user:
+            c.username_pw_set(self.user, self.password)
+        c.on_connect = self._on_connect
+        c.on_message = self._on_message
+        c.connect(self.host, self.port, 60)
+        c.loop_start()
+        try:
+            while True:
+                yield self._q.get()
+        finally:
+            c.loop_stop()

ekm_proxy/sources/push3_native.py

@@ -0,0 +1,8 @@
+"""push3-native variant (PLACEHOLDER, no implementation here).
+
+Running the proxy ON the Push3 gateway is a distinct deployment whose runtime
+(OS, language, resources) depends on the Push3 platform and is TBD. It is very
+likely NOT this Python package. This file documents the variant and keeps it in
+the architecture. The reusable piece across all variants is `ekm_proxy.mapping`;
+only acquisition + eBus transport would be reimplemented for the device.
+"""

ekm_proxy/sources/rs485.py

@@ -0,0 +1,100 @@
+"""RS-485 source: read EKM Omnimeters directly over serial (no Push3).
+
+Wraps EKM's `ekmmeters` library. Because `ekmmeters`' field names are identical
+to the mapping table's keys, a read becomes the same `Reading` shape the other
+sources produce, carrying the meter's FULL field set (all phases, reactive
+power, per-line energy), and flows through the shared resolver + emitter with no
+translation.
+
+The serial/meter I/O lives in `stream()`; the read-buffer -> `Reading` transform
+is factored into `reading_from_fields()` so it can be unit-tested without
+hardware. `ekmmeters` is imported lazily so this module imports without it
+installed. To run the source, install `ekmmeters` (the local clone is
+recommended for Python 3): `pip install -e ../ekmmeters`.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Iterator, Optional
+
+from . import Reading
+
+logger = logging.getLogger(__name__)
+
+# EKM read fields describing the meter itself -> eBus info-capability properties.
+_INFO_FIELDS = {"Model": "model", "Firmware": "firmware-version"}
+_VENDOR_NAME = "EKM Metering Inc."
+
+
+def reading_from_fields(address: str, fields: dict) -> Reading:
+    """Turn a flat {ekm_field: value} read into a Reading. Pure, hardware-free.
+
+    Model/Firmware become info-capability properties and the meter address is the
+    serial. Every other field is passed through untouched: the shared resolver
+    maps the ones it knows and holds the rest, so unmapped/reserved fields (meter
+    time, CRC, status, and so on) are harmless.
+    """
+    address = str(address)
+    info = {"vendor-name": _VENDOR_NAME, "serial-number": address}
+    meter_fields = {}
+    for name, value in fields.items():
+        if value is None:
+            continue
+        if name in _INFO_FIELDS:
+            info[_INFO_FIELDS[name]] = str(value)
+        else:
+            meter_fields[name] = value
+    return Reading(device_id=address, kind="meter", fields=meter_fields, info=info, available=True)
+
+
+class Rs485Source:
+    def __init__(self, cfg: dict):
+        self.port = cfg.get("port", "/dev/ttyUSB0")
+        self.baud = int(cfg.get("baud", 9600))
+        self.poll_seconds = float(cfg.get("poll_seconds", 10))
+        # Each entry: {"address": "000300001463", "version": "v4"|"v3"}.
+        self.meters = cfg.get("meters", [])
+
+    def _build_meters(self):
+        from ekmmeters import SerialPort, V3Meter, V4Meter  # lazy: needs ekmmeters
+
+        port = SerialPort(self.port, self.baud)
+        if not port.initPort():
+            raise RuntimeError(f"rs485: could not open serial port {self.port!r}")
+        meters = []
+        for spec in self.meters:
+            address = spec["address"] if isinstance(spec, dict) else spec
+            version = (spec.get("version", "v4") if isinstance(spec, dict) else "v4").lower()
+            meter = V3Meter(address) if version == "v3" else V4Meter(address)
+            meter.attachPort(port)
+            meters.append((str(address), meter))
+        return port, meters
+
+    def _read(self, meter) -> Optional[dict]:
+        from ekmmeters import MeterData  # lazy
+
+        if not meter.request():
+            return None
+        buf = meter.getReadBuffer()
+        # Use the typed NativeValue, not getField()'s pre-formatted string.
+        return {name: buf[name][MeterData.NativeValue] for name in buf}
+
+    def stream(self) -> Iterator[Reading]:
+        port, meters = self._build_meters()
+        try:
+            while True:
+                for address, meter in meters:
+                    try:
+                        fields = self._read(meter)
+                    except Exception:
+                        logger.exception("rs485: read failed for meter %s", address)
+                        continue
+                    if fields:
+                        yield reading_from_fields(address, fields)
+                    else:
+                        logger.warning("rs485: no/invalid response from meter %s", address)
+                time.sleep(self.poll_seconds)
+        finally:
+            port.closePort()

ekm_proxy-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: ekm-proxy
+Version: 0.1.0
+Summary: Proxy EKM Metering devices onto the Electrification Bus (eBus / Homie 5)
+Author: Clark Communications Corporation
+License-Expression: MIT
+Keywords: ekm,omnimeter,iostack,metering,sub-metering,ebus,homie,proxy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ebus-sdk>=0.11.0
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: requests>=2.28
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: rs485
+Requires-Dist: pyserial>=3.5; extra == "rs485"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# ekm-proxy
+
+[![PyPI](https://img.shields.io/pypi/v/ekm-proxy.svg)](https://pypi.org/project/ekm-proxy/)
+[![Test](https://github.com/electrification-bus/ekm-proxy/actions/workflows/test.yml/badge.svg)](https://github.com/electrification-bus/ekm-proxy/actions/workflows/test.yml)
+[![Lint](https://github.com/electrification-bus/ekm-proxy/actions/workflows/lint.yml/badge.svg)](https://github.com/electrification-bus/ekm-proxy/actions/workflows/lint.yml)
+[![spec drift](https://github.com/electrification-bus/ekm-proxy/actions/workflows/spec-drift.yml/badge.svg)](https://github.com/electrification-bus/ekm-proxy/actions/workflows/spec-drift.yml)
+[![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)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+Publishes **EKM Metering** devices (Omnimeter meters, and ioStack IO/sensor modules) onto the **Electrification Bus (eBus)** as Homie 5 devices.
+
+It is an eBus **proxier** (see the eBus [`proxy.md`](https://github.com/electrification-bus/specification/blob/main/data-models/proxy.md) pattern): EKM meters do not speak eBus natively, so this service reads their data and republishes each discrete device onto eBus/Homie 5. It is not an "adapter" in the vague sense; it is a proxy with a specific, first-class role in the eBus model.
+
+> Status: **scaffold / MVP.** The cloud-MQTT source is the first target; other sources are stubbed with a common interface (see Variants).
+
+## What it emits
+
+- Each **Omnimeter** → one `energy.ebus.device.circuit` device bearing the eBus `meter` (and `demand`) capability plus `info`. Behind-the-meter sub-metering is modeled as a capability on a host circuit, not a standalone device type; per-conductor legs are `-a`/`-b`/`-c` property suffixes on the one device.
+- Each **ioStack** → an IO/sensor device. Its non-electrical sensors (e.g. 1-Wire temperature) are **deferred** pending the eBus `homie/5` domain-partitioning decision (spec issue SPEC-611) and are not emitted yet.
+- Device IDs follow the proxier convention `{proxier-id}-{proxied-id}` (the meter/ioStack serial is the proxied id).
+
+Full context, the field-mapping rationale, and the "why MVP-first is safe" spec-dependency analysis are maintained in the eBus specification project's design notes.
+
+## Architecture: shared core + pluggable sources
+
+All variants share the same **core** (EKM→eBus field mapping + Homie 5 emitter) and differ only in the **source** (how EKM data is acquired). Ports-and-adapters:
+
+```
+ source (acquire EKM data)  ->  core.mapping (EKM fields -> eBus props)  ->  core.emitter (Homie 5 -> eBus MQTT)
+```
+
+- `ekm_proxy/mapping.py` — the EKM-field → eBus-property mapping (source-agnostic).
+- `ekm_proxy/emitter.py` — Homie 5 device/description + value publisher to the eBus broker.
+- `ekm_proxy/sources/` — pluggable data sources; each yields normalized `readMeter`-style readings.
+
+## Variants (sources)
+
+Recall there will be several deployment variants of this proxy; they are all just different `sources/` behind the same core:
+
+| Source | Path | Cloud? | Status | Notes |
+|---|---|---|---|---|
+| **cloud-mqtt** (MVP) | `sources/cloud_mqtt.py` | yes | done (MVP) | Subscribe the EKM Push3 Home Assistant MQTT discovery stream (`homeassistant/device/+/config` + `ekmdata/+/state`). Curated field subset (only what the operator exposed as HA entities). |
+| **rs485** | `sources/rs485.py` | no | planned (full-detail path) | Talk RS-485 directly to Omnimeters (via EKM's `ekmmeters.py`). Full field detail, fully offline, and no Push3 required (just a low-cost USB-RS485 adapter). |
+| **cloud-api** | `sources/cloud_api.py` | yes | TBD if needed | Poll the EKM cloud `readMeter` API (full field set). See the note below on why this is deferred. |
+| **local-api** | `sources/local_api.py` | no | TBD if needed | Poll a Push3's onboard LAN `readMeter` API (`http://<push3-ip>/readMeter?...`), fully offline. Requires a Push3. See the note below. |
+| **push3-native** | (separate) | no | future | Run *on* the Push3 itself. Platform/language TBD; likely not this Python package. Placeholder documented in `sources/push3_native.py`. |
+
+`cloud-mqtt` and the `readMeter`-based sources (`cloud-api`, `local-api`) share this Python package. The two `readMeter` variants are **TBD if needed**: their advantages over `cloud-mqtt` are full field fidelity and offline (LAN) operation, but `rs485` already delivers both without a Push3 (just a low-cost USB-RS485 adapter), so it is the preferred path to full detail. The `readMeter` sources earn their place mainly where a Push3 is already deployed and you want to reuse its aggregation without wiring to the RS-485 bus. `push3-native` is a separate consideration because it depends on the Push3's on-device runtime.
+
+## eBus spec status
+
+This proxy composes existing eBus capabilities (`info` / `meter` / `demand`) under the `proxy.md` pattern. It emits `energy.ebus.device.circuit` bearing the `meter` capability, conforming to the eBus specification's capability-on-host model for behind-the-meter sub-metering (`data-models/circuit.md`, `capabilities/meter.md`). Instrument nameplate (`vendor-name` / `serial-number` / `model` / `firmware-version`) rides on the circuit's `info` per `capabilities/info.md` §"Nameplate versus conductor identity", with the EKM serial mirrored into `info/external-ids` as `ekm:<serial>`.
+
+## How to run
+
+Step-by-step for the MVP `cloud_mqtt` variant. Anyone with MQTT broker credentials can run it; no EKM hardware is required. It subscribes to the Home Assistant MQTT discovery stream an EKM Push3 publishes, translates each meter, and republishes it as an eBus (Homie 5) device.
+
+### 1. What you need
+
+- Python 3.10 or newer, with `pip` (a virtual environment is recommended).
+- The Mosquitto client tools (`mosquitto_sub` / `mosquitto_pub`) for watching the output. Optional, but handy for step 5.
+- Access to two MQTT brokers, which may be the **same** broker:
+  - a **source** broker carrying an EKM Push3's Home Assistant discovery topics (`homeassistant/device/+/config`, `ekmdata/+/state`, `ekmdata/+/availability`). This is any broker an EKM Push3 publishes to (your own Push3, or a shared/demo broker). You supply the MQTT credentials.
+  - a **target** eBus broker to publish the translated Homie 5 devices to. Can be the same broker, or a separate/local one. To stand up a local eBus broker on your own machine, see [broker-quickstart](https://github.com/electrification-bus/broker-quickstart).
+
+### 2. Install
+
+ekm-proxy is published on [PyPI](https://pypi.org/project/ekm-proxy/), so the quickest install is:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install ekm-proxy
+```
+
+That installs the `ekm-proxy` command plus its dependencies: the eBus library `ebus-sdk` and `paho-mqtt`. For the RS-485 source, install the extra with `pip install "ekm-proxy[rs485]"`.
+
+To hack on the proxy itself, install from a source checkout instead:
+
+```bash
+git clone https://github.com/electrification-bus/ekm-proxy.git
+cd ekm-proxy
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+If your Python package index does not carry `ebus-sdk`, install it from the `electrification-bus` GitHub organization.
+
+### 3. Configure
+
+```bash
+cp config/config.example.toml config/config.toml
+```
+
+Edit `config/config.toml`. The two sections you set are the **source** (`[source.cloud_mqtt]`, the broker with the EKM discovery stream) and the **target** (`[ebus]`, where translated devices are published):
+
+```toml
+[source]
+kind = "cloud_mqtt"
+
+[source.cloud_mqtt]
+host = "${EKM_MQTT_HOST}"       # broker carrying the Push3 HA discovery stream
+port = 1883
+username = "${EKM_MQTT_USER}"   # password comes from EKM_MQTT_PASS
+
+[ebus]
+host = "${EBUS_MQTT_HOST}"      # where translated eBus devices are published
+port = 1883
+username = "${EBUS_MQTT_USER}"  # password comes from EBUS_MQTT_PASS
+proxier_id = "ekm-proxy-1"      # your bridge id; devices are {proxier-id}-{serial}
+vendor_name = "ekm-proxy"
+name = "EKM Proxy"
+```
+
+Provide the credentials via environment variables (never commit secrets):
+
+```bash
+# source broker (the EKM Push3 / demo broker):
+export EKM_MQTT_HOST=<source-broker-host>
+export EKM_MQTT_USER=<source-username>
+export EKM_MQTT_PASS=<source-password>
+
+# target eBus broker (may be the same host):
+export EBUS_MQTT_HOST=<target-broker-host>
+export EBUS_MQTT_USER=<target-username>
+export EBUS_MQTT_PASS=<target-password>
+```
+
+To publish back to the same broker you read from (the simplest setup), point the `EBUS_MQTT_*` values at the same host and credentials as the `EKM_MQTT_*` ones.
+
+### 4. Run
+
+```bash
+ekm-proxy --config config/config.toml
+```
+
+It connects, discovers each EKM meter from the retained HA discovery messages, and publishes one eBus device per meter. Leave it running; it updates property values as new readings arrive.
+
+### 5. Verify
+
+Watch the eBus tree on the **target** broker:
+
+```bash
+mosquitto_sub -h <target-broker-host> -p 1883 -u <user> -P <pass> -t 'ebus/5/#' -v
+```
+
+You should see:
+
+- `ebus/5/<proxier-id>/...` : the bridge (`energy.ebus.device.bridge`) root device.
+- `ebus/5/<proxier-id>-<serial>/...` : one circuit (`energy.ebus.device.circuit`) per EKM meter, each with a typed `$description`, a `$state`, an `info` capability (nameplate: vendor, serial, plus `external-ids = ekm:<serial>`), and a `meter` capability (`imported-energy`, `active-power`, `current-a`, ...) in eBus-canonical units (energy in Wh, power in W, current in A).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues, propose changes, and the lint/test expectations (`ruff` + `pytest`).
+
+## Releasing
+
+Published to [PyPI](https://pypi.org/project/ekm-proxy/) via Trusted Publishing (GitHub Actions OIDC, no stored token): the [`publish.yml`](.github/workflows/publish.yml) workflow builds and uploads on any `v*` tag. To cut a release:
+
+1. Bump the version in **both** `pyproject.toml` (`[project].version`) and `src/ekm_proxy/__init__.py` (`__version__`); the `setup.py` shim reads the latter for the Yocto/kirkstone build path, so they must agree. Update the `CHANGELOG.md` `[Unreleased]` section.
+2. Commit, then tag and push:
+   ```bash
+   git tag v0.1.0 && git push origin v0.1.0
+   ```
+3. The workflow runs the tests, builds the sdist + wheel, and publishes. Confirm the new version on PyPI and that the badge updates.
+
+The `setup.py` shim exists so the older setuptools pinned in Yocto kirkstone builds a correct wheel (all modules plus the `ekm-proxy` entry point) from the sdist; the modern build path uses the PEP 621 metadata in `pyproject.toml`.
+
+## License
+
+[MIT](LICENSE) (c) 2026 Clark Communications Corporation.
+
+## References (EKM public docs)
+
+- EKM Push Open API / MQTT / RS-485: <https://documents.ekmmetering.com/api-docs/>
+- Push3 LAN UI + local `readMeter` API: <https://help.ekmmetering.com/support/solutions/articles/6000236439>
+- Omnimeter Pulse v.4, ioStack, Push3: <https://www.ekmmetering.com/>
+
+Captured copies of these docs and live data captures are kept private (EKM's docs are copyrighted and are not redistributed here).

ekm_proxy-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ekm_proxy/__init__.py,sha256=lfafLKNpHVQrM4qEm08h8IM4nougKwJqJudrFLbs83Y,109
+ekm_proxy/cli.py,sha256=MVtIBSZRw4W816XhiG3zf1euDOfy3RX3OlHk2W-hADk,1187
+ekm_proxy/config.py,sha256=37LK7B_1kuG4IzqirhhELIzpHyl7rm6iwzzafo6rBsk,257
+ekm_proxy/emitter.py,sha256=O3vpxoS_wtO6B57h1Sc-6-bTepOtU2bf-nkR5jZuoww,8452
+ekm_proxy/mapping.py,sha256=X1teLkvq5kQbu4lXhhdaW9BMPSubenCB603blfUIiqg,6130
+ekm_proxy/sources/__init__.py,sha256=9IOR4-UR_ASU49fgcU24lqKJqyDySDzYiguCoNX_JwM,1808
+ekm_proxy/sources/cloud_api.py,sha256=tPJ1mA9u9jHqCjGqToKhLKace80lvnGQCpldEOXmGpA,1426
+ekm_proxy/sources/cloud_mqtt.py,sha256=V5i_XQLMRPNfGDWBzGA4C2EW46CNTUIDfWSjq75n_0Y,5720
+ekm_proxy/sources/push3_native.py,sha256=fcT_yvPtbRix31sji8-8GvRMoCkr_Kkin5H4hjLiQCk,459
+ekm_proxy/sources/rs485.py,sha256=jhEGSA0T0T7CHhsBXTRWgma04hjXAQVSJa5cHIzA58A,4065
+ekm_proxy-0.1.0.dist-info/licenses/LICENSE,sha256=SNfEtQtKuaLySMOhEdErGT_hoKN-6L0BJlPJpUXZoDI,1089
+ekm_proxy-0.1.0.dist-info/METADATA,sha256=ewab5ZDBvH5-_DacD3vPotmCVW0g15fzm1YgvYa6vSI,11921
+ekm_proxy-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ekm_proxy-0.1.0.dist-info/entry_points.txt,sha256=N1cNtCsIdVT3ogsVXERvX5x0FOuYkWuDKXw8QwPgs4M,49
+ekm_proxy-0.1.0.dist-info/top_level.txt,sha256=L6ojEG5sf1BnjUlQpXpv7YzEdAQ7GRnNUqdBB072FuQ,10
+ekm_proxy-0.1.0.dist-info/RECORD,,

ekm_proxy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ekm_proxy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ekm-proxy = ekm_proxy.cli:main

ekm_proxy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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.

ekm_proxy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ekm_proxy