zendure 0.3.0__py3-none-any.whl

zendure/__init__.py

@@ -0,0 +1,90 @@
+"""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,
+    FaultCleared,
+    FaultRaised,
+    ProtocolWarning,
+    ZendureEvent,
+)
+from .exceptions import (
+    ClientClosedError,
+    DeviceMismatchError,
+    MalformedResponseError,
+    ProvisioningError,
+    ProvisioningFailedError,
+    ProvisioningTimeoutError,
+    UnsupportedDeviceError,
+    UnsupportedFeatureError,
+    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.3.0"
+
+__all__ = [
+    "Availability",
+    "BatteryAdded",
+    "BatteryPropertiesChanged",
+    "BatteryRemoved",
+    "BatterySnapshot",
+    "ClientClosedError",
+    "ControlDescription",
+    "DeviceAvailabilityChanged",
+    "DeviceMismatchError",
+    "DevicePropertiesChanged",
+    "DeviceSnapshot",
+    "EntityKind",
+    "EventListener",
+    "FaultCleared",
+    "FaultRaised",
+    "MalformedResponseError",
+    "PropertyValue",
+    "ProtocolWarning",
+    "ProvisioningError",
+    "ProvisioningFailedError",
+    "ProvisioningTimeoutError",
+    "SensorDescription",
+    "UnsupportedDeviceError",
+    "UnsupportedFeatureError",
+    "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.
+
+    ``TESTDEV00000001`` -> ``TEST***``.
+    """
+    if len(serial_number) <= 4:
+        return "***"
+    return f"{serial_number[:4]}***"
+
+
+__all__ = ["mask_serial"]

zendure/ble/__init__.py

@@ -0,0 +1,25 @@
+"""BLE Wi-Fi provisioning for Zendure devices (local, no cloud token).
+
+Kept apart from the HTTP client so that only callers that provision devices
+need ``bleak``.
+"""
+
+from .advertisement import parse_serial_number
+from .const import (
+    COMMAND_CHAR_UUID,
+    LOCAL_NAME_PREFIX,
+    NOTIFY_CHAR_UUID,
+    PROVISIONING_SERVICE_UUID,
+)
+from .provision import ProvisionResult, async_provision_wifi, build_provision_request
+
+__all__ = [
+    "COMMAND_CHAR_UUID",
+    "LOCAL_NAME_PREFIX",
+    "NOTIFY_CHAR_UUID",
+    "PROVISIONING_SERVICE_UUID",
+    "ProvisionResult",
+    "async_provision_wifi",
+    "build_provision_request",
+    "parse_serial_number",
+]

zendure/ble/advertisement.py

@@ -0,0 +1,37 @@
+"""Identify a Zendure device from its BLE advertisement.
+
+The advertised local name (``Zen<x>_<n>``) is too short to identify a device,
+so the serial number is read from manufacturer data instead: the 16-bit
+company id (little endian) holds the first two serial characters and the
+payload holds the remaining 13, followed by one trailing status byte.
+"""
+
+from collections.abc import Mapping
+from typing import Final
+
+from .const import SERIAL_NUMBER_LENGTH
+
+# 2 company-id bytes + 13 serial bytes + 1 trailing byte.
+_RAW_LENGTH: Final = SERIAL_NUMBER_LENGTH + 1
+
+
+def parse_serial_number(manufacturer_data: Mapping[int, bytes]) -> str | None:
+    """Return the serial number carried in ``manufacturer_data``, or ``None``.
+
+    ``None`` means the advertisement is not a Zendure device in the expected
+    format, so callers can ignore unrelated devices whose name merely starts
+    with ``Zen``.
+    """
+    for company_id, payload in manufacturer_data.items():
+        if not 0 <= company_id <= 0xFFFF:
+            continue
+        raw = company_id.to_bytes(2, "little") + bytes(payload)
+        if len(raw) != _RAW_LENGTH:
+            continue
+        serial = raw[:SERIAL_NUMBER_LENGTH]
+        if serial.isascii() and serial.isalnum() and serial.upper() == serial:
+            return serial.decode("ascii")
+    return None
+
+
+__all__ = ["parse_serial_number"]

