zendure 0.1.0__py3-none-any.whl

zendure/__init__.py

@@ -0,0 +1,78 @@
+"""Async local-network client for Zendure energy devices.
+
+Talks to a device on the LAN over the zenSDK HTTP protocol (``GET
+/properties/report`` + ``POST /properties/write``). No cloud, no MQTT, no app
+token. This package never imports ``homeassistant``: a thin Home Assistant
+integration consumes it in a later phase.
+
+Public surface is re-exported here; everything else is an implementation detail.
+"""
+
+from .client import ZendureClient
+from .events import (
+    BatteryAdded,
+    BatteryPropertiesChanged,
+    BatteryRemoved,
+    DeviceAvailabilityChanged,
+    DevicePropertiesChanged,
+    EventListener,
+    ProtocolWarning,
+    ZendureEvent,
+)
+from .exceptions import (
+    ClientClosedError,
+    DeviceMismatchError,
+    MalformedResponseError,
+    UnsupportedDeviceError,
+    UnsupportedPropertyError,
+    ValidationError,
+    WriteNotConfirmedError,
+    WriteRejectedError,
+    ZendureConnectionError,
+    ZendureError,
+    ZendureProtocolError,
+)
+from .local import create_local_client
+from .models import (
+    Availability,
+    BatterySnapshot,
+    ControlDescription,
+    DeviceSnapshot,
+    EntityKind,
+    PropertyValue,
+    SensorDescription,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Availability",
+    "BatteryAdded",
+    "BatteryPropertiesChanged",
+    "BatteryRemoved",
+    "BatterySnapshot",
+    "ClientClosedError",
+    "ControlDescription",
+    "DeviceAvailabilityChanged",
+    "DeviceMismatchError",
+    "DevicePropertiesChanged",
+    "DeviceSnapshot",
+    "EntityKind",
+    "EventListener",
+    "MalformedResponseError",
+    "PropertyValue",
+    "ProtocolWarning",
+    "SensorDescription",
+    "UnsupportedDeviceError",
+    "UnsupportedPropertyError",
+    "ValidationError",
+    "WriteNotConfirmedError",
+    "WriteRejectedError",
+    "ZendureClient",
+    "ZendureConnectionError",
+    "ZendureError",
+    "ZendureEvent",
+    "ZendureProtocolError",
+    "__version__",
+    "create_local_client",
+]

zendure/_redact.py

@@ -0,0 +1,14 @@
+"""Helpers that keep sensitive identifiers out of logs and error messages."""
+
+
+def mask_serial(serial_number: str) -> str:
+    """Keep a 4-character prefix for correlation and hide the rest.
+
+    ``HEC4ADP5P210250`` -> ``HEC4***``.
+    """
+    if len(serial_number) <= 4:
+        return "***"
+    return f"{serial_number[:4]}***"
+
+
+__all__ = ["mask_serial"]

zendure/catalog/__init__.py

@@ -0,0 +1,28 @@
+"""Static capability definitions: protocol-agnostic, no runtime state.
+
+Everything here is declared data (device models, property descriptions, battery
+rules) plus the pure functions that look it up. These tables replace the
+inheritance tree and runtime entity-building of the old integration.
+"""
+
+from .controls import CONTROL_DESCRIPTIONS, control, validate_control
+from .devices import DeviceCapability, lookup_device, normalize_product
+from .sensors import (
+    BATTERY_SENSOR_DESCRIPTIONS,
+    DEVICE_SENSOR_DESCRIPTIONS,
+    battery_sensor,
+    device_sensor,
+)
+
+__all__ = [
+    "BATTERY_SENSOR_DESCRIPTIONS",
+    "CONTROL_DESCRIPTIONS",
+    "DEVICE_SENSOR_DESCRIPTIONS",
+    "DeviceCapability",
+    "battery_sensor",
+    "control",
+    "device_sensor",
+    "lookup_device",
+    "normalize_product",
+    "validate_control",
+]

zendure/catalog/controls.py

@@ -0,0 +1,171 @@
+"""Writable property (control) descriptions and pre-write validation.
+
+Static declaration of the 9 Max 5000 Pro controls plus the pure validation that
+guards every write BEFORE anything leaves the library. An out-of-range, bad-enum
+or read-only write raises ``ValidationError`` and nothing is sent; the library
+never silently clamps (unlike the old integration).
+
+Raw<->user encoding (e.g. ``socSet`` x10) is a protocol detail handled on the
+write path, not here. This table holds user-facing ranges and enum options.
+"""
+
+from collections.abc import Mapping
+
+from ..exceptions import UnsupportedPropertyError, ValidationError
+from ..models import ControlDescription, EntityKind, PropertyValue
+
+_STEP_TOLERANCE = 1e-9
+
+_CONTROLS: tuple[ControlDescription, ...] = (
+    ControlDescription(
+        key="acMode",
+        kind=EntityKind.SELECT,
+        options={1: "input", 2: "output"},
+    ),
+    ControlDescription(
+        key="gridOffMode",
+        kind=EntityKind.SELECT,
+        options={0: "normal", 1: "eco", 2: "off"},
+    ),
+    ControlDescription(
+        key="gridReverse",
+        kind=EntityKind.SELECT,
+        # 1=allow / 2=forbidden from the old integration; 0's meaning is a
+        # candidate pending firmware confirmation.
+        options={0: "disabled", 1: "allow", 2: "forbidden"},
+    ),
+    ControlDescription(
+        key="inputLimit",
+        kind=EntityKind.NUMBER,
+        unit="W",
+        native_min=0,
+        max_source_key="chargeMaxLimit",
+    ),
+    ControlDescription(
+        key="outputLimit",
+        kind=EntityKind.NUMBER,
+        unit="W",
+        native_min=0,
+        max_source_key="inverseMaxPower",
+    ),
+    # Regulatory output limit: read-only until firmware confirms it is safe and
+    # legal to write locally (it tracks gridStandard / regional caps).
+    ControlDescription(
+        key="inverseMaxPower",
+        kind=EntityKind.NUMBER,
+        unit="W",
+        writable=False,
+    ),
+    # zenSDK docs mark lampSwitch read-only, but the product's control list
+    # exposes Light as a switch; writability is a candidate pending firmware.
+    ControlDescription(key="lampSwitch", kind=EntityKind.SWITCH),
+    ControlDescription(
+        key="socSet",
+        kind=EntityKind.NUMBER,
+        unit="%",
+        native_min=70,
+        native_max=100,
+        step=1,
+    ),
+    # NOT a "smart strategy": smartMode=1 means params are not written to flash
+    # and revert after a device restart. Exposed verbatim.
+    ControlDescription(key="smartMode", kind=EntityKind.SWITCH),
+)
+
+CONTROL_DESCRIPTIONS: Mapping[str, ControlDescription] = {c.key: c for c in _CONTROLS}
+
+
+def control(key: str) -> ControlDescription | None:
+    """Return the control description for ``key``, or ``None``."""
+    return CONTROL_DESCRIPTIONS.get(key)
+
+
+def validate_control(
+    key: str,
+    value: PropertyValue,
+    *,
+    dynamic_max: float | None = None,
+) -> int | float:
+    """Validate a user-facing control value and return it normalized.
+
+    ``dynamic_max`` is the device's current reported upper bound (e.g.
+    ``inverseMaxPower``); it only applies to controls that declare a
+    ``max_source_key``.
+
+    Raises:
+        UnsupportedPropertyError: ``key`` is not a known control.
+        ValidationError: the control is read-only, or the value is out of
+            range / off-step / not a valid option.
+    """
+    description = CONTROL_DESCRIPTIONS.get(key)
+    if description is None:
+        raise UnsupportedPropertyError(key)
+    if not description.writable:
+        raise ValidationError(f"{key} is read-only")
+    if value is None:
+        raise ValidationError(f"{key} value must not be None")
+
+    if description.kind is EntityKind.SELECT:
+        return _validate_select(description, value)
+    if description.kind is EntityKind.SWITCH:
+        return _validate_switch(key, value)
+    if description.kind is EntityKind.NUMBER:
+        return _validate_number(description, value, dynamic_max)
+    raise ValidationError(f"{key} is not a writable control kind")
+
+
+def _validate_select(description: ControlDescription, value: PropertyValue) -> int:
+    options = description.options
+    if options is None:
+        raise ValidationError(f"{description.key} has no options")
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValidationError(f"{description.key} expects an integer option")
+    if value not in options:
+        raise ValidationError(
+            f"{description.key}={value} not in options {sorted(options)}"
+        )
+    return value
+
+
+def _validate_switch(key: str, value: PropertyValue) -> int:
+    if isinstance(value, bool):
+        return int(value)
+    if value in (0, 1):
+        return int(value)
+    raise ValidationError(f"{key} expects 0, 1 or a bool")
+
+
+def _validate_number(
+    description: ControlDescription,
+    value: PropertyValue,
+    dynamic_max: float | None,
+) -> int | float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValidationError(f"{description.key} expects a number")
+
+    low = description.native_min
+    if description.max_source_key is not None and dynamic_max is not None:
+        high: float | None = dynamic_max
+    else:
+        high = description.native_max
+
+    if low is not None and value < low:
+        raise ValidationError(f"{description.key}={value} below minimum {low}")
+    if high is not None and value > high:
+        raise ValidationError(f"{description.key}={value} above maximum {high}")
+
+    if description.step is not None:
+        base = description.native_min if description.native_min is not None else 0
+        steps = (value - base) / description.step
+        if abs(steps - round(steps)) > _STEP_TOLERANCE:
+            raise ValidationError(
+                f"{description.key}={value} not aligned to step {description.step}"
+            )
+    return value
+
+
+__all__ = [
+    "CONTROL_DESCRIPTIONS",
+    "control",
+    "validate_control",
+]