zendure/ble/const.py

@@ -0,0 +1,53 @@
+"""GATT layout and limits of the Zendure BLE provisioning interface.
+
+Verified on a SolarFlow device (advertised as ``ZenEB4_5``). The device needs no
+pairing; writes require a response.
+"""
+
+from typing import Final
+
+PROVISIONING_SERVICE_UUID: Final = "0000a002-0000-1000-8000-00805f9b34fb"
+"""Vendor service that carries provisioning messages."""
+
+COMMAND_CHAR_UUID: Final = "0000c304-0000-1000-8000-00805f9b34fb"
+"""Write-with-response characteristic for requests."""
+
+NOTIFY_CHAR_UUID: Final = "0000c305-0000-1000-8000-00805f9b34fb"
+"""Read/notify characteristic the device pushes replies on."""
+
+LOCAL_NAME_PREFIX: Final = "Zen"
+"""Advertised local names start with this (``ZenEB4_5``); case-sensitive."""
+
+MAX_PACKET_BYTES: Final = 500
+"""Largest single write the device accepts (firmware limit)."""
+
+SERIAL_NUMBER_LENGTH: Final = 15
+
+DEFAULT_PROVISION_TIMEOUT: Final = 60.0
+"""Seconds to wait for the join result, including the device's DHCP lease."""
+
+HANDSHAKE_TIMEOUT: Final = 5.0
+"""Seconds to wait for the device's ``BLESPP`` greeting after subscribing."""
+
+WRITE_TIMEOUT: Final = 10.0
+"""Seconds allowed for the request write itself to be acknowledged."""
+
+SUBSCRIBE_TIMEOUT: Final = 10.0
+"""Seconds allowed for enabling notifications (the CCCD write)."""
+
+UNSUBSCRIBE_TIMEOUT: Final = 5.0
+"""Seconds allowed for disabling notifications during cleanup."""
+
+__all__ = [
+    "COMMAND_CHAR_UUID",
+    "DEFAULT_PROVISION_TIMEOUT",
+    "HANDSHAKE_TIMEOUT",
+    "LOCAL_NAME_PREFIX",
+    "MAX_PACKET_BYTES",
+    "NOTIFY_CHAR_UUID",
+    "PROVISIONING_SERVICE_UUID",
+    "SERIAL_NUMBER_LENGTH",
+    "SUBSCRIBE_TIMEOUT",
+    "UNSUBSCRIBE_TIMEOUT",
+    "WRITE_TIMEOUT",
+]

zendure/ble/provision.py