zendure/catalog/devices.py

@@ -0,0 +1,76 @@
+"""Device model capability table.
+
+A device's reported ``product`` string is normalized (lower-cased, whitespace
+removed) and looked up here, replacing the old per-model inheritance tree. An
+unregistered product raises ``UnsupportedDeviceError`` rather than guessing.
+
+Only ``max_5000_pro`` and ``solarflow_2400ac_plus`` are registered. They share
+the same property set. Power limits are deliberately NOT stored here: the
+device reports its own dynamic limits (``inverseMaxPower``, ``chargeMaxLimit``),
+which always win over any static value. Other models are added as they are
+verified on real hardware.
+"""
+
+from dataclasses import dataclass
+
+
+def normalize_product(product: str) -> str:
+    """Normalize a reported product string for case/whitespace-insensitive match.
+
+    ``"+"`` is significant (e.g. ``solarFlow2400AC+``) and is kept.
+    """
+    return "".join(product.split()).lower()
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceCapability:
+    """What the library knows about one device model, independent of protocol."""
+
+    model_key: str
+    display_name: str
+    solar_channels: int
+    aliases: tuple[str, ...]
+
+
+# Keyed by model_key. `aliases` hold already-normalized product strings.
+_CAPABILITIES: tuple[DeviceCapability, ...] = (
+    DeviceCapability(
+        model_key="max_5000_pro",
+        display_name="SolarFlow Max 5000 Pro",
+        # 4 PV inputs per the Max 5000 Pro feature list (candidate until a real
+        # Max 5000 Pro report is seen; its property set matches 2400 AC+).
+        solar_channels=4,
+        aliases=("solarflowmax5000pro",),
+    ),
+    DeviceCapability(
+        model_key="solarflow_2400ac_plus",
+        display_name="SolarFlow 2400 AC+",
+        solar_channels=4,
+        aliases=("solarflow2400ac+",),
+    ),
+)
+
+_BY_ALIAS: dict[str, DeviceCapability] = {
+    alias: cap for cap in _CAPABILITIES for alias in cap.aliases
+}
+
+
+def lookup_device(product: str) -> DeviceCapability:
+    """Resolve a reported product string to its capability, or reject it.
+
+    Raises:
+        UnsupportedDeviceError: the product is not a registered model.
+    """
+    from ..exceptions import UnsupportedDeviceError
+
+    capability = _BY_ALIAS.get(normalize_product(product))
+    if capability is None:
+        raise UnsupportedDeviceError(product)
+    return capability
+
+
+__all__ = [
+    "DeviceCapability",
+    "lookup_device",
+    "normalize_product",
+]

zendure/catalog/sensors.py

@@ -0,0 +1,130 @@
+"""Read-only property descriptions (protocol-agnostic).
+
+Static declaration of every sensor the library exposes for the Max 5000 Pro:
+its entity kind, unit, and HA-style classes. Raw-to-value decoding is NOT here
+(it is a protocol detail in ``protocols/local_http/codec.py``); this table only
+says what each entity *is*.
+
+Keys use the vendor's original casing (``electricLevel``, ``packNum``) on
+purpose. A reported key that is absent here is not turned into an entity.
+"""
+
+from collections.abc import Mapping
+
+from ..models import EntityKind, SensorDescription
+
+
+def _power(key: str) -> SensorDescription:
+    return SensorDescription(
+        key=key, unit="W", device_class="power", state_class="measurement"
+    )
+
+
+def _voltage(key: str) -> SensorDescription:
+    return SensorDescription(
+        key=key,
+        unit="V",
+        device_class="voltage",
+        state_class="measurement",
+        precision=2,
+    )
+
+
+def _temperature(key: str) -> SensorDescription:
+    return SensorDescription(
+        key=key,
+        unit="°C",
+        device_class="temperature",
+        state_class="measurement",
+        precision=1,
+    )
+
+
+def _binary(key: str, device_class: str | None = None) -> SensorDescription:
+    return SensorDescription(
+        key=key, kind=EntityKind.BINARY_SENSOR, device_class=device_class
+    )
+
+
+def _enum(key: str) -> SensorDescription:
+    # Integer state code; the meaning table is validated on real hardware.
+    return SensorDescription(key=key)
+
+
+def _index(
+    descriptions: tuple[SensorDescription, ...],
+) -> Mapping[str, SensorDescription]:
+    return {d.key: d for d in descriptions}
+
+
+# --- Device-level sensors (from the Max 5000 Pro feature list) ---------------
+_DEVICE: tuple[SensorDescription, ...] = (
+    SensorDescription(
+        key="electricLevel", unit="%", device_class="battery", state_class="measurement"
+    ),
+    _power("gridInputPower"),  # On-grid input (charge from grid)
+    _power("gridOffPower"),  # Off-grid outlet: + output / - input (sign candidate)
+    _power("outputHomePower"),  # On-grid output
+    _power("outputPackPower"),  # Battery charge power
+    _power("packInputPower"),  # Battery discharge power
+    _power("solarInputPower"),  # Total PV input
+    _power("solarPower1"),
+    _power("solarPower2"),
+    _power("solarPower3"),
+    _power("solarPower4"),
+    _temperature("hyperTmp"),  # Enclosure temperature
+    SensorDescription(key="packNum", state_class="measurement"),  # pack count
+    _enum("packState"),  # 0..2 (candidate)
+    SensorDescription(
+        key="remainOutTime",
+        unit="min",
+        device_class="duration",
+        state_class="measurement",
+    ),
+    _binary("heatState", device_class="heat"),
+    _binary("pass"),  # bypass state
+    _binary("reverseState"),  # reverse-flow state
+    _binary("socStatus"),  # SOC calibration state
+)
+
+# --- Per-battery sensors -----------------------------------------------------
+_BATTERY: tuple[SensorDescription, ...] = (
+    SensorDescription(
+        key="socLevel", unit="%", device_class="battery", state_class="measurement"
+    ),
+    _power("power"),  # + charge / - discharge (sign candidate)
+    _temperature("maxTemp"),
+    _voltage("totalVol"),
+    _voltage("maxVol"),
+    _voltage("minVol"),
+    SensorDescription(
+        key="batcur",
+        unit="A",
+        device_class="current",
+        state_class="measurement",
+        precision=1,
+    ),
+    _enum("state"),  # 0 standby / 1 charging / 2 discharging (candidate)
+    SensorDescription(key="softVersion"),  # decoded to a version string
+)
+
+DEVICE_SENSOR_DESCRIPTIONS: Mapping[str, SensorDescription] = _index(_DEVICE)
+BATTERY_SENSOR_DESCRIPTIONS: Mapping[str, SensorDescription] = _index(_BATTERY)
+
+
+def device_sensor(key: str) -> SensorDescription | None:
+    """Return the device-level sensor description for ``key``, or ``None``."""
+    return DEVICE_SENSOR_DESCRIPTIONS.get(key)
+
+
+def battery_sensor(key: str) -> SensorDescription | None:
+    """Return the per-battery sensor description for ``key``, or ``None``."""
+    return BATTERY_SENSOR_DESCRIPTIONS.get(key)
+
+
+__all__ = [
+    "BATTERY_SENSOR_DESCRIPTIONS",
+    "DEVICE_SENSOR_DESCRIPTIONS",
+    "battery_sensor",
+    "device_sensor",
+]