@@ -0,0 +1,345 @@
+"""Hand Wi-Fi credentials to a Zendure device over BLE, without the cloud.
+
+The caller owns the BLE connection (Home Assistant connects through its
+Bluetooth stack and proxies); this module only exchanges one request and one
+reply on an already connected client and never retries the write, because a
+timed-out write may already have reached the device.
+"""
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass
+from ipaddress import IPv4Address
+from typing import Any, Final
+
+from bleak import BleakClient
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.exc import BleakError
+
+from ..exceptions import (
+    MalformedResponseError,
+    ProvisioningFailedError,
+    ProvisioningTimeoutError,
+    ValidationError,
+    ZendureConnectionError,
+    ZendureProtocolError,
+)
+from .const import (
+    COMMAND_CHAR_UUID,
+    DEFAULT_PROVISION_TIMEOUT,
+    HANDSHAKE_TIMEOUT,
+    MAX_PACKET_BYTES,
+    NOTIFY_CHAR_UUID,
+    SUBSCRIBE_TIMEOUT,
+    UNSUBSCRIBE_TIMEOUT,
+    WRITE_TIMEOUT,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+_REQUEST_METHOD: Final = "token"
+_REPLY_METHOD: Final = "Token"
+# The device greets a new subscriber and expects this answer before requests.
+_HANDSHAKE_METHOD: Final = "BLESPP"
+_HANDSHAKE_ACK: Final = b'{"method":"BLESPP_OK"}'
+# Identifies Home Assistant as the provisioning client.
+_SOURCE_HOME_ASSISTANT: Final = 2
+# Device reply: 0 = joined the network, anything else = failed.
+_RESULT_SUCCESS: Final = 0
+_MAX_SSID_BYTES: Final = 32
+_MIN_PASSWORD_BYTES: Final = 8
+_MAX_PASSWORD_BYTES: Final = 64
+
+
+@dataclass(frozen=True, slots=True)
+class ProvisionResult:
+    """Outcome of a successful provisioning.
+
+    ``host`` is the address the device reported after joining the network, or
+    ``None`` when it reported none; callers then fall back to discovery.
+    """
+
+    serial_number: str
+    host: str | None
+
+
+def build_provision_request(ssid: str, password: str) -> bytes:
+    """Serialize the provisioning request.
+
+    UTF-8 is sent verbatim (``ensure_ascii=False``) so non-ASCII network names
+    are not turned into ``\\u`` escapes.
+
+    Raises:
+        ValidationError: SSID or password length is invalid for Wi-Fi, or the
+            request exceeds the device's packet limit.
+    """
+    ssid_len = len(ssid.encode())
+    if not 1 <= ssid_len <= _MAX_SSID_BYTES:
+        raise ValidationError(f"SSID must be 1-{_MAX_SSID_BYTES} bytes")
+    password_len = len(password.encode())
+    if password_len and not _MIN_PASSWORD_BYTES <= password_len <= _MAX_PASSWORD_BYTES:
+        raise ValidationError(
+            f"password must be empty or {_MIN_PASSWORD_BYTES}-"
+            f"{_MAX_PASSWORD_BYTES} bytes"
+        )
+    payload = {
+        "method": _REQUEST_METHOD,
+        "source": _SOURCE_HOME_ASSISTANT,
+        "ssid": ssid,
+        "password": password,
+        "AM": 0,
+    }
+    body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
+    if len(body) > MAX_PACKET_BYTES:
+        raise ValidationError(
+            f"provisioning request is {len(body)} bytes; "
+            f"device limit is {MAX_PACKET_BYTES}"
+        )
+    return body
+
+
+def parse_provision_reply(message: dict[str, Any]) -> ProvisionResult:
+    """Interpret the device's ``Token`` reply.
+
+    Raises:
+        ProvisioningFailedError: the device reports it could not join.
+        MalformedResponseError: ``result`` or ``deviceId`` is missing or wrong.
+    """
+    result = message.get("result")
+    if not isinstance(result, int) or isinstance(result, bool):
+        raise MalformedResponseError("provisioning reply has no integer result")
+    if result != _RESULT_SUCCESS:
+        raise ProvisioningFailedError(
+            f"device could not join the Wi-Fi network (result={result})"
+        )
+    serial_number = message.get("deviceId")
+    if not isinstance(serial_number, str) or not serial_number:
+        raise MalformedResponseError("provisioning reply has no deviceId")
+    return ProvisionResult(serial_number=serial_number, host=_host(message.get("ip")))
+
+
+def _host(value: object) -> str | None:
+    """Return a usable IPv4 address, or ``None`` if absent or a placeholder."""
+    if not isinstance(value, str):
+        return None
+    try:
+        address = IPv4Address(value)
+    except ValueError:
+        return None
+    if address.is_unspecified or address.is_loopback or address.is_multicast:
+        return None
+    return str(address)
+
+
+def _loggable_request(body: bytes) -> str:
+    """Return the request exactly as sent, except the password value."""
+    payload = json.loads(body)
+    if payload.get("password"):
+        payload["password"] = "***"
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+class _ReplyCollector:
+    """Reassemble notifications into the ``BLESPP`` greeting and ``Token`` reply.
+
+    Messages may arrive split across notifications or with a trailing NUL;
+    other messages on the same characteristic are logged and ignored.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = bytearray()
+        self.notifications = 0
+        loop = asyncio.get_running_loop()
+        self.greeting: asyncio.Future[dict[str, Any]] = loop.create_future()
+        self.reply: asyncio.Future[dict[str, Any]] = loop.create_future()
+
+    @property
+    def buffered(self) -> int:
+        """Bytes received that do not yet form a complete message."""
+        return len(self._buffer)
+
+    def __call__(self, _char: BleakGATTCharacteristic, data: bytearray) -> None:
+        self.notifications += 1
+        _LOGGER.debug("BLE RX %d bytes: %r", len(data), bytes(data))
+        if self.reply.done():
+            _LOGGER.debug("BLE notification after reply (%d bytes), ignored", len(data))
+            return
+        self._buffer.extend(data)
+        try:
+            message = json.loads(self._buffer.rstrip(b"\x00"))
+        except json.JSONDecodeError, UnicodeDecodeError:
+            _LOGGER.debug(
+                "BLE notification %d bytes, %d buffered, waiting for the rest",
+                len(data),
+                len(self._buffer),
+            )
+            if len(self._buffer) > MAX_PACKET_BYTES:
+                _LOGGER.debug("Dropping %d undecodable bytes", len(self._buffer))
+                self._buffer.clear()
+            return
+        self._buffer.clear()
+        method = message.get("method") if isinstance(message, dict) else None
+        if method == _HANDSHAKE_METHOD and not self.greeting.done():
+            _LOGGER.debug("BLE handshake greeting: %s", message)
+            self.greeting.set_result(message)
+        elif method == _REPLY_METHOD:
+            _LOGGER.debug("BLE provisioning reply: %s", message)
+            self.reply.set_result(message)
+        else:
+            _LOGGER.debug("Ignoring unrelated BLE message: %s", message)
+
+
+async def _async_write(
+    client: BleakClient,
+    command: BleakGATTCharacteristic,
+    data: bytes,
+    logged: str,
+) -> None:
+    """Write ``data`` with response; ``logged`` is what the TX log shows."""
+    _LOGGER.debug("BLE TX %d bytes to %s: %s", len(data), COMMAND_CHAR_UUID, logged)
+    try:
+        async with asyncio.timeout(WRITE_TIMEOUT):
+            await client.write_gatt_char(command, data, response=True)
+    except TimeoutError as err:
+        raise ZendureConnectionError(
+            "provisioning write was not acknowledged (outcome unknown)"
+        ) from err
+    except BleakError as err:
+        raise ZendureConnectionError(f"provisioning write failed: {err}") from err
+    _LOGGER.debug("BLE TX acknowledged")
+
+
+async def _async_stop_notify(
+    client: BleakClient, notify: BleakGATTCharacteristic
+) -> None:
+    """Disable notifications without letting cleanup fail or hang."""
+    try:
+        async with asyncio.timeout(UNSUBSCRIBE_TIMEOUT):
+            await client.stop_notify(notify)
+    except TimeoutError:
+        _LOGGER.debug(
+            "Stopping notifications timed out after %g s", UNSUBSCRIBE_TIMEOUT
+        )
+    except BleakError:
+        # The device may drop the link right after replying.
+        _LOGGER.debug("Could not stop notifications", exc_info=True)
+
+
+def _characteristic(client: BleakClient, uuid: str) -> BleakGATTCharacteristic:
+    char = client.services.get_characteristic(uuid)
+    if char is None:
+        raise ZendureProtocolError(
+            f"device does not expose the provisioning characteristic {uuid}"
+        )
+    return char
+
+
+async def async_provision_wifi(
+    client: BleakClient,
+    ssid: str,
+    password: str,
+    *,
+    result_timeout: float = DEFAULT_PROVISION_TIMEOUT,
+) -> ProvisionResult:
+    """Send Wi-Fi credentials and wait until the device reports the result.
+
+    ``client`` must already be connected; it is left connected on return.
+
+    Raises:
+        ValidationError: invalid credentials or request too large for the link.
+        ZendureProtocolError: the device lacks the provisioning service.
+        ZendureConnectionError: the BLE link failed, enabling notifications
+            timed out, the device did not send its ``BLESPP`` greeting, or a
+            write timed out (outcome unknown).
+        ProvisioningFailedError: the device could not join the network.
+        ProvisioningTimeoutError: no result within ``result_timeout`` seconds.
+        MalformedResponseError: the reply could not be understood.
+    """
+    body = build_provision_request(ssid, password)
+    command = _characteristic(client, COMMAND_CHAR_UUID)
+    notify = _characteristic(client, NOTIFY_CHAR_UUID)
+    if len(body) > command.max_write_without_response_size:
+        raise ValidationError(
+            f"provisioning request is {len(body)} bytes; the BLE link allows "
+            f"{command.max_write_without_response_size}"
+        )
+
+    collector = _ReplyCollector()
+    _LOGGER.debug(
+        "BLE subscribing to %s (timeout %g s)", NOTIFY_CHAR_UUID, SUBSCRIBE_TIMEOUT
+    )
+    try:
+        async with asyncio.timeout(SUBSCRIBE_TIMEOUT):
+            await client.start_notify(notify, collector)
+    except TimeoutError as err:
+        # BlueZ may have half-enabled notifications; undo them best effort.
+        await _async_stop_notify(client, notify)
+        raise ZendureConnectionError(
+            f"subscribing to replies timed out after {SUBSCRIBE_TIMEOUT:g} s"
+        ) from err
+    except BleakError as err:
+        raise ZendureConnectionError(f"could not subscribe to replies: {err}") from err
+    _LOGGER.debug(
+        "BLE subscribed to %s (props=%s), write char %s (props=%s, max write %d)",
+        NOTIFY_CHAR_UUID,
+        notify.properties,
+        COMMAND_CHAR_UUID,
+        command.properties,
+        command.max_write_without_response_size,
+    )
+    try:
+        try:
+            async with asyncio.timeout(HANDSHAKE_TIMEOUT):
+                await collector.greeting
+        except TimeoutError as err:
+            _LOGGER.debug(
+                "No %s greeting within %g s: %d notifications",
+                _HANDSHAKE_METHOD,
+                HANDSHAKE_TIMEOUT,
+                collector.notifications,
+            )
+            raise ZendureConnectionError(
+                f"device did not send {_HANDSHAKE_METHOD} within "
+                f"{HANDSHAKE_TIMEOUT:g} s; BLE link not established"
+            ) from err
+        await _async_write(client, command, _HANDSHAKE_ACK, _HANDSHAKE_ACK.decode())
+        # The password value is never logged, only its length.
+        await _async_write(
+            client,
+            command,
+            body,
+            f"{_loggable_request(body)} (password_len={len(password.encode())})",
+        )
+        _LOGGER.debug("Waiting up to %g s for the Token reply", result_timeout)
+        try:
+            async with asyncio.timeout(result_timeout):
+                message = await collector.reply
+        except TimeoutError as err:
+            _LOGGER.debug(
+                "No provisioning reply after %g s: %d notifications, %d bytes buffered",
+                result_timeout,
+                collector.notifications,
+                collector.buffered,
+            )
+            raise ProvisioningTimeoutError(
+                f"no provisioning result within {result_timeout:g} s"
+            ) from err
+    finally:
+        await _async_stop_notify(client, notify)
+
+    result = parse_provision_reply(message)
+    _LOGGER.debug(
+        "Provisioned deviceId=%s, reported host=%s",
+        result.serial_number,
+        result.host,
+    )
+    return result
+
+
+__all__ = [
+    "ProvisionResult",
+    "async_provision_wifi",
+    "build_provision_request",
+    "parse_provision_reply",
+]

zendure/catalog/__init__.py

@@ -0,0 +1,33 @@
+"""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 .faults import FaultDescription, FaultLevel, fault_codes, lookup_fault
+from .sensors import (
+    BATTERY_SENSOR_DESCRIPTIONS,
+    DEVICE_SENSOR_DESCRIPTIONS,
+    battery_sensor,
+    device_sensor,
+)
+
+__all__ = [
+    "BATTERY_SENSOR_DESCRIPTIONS",
+    "CONTROL_DESCRIPTIONS",
+    "DEVICE_SENSOR_DESCRIPTIONS",
+    "DeviceCapability",
+    "FaultDescription",
+    "FaultLevel",
+    "battery_sensor",
+    "control",
+    "device_sensor",
+    "fault_codes",
+    "lookup_device",
+    "lookup_fault",
+    "normalize_product",
+    "validate_control",
+]