zendure/client.py

@@ -0,0 +1,195 @@
+"""``ZendureClient``: the public facade (read path).
+
+Depends only on the abstract ``DeviceProtocol``, never on a concrete protocol.
+Every read goes through ``async_refresh`` (whether triggered by the built-in
+poller or by the caller, e.g. a Home Assistant coordinator), so failure
+counting and availability are consistent no matter who drives refreshes.
+"""
+
+import asyncio
+import logging
+from collections.abc import Callable
+from typing import Final, Self
+
+from .catalog.controls import control, validate_control
+from .events import EventListener, ZendureEvent
+from .exceptions import (
+    ClientClosedError,
+    ValidationError,
+    WriteNotConfirmedError,
+    ZendureConnectionError,
+    ZendureProtocolError,
+)
+from .models import Availability, DeviceSnapshot, PropertyValue
+from .protocols.base import DeviceProtocol
+from .state.store import DEFAULT_OFFLINE_THRESHOLD, DeviceStore
+from .transport.poller import DEFAULT_MAX_BACKOFF, DEFAULT_SCAN_INTERVAL, Poller
+
+_LOGGER = logging.getLogger(__name__)
+
+# Device reports can lag a successful write. Retry the confirmation GET only;
+# the write itself is never retried.
+_CONFIRM_ATTEMPTS: Final = 7
+_CONFIRM_DELAY_S: Final = 1.0
+
+
+class ZendureClient:
+    """One device, one client. Async context manager; ``close()`` is idempotent."""
+
+    def __init__(
+        self,
+        protocol: DeviceProtocol,
+        *,
+        offline_threshold: int = DEFAULT_OFFLINE_THRESHOLD,
+        expected_serial_number: str | None = None,
+        scan_interval: float = DEFAULT_SCAN_INTERVAL,
+        max_backoff: float = DEFAULT_MAX_BACKOFF,
+    ) -> None:
+        self._protocol = protocol
+        self._store = DeviceStore(
+            offline_threshold=offline_threshold,
+            expected_serial_number=expected_serial_number,
+        )
+        self._poller = Poller(
+            self.async_refresh,
+            interval=scan_interval,
+            max_interval=max_backoff,
+            backoff_after=offline_threshold,
+        )
+        self._listeners: list[EventListener] = []
+        self._inflight: asyncio.Task[DeviceSnapshot] | None = None
+        self._closed = False
+        self._write_lock = asyncio.Lock()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+    @property
+    def snapshot(self) -> DeviceSnapshot | None:
+        """Latest snapshot, or ``None`` before the first successful read."""
+        return self._store.snapshot() if self._store.has_identity else None
+
+    @property
+    def availability(self) -> Availability:
+        """Current availability."""
+        return self._store.availability
+
+    def subscribe(self, listener: EventListener) -> Callable[[], None]:
+        """Register a change listener; returns a function that unsubscribes it."""
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    async def async_refresh(self) -> DeviceSnapshot:
+        """Read the device once and merge the result.
+
+        Concurrent callers share one in-flight request, so a burst of refreshes
+        sends one GET and counts at most one failure.
+
+        Raises:
+            ClientClosedError: called after ``close()``.
+            ZendureConnectionError / ZendureProtocolError: the read failed
+                (counted toward the offline threshold).
+            UnsupportedDeviceError: the model is not supported (not counted).
+        """
+        if self._closed:
+            raise ClientClosedError("client is closed")
+        # Join only a request that is still running; a finished one (whose
+        # done-callback has not run yet) must not hand out a stale result.
+        if self._inflight is None or self._inflight.done():
+            self._inflight = asyncio.create_task(self._refresh_once())
+            self._inflight.add_done_callback(self._clear_inflight)
+        return await asyncio.shield(self._inflight)
+
+    def _clear_inflight(self, task: asyncio.Task[DeviceSnapshot]) -> None:
+        if self._inflight is task:
+            self._inflight = None
+        if not task.cancelled():
+            task.exception()  # Mark as retrieved; the awaiting caller re-raises.
+
+    async def _refresh_once(self) -> DeviceSnapshot:
+        try:
+            report = await self._protocol.async_read()
+            snapshot, events = self._store.merge(report)
+        except (ZendureConnectionError, ZendureProtocolError) as err:
+            self._dispatch(self._store.record_failure(err))
+            raise
+        self._dispatch(events)
+        return snapshot
+
+    async def async_set(self, key: str, value: PropertyValue) -> DeviceSnapshot:
+        """Validate, write once, then confirm against a fresh device report.
+
+        A timeout is outcome-unknown and never retried. An accepted write whose
+        value is not yet reported raises WriteNotConfirmedError, not rejection.
+        """
+        async with self._write_lock:
+            if self._closed:
+                raise ClientClosedError("client is closed")
+            description = control(key)
+            # Reject unknown/read-only/type errors before requesting identity.
+            if description is None or not description.writable:
+                validate_control(key, value)
+            snapshot = await self.async_refresh()
+            dynamic_max = None
+            if description is not None and description.max_source_key is not None:
+                bound = snapshot.properties.get(description.max_source_key)
+                if isinstance(bound, bool) or not isinstance(bound, (int, float)):
+                    raise ValidationError(f"{key} upper bound is unavailable")
+                dynamic_max = float(bound)
+            normalized = validate_control(key, value, dynamic_max=dynamic_max)
+            await self._protocol.async_write(snapshot.serial_number, {key: normalized})
+            if self._inflight is not None and not self._inflight.done():
+                await asyncio.shield(self._inflight)
+            confirmed = await self._confirm_write(key, normalized)
+            if confirmed.properties.get(key) != normalized:
+                raise WriteNotConfirmedError(f"{key} write not confirmed by read-back")
+            return confirmed
+
+    async def _confirm_write(self, key: str, expected: PropertyValue) -> DeviceSnapshot:
+        """Re-read until the device reports ``expected``, or attempts are exhausted."""
+        snapshot = await self.async_refresh()
+        for _ in range(_CONFIRM_ATTEMPTS - 1):
+            if snapshot.properties.get(key) == expected:
+                return snapshot
+            await asyncio.sleep(_CONFIRM_DELAY_S)
+            snapshot = await self.async_refresh()
+        return snapshot
+
+    def start(self) -> None:
+        """Start the built-in poller (standalone use; HA drives refreshes itself)."""
+        if self._closed:
+            raise ClientClosedError("client is closed")
+        self._poller.start()
+
+    async def close(self) -> None:
+        """Stop polling and cancel any in-flight read. Does not close the session."""
+        if self._closed:
+            return
+        self._closed = True
+        await self._poller.stop()
+        if (task := self._inflight) is not None:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        self._listeners.clear()
+
+    def _dispatch(self, events: list[ZendureEvent]) -> None:
+        if self._closed:
+            return
+        for event in events:
+            for listener in tuple(self._listeners):
+                try:
+                    listener(event)
+                except Exception:
+                    # One faulty listener must not stop delivery to the others.
+                    _LOGGER.exception("Listener failed on %s", type(event).__name__)
+
+
+__all__ = ["ZendureClient"]