pylumencache 0.0.1__py3-none-any.whl

pylumencache/__init__.py

@@ -0,0 +1,13 @@
+"""Unofficial Python client for LumenCache ReNetA lighting."""
+from .api import LumenCache
+from .domain.commands import Command, SetLight
+from .domain.events import Event
+from .domain.model import Category, Change, Device, LightState, SystemModel
+from .transport import NotConnectedError, Transport, UnsupportedError
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Category", "Change", "Command", "Device", "Event", "LightState", "LumenCache", "NotConnectedError",
+    "SetLight", "SystemModel", "Transport", "UnsupportedError",
+]

pylumencache/api.py

@@ -0,0 +1,73 @@
+"""The public entry point: one ReNetA system, reached through a transport.
+
+    cache = LumenCache.mqtt("broker.example.com", "<Prefix Topic>", username=..., password=...)
+    cache.model.add_listener(on_change)
+    await cache.start()
+    await cache.wait_connected()
+    await cache.send(SetLight("zone", 250, brightness=50))
+
+The facade owns the SystemModel and keeps it fed from the transport. A caller never needs
+to know which transport is underneath.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .domain.commands import Command
+from .domain.model import SystemModel
+from .transport import Transport, UnsupportedError
+from .transports.fallback import DEFAULT_FAIL_AFTER, FallbackTransport
+
+
+class LumenCache:
+    def __init__(self, transport: Transport, model: SystemModel | None = None) -> None:
+        self.transport = transport
+        self.model = model if model is not None else SystemModel()
+        self.model.attach(transport)
+
+    @classmethod
+    def mqtt(cls, host: str, prefix: str, *, model: SystemModel | None = None, **options: Any) -> LumenCache:
+        """Over the hosted MQTT broker. `options` are those of MqttTransport (port, username, ...)."""
+        from .transports.mqtt import MqttTransport
+        return cls(MqttTransport(host, prefix, **options), model)
+
+    @classmethod
+    def with_fallback(
+        cls,
+        transports: Sequence[Transport],
+        *,
+        fail_after: float = DEFAULT_FAIL_AFTER,
+        model: SystemModel | None = None,
+    ) -> LumenCache:
+        """Several transports in priority order. A later one is connected only while the earlier ones are down.
+
+        `fail_after` is how many seconds without a connection before the next one is started.
+        """
+        return cls(FallbackTransport(transports, fail_after=fail_after), model)
+
+    @property
+    def connected(self) -> bool:
+        return self.transport.connected
+
+    def add_connection_listener(self, callback: Callable[[bool], Any]) -> Callable[[], None]:
+        return self.transport.add_connection_listener(callback)
+
+    async def start(self) -> None:
+        await self.transport.start()
+
+    async def stop(self) -> None:
+        await self.transport.stop()
+
+    async def wait_connected(self, timeout: float | None = None) -> None:
+        await self.transport.wait_connected(timeout)
+
+    async def send(self, command: Command) -> None:
+        await self.transport.send(command)
+
+    async def send_raw(self, message: dict[str, Any]) -> None:
+        """Send a command in the transport's own format, as a fallback. Not every transport has one."""
+        send_raw = getattr(self.transport, "send_raw", None)
+        if send_raw is None:
+            raise UnsupportedError("this transport has no raw commands")
+        await send_raw(message)

pylumencache/domain/__init__.py

@@ -0,0 +1 @@
+"""Transport-independent model, events and commands."""

pylumencache/domain/commands.py

@@ -0,0 +1,20 @@
+"""What a caller asks of a system, independent of any wire format."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .events import LightKind
+
+
+@dataclass(frozen=True)
+class SetLight:
+    """Set a zone or a fixture. A brightness of 0 turns it off."""
+
+    kind: LightKind
+    key: int
+    brightness: float   # percent, 0 to 100
+    color_temperature: int | None = None   # kelvin
+    fade: int | None = None   # ms
+
+
+Command = SetLight

pylumencache/domain/events.py

@@ -0,0 +1,48 @@
+"""What a transport tells the domain model, independent of any wire format."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+LightKind = Literal["zone", "fixture"]
+Source = Literal["event", "command", "unknown"]
+
+
+@dataclass(frozen=True)
+class DeviceAnnounced:
+    """A device exists. `path` is where the system placed it in its device tree."""
+
+    gid: int
+    path: str
+    name: str | None = None
+    hsn: str | None = None
+    category: int | None = None
+    parent: int | None = None
+
+
+@dataclass(frozen=True)
+class DeviceSeen:
+    """A device showed signs of life. `hsn` is its serial number, when the message carried it."""
+
+    gid: int
+    hsn: str | None = None
+
+
+@dataclass(frozen=True)
+class LightChanged:
+    """A zone or fixture changed state. None means the message did not say.
+
+    `source` is "event" when the system reported it and "command" when it is a command as
+    sent, which the system does not confirm.
+    """
+
+    kind: LightKind
+    key: int
+    on: bool | None = None
+    brightness: float | None = None   # percent, 0 to 100
+    color_temperature: int | None = None   # kelvin
+    fade: int | None = None   # ms
+    source: Source = "unknown"
+
+
+Event = DeviceAnnounced | DeviceSeen | LightChanged

pylumencache/domain/model.py

@@ -0,0 +1,178 @@
+"""What is in the system and what state it is in, built from domain events.
+
+The system does not report the state of a light when asked, and it does not keep its
+inventory on the broker (nothing is retained). So the model learns from what passes by:
+
+* devices come from announcements, which the system publishes once after it connects.
+  Use to_dict()/from_dict() to keep them across restarts;
+* a zone or light changes state when a wall switch reports it or when any client,
+  including this one, sends a control command that the transport sees. Those states are
+  the commands as sent. The system does not confirm that they happened;
+* signs of life show which devices are alive.
+
+Fixtures that belong to a zone are not updated when the zone changes, because the
+membership of a zone cannot be read from the system.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from enum import IntEnum
+from typing import Any, Protocol
+
+from .events import DeviceAnnounced, DeviceSeen, Event, LightChanged
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EventSource(Protocol):
+    def add_listener(self, callback: Callable[[Event], Any]) -> Callable[[], None]: ...
+
+NO_PARENT = 65535
+
+
+class Category(IntEnum):
+    """Device category (`cat`). Other values are possible and are kept as plain integers."""
+
+    POWERPLANE = 32
+    PDM = 35
+    SOCKET = 36
+    SOCKET_CARD = 37
+    WALL_SWITCH = 40
+
+
+@dataclass(frozen=True)
+class Device:
+    gid: int
+    path: str
+    name: str | None = None
+    hsn: str | None = None
+    category: int | None = None
+    parent: int | None = None   # a GID, NO_PARENT for none, 0 not yet assigned
+
+    @property
+    def kind(self) -> Category | int | None:
+        if self.category is None:
+            return None
+        try:
+            return Category(self.category)
+        except ValueError:
+            return self.category
+
+
+@dataclass(frozen=True)
+class LightState:
+    """The last known state of a zone or fixture. None means not known."""
+
+    on: bool | None = None
+    brightness: float | None = None    # percent, 0 to 100
+    color_temperature: int | None = None   # kelvin
+    fade: int | None = None   # ms, from the last command
+    source: str = "unknown"   # "event" (reported by the system) or "command" (as sent, not confirmed)
+
+
+@dataclass(frozen=True)
+class Change:
+    """Passed to listeners. `kind` is "device", "zone", "fixture" or "seen"; `key` is the id."""
+
+    kind: str
+    key: int
+
+
+@dataclass
+class SystemModel:
+    devices: dict[int, Device] = field(default_factory=dict)
+    zones: dict[int, LightState] = field(default_factory=dict)
+    fixtures: dict[int, LightState] = field(default_factory=dict)
+    last_seen: dict[int, float] = field(default_factory=dict)   # GID -> time.monotonic() of the last sign of life
+    _listeners: list[Callable[[Change], Any]] = field(default_factory=list, repr=False)
+
+    # --- reading -----------------------------------------------------------
+
+    def children(self, gid: int) -> list[Device]:
+        return [d for d in self.devices.values() if d.parent == gid]
+
+    def seconds_since_seen(self, gid: int) -> float | None:
+        seen = self.last_seen.get(gid)
+        return None if seen is None else time.monotonic() - seen
+
+    # --- updating ----------------------------------------------------------
+
+    def add_listener(self, callback: Callable[[Change], Any]) -> Callable[[], None]:
+        self._listeners.append(callback)
+        return lambda: self._listeners.remove(callback)
+
+    def attach(self, source: EventSource) -> Callable[[], None]:
+        """Feed the model from anything with `add_listener(callback)`, such as a Transport."""
+        return source.add_listener(self.apply)
+
+    def apply(self, event: Event) -> None:
+        """Update from one event."""
+        if isinstance(event, DeviceAnnounced):
+            self._device(event)
+        elif isinstance(event, DeviceSeen):
+            self._seen(event)
+        elif isinstance(event, LightChanged):
+            table = self.zones if event.kind == "zone" else self.fixtures
+            self._set_state(table, event.kind, event.key, LightState(
+                event.on, event.brightness, event.color_temperature, event.fade, event.source))
+
+    def _notify(self, kind: str, key: int) -> None:
+        for callback in list(self._listeners):
+            try:
+                callback(Change(kind, key))
+            except Exception:   # a listener must not break the model
+                _LOGGER.exception("A model listener raised an exception")
+
+    def _device(self, event: DeviceAnnounced) -> None:
+        known = self.devices.get(event.gid)
+        hsn = event.hsn or (known.hsn if known else None)
+        device = Device(event.gid, event.path, event.name, hsn, event.category, event.parent)
+        if device != known:
+            self.devices[event.gid] = device
+            self._notify("device", event.gid)
+
+    def _seen(self, event: DeviceSeen) -> None:
+        self.last_seen[event.gid] = time.monotonic()
+        device = self.devices.get(event.gid)
+        if device and event.hsn and not device.hsn:   # the PowerPlane's announcement has no serial
+            self.devices[event.gid] = Device(
+                device.gid, device.path, device.name, event.hsn, device.category, device.parent)
+            self._notify("device", event.gid)
+        self._notify("seen", event.gid)
+
+    def _set_state(self, table: dict[int, LightState], kind: str, key: int, new: LightState) -> None:
+        """Merge `new` into the stored state: fields the message did not carry keep their value."""
+        old = table.get(key, LightState())
+        merged = LightState(
+            on=old.on if new.on is None else new.on,
+            brightness=old.brightness if new.brightness is None else new.brightness,
+            color_temperature=old.color_temperature if new.color_temperature is None else new.color_temperature,
+            fade=old.fade if new.fade is None else new.fade,
+            source=new.source,
+        )
+        if merged.on and merged.brightness == 0:
+            merged = LightState(True, None, merged.color_temperature, merged.fade, merged.source)
+        if merged != old:
+            table[key] = merged
+            self._notify(kind, key)
+
+    # --- keeping it across restarts ---------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-able copy of the devices and the last known states (not heartbeats)."""
+        return {
+            "devices": [asdict(d) for d in self.devices.values()],
+            "zones": {str(k): asdict(v) for k, v in self.zones.items()},
+            "fixtures": {str(k): asdict(v) for k, v in self.fixtures.items()},
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SystemModel:
+        model = cls()
+        model.devices = {d["gid"]: Device(**d) for d in data.get("devices", [])}
+        model.zones = {int(k): LightState(**v) for k, v in data.get("zones", {}).items()}
+        model.fixtures = {int(k): LightState(**v) for k, v in data.get("fixtures", {}).items()}
+        return model

pylumencache/obfuscate.py

@@ -0,0 +1,84 @@
+"""Make captured traffic safe to share: stable fakes for ids, blanked free text.
+
+Used by the capture tool for the files it writes and by tools/watch.py for the screen.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+class Obfuscator:
+    """Make a capture safe to share: stable fakes for ids, blanked free text.
+
+    Within one run the same real value always gets the same fake, so the
+    relationships between messages survive. The mapping is kept in memory only.
+    """
+
+    ID_KEYS = {"hsn": "HSN", "sys": "SYS"}
+    FREE_TEXT = {"name", "addr1", "addr2", "zip", "phone", "note"}
+    FREE_TEXT_PARENTS = {"sys_info", "org_info"}   # inside "meta"; dev names stay
+    SUFFIX = re.compile(r"^(.+?)(_S\d+)$")        # socket hsn = PDM hsn + _S1.._S8
+    MAC = re.compile(r"\b[0-9A-Fa-f]{2}(?:[:-][0-9A-Fa-f]{2}){5}\b")
+
+    def __init__(self, prefix: str) -> None:
+        self.prefix = prefix
+        self.fakes: dict[tuple[str, str], str] = {}   # real value -> fake
+
+    def _fake(self, kind: str, real: str) -> str:
+        key = (kind, real)
+        if key not in self.fakes:
+            n = sum(1 for k in self.fakes if k[0] == kind) + 1
+            self.fakes[key] = f"{kind}{n:04d}" if kind != "MAC" else \
+                f"02:00:00:00:{n >> 8 & 255:02x}:{n & 255:02x}"
+        return self.fakes[key]
+
+    def _id(self, kind: str, value: Any) -> str:
+        real = str(value)
+        m = self.SUFFIX.match(real)
+        if m:
+            return self._fake(kind, m.group(1)) + m.group(2)
+        return self._fake(kind, real)
+
+    def text(self, value: str) -> str:
+        """Scrub free-form text: the prefix, known ids and MAC-shaped strings."""
+        value = value.replace(self.prefix, "<prefix>")
+        for (kind, real), fake in sorted(self.fakes.items(), key=lambda kv: -len(kv[0][1])):
+            if kind != "MAC" and real:
+                value = value.replace(real, fake)
+        return self.MAC.sub(lambda m: self._fake("MAC", m.group(0).lower()), value)
+
+    def _learn(self, node: Any) -> None:
+        if isinstance(node, dict):
+            for k, v in node.items():
+                if k in self.ID_KEYS and not isinstance(v, (dict, list)):
+                    self._id(self.ID_KEYS[k], v)
+                else:
+                    self._learn(v)
+        elif isinstance(node, list):
+            for v in node:
+                self._learn(v)
+
+    def _walk(self, node: Any, parent: str | None = None, in_meta: bool = False) -> Any:
+        if isinstance(node, dict):
+            result: dict[str, Any] = {}
+            for k, v in node.items():
+                if k in self.ID_KEYS and not isinstance(v, (dict, list)):
+                    result[k] = self._id(self.ID_KEYS[k], v)
+                elif (in_meta and parent in self.FREE_TEXT_PARENTS
+                      and k in self.FREE_TEXT and v not in ("", None)):
+                    result[k] = ""
+                else:
+                    result[k] = self._walk(v, k, in_meta or k == "meta")
+            return result
+        if isinstance(node, list):
+            return [self._walk(v, parent, in_meta) for v in node]
+        if isinstance(node, str):
+            return self.text(node)
+        return node
+
+    def payload(self, node: Any) -> Any:
+        if isinstance(node, str):
+            return self.text(node)
+        self._learn(node)
+        return self._walk(node)

pylumencache/transport.py

@@ -0,0 +1,46 @@
+"""The interface between the library and a way of reaching a ReNetA system.
+
+A transport turns what its wire format carries into domain events and domain commands
+into wire messages. Everything above it (the model, the facade, an integration) never
+sees a topic, an event code or a URL.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from .domain.commands import Command
+from .domain.events import Event
+
+
+class NotConnectedError(ConnectionError):
+    """A command was sent while the transport was not connected."""
+
+
+class UnsupportedError(NotImplementedError):
+    """The transport cannot do what was asked."""
+
+
+class Transport(Protocol):
+    @property
+    def connected(self) -> bool: ...
+
+    def add_listener(self, callback: Callable[[Event], Any]) -> Callable[[], None]:
+        """Call `callback(event)` for each domain event. Returns a function that removes it."""
+        ...
+
+    def add_connection_listener(self, callback: Callable[[bool], Any]) -> Callable[[], None]:
+        """Call `callback(True)` when connected and `callback(False)` when the connection is lost."""
+        ...
+
+    async def start(self) -> None:
+        """Start connecting in the background. Returns at once."""
+        ...
+
+    async def stop(self) -> None: ...
+
+    async def wait_connected(self, timeout: float | None = None) -> None: ...
+
+    async def send(self, command: Command) -> None:
+        """Raises NotConnectedError when not connected."""
+        ...

pylumencache/transports/__init__.py

@@ -0,0 +1 @@
+"""Ways of reaching a ReNetA system. Each subpackage implements pylumencache.transport.Transport."""

pylumencache/transports/fallback.py

@@ -0,0 +1,181 @@
+"""Several transports in priority order, with the later ones used only when the earlier ones are down.
+
+    FallbackTransport([first, second])
+
+Only the first transport is started at first. If it is not connected after `fail_after`
+seconds, the second is started as well, and so on down the list. The earlier transports keep
+trying to connect in the background, and as soon as one of them connects, the transports
+after it are stopped. So a later transport is connected only while every earlier one is down.
+
+Events come from the highest-priority transport that is connected, and commands go to it, so
+the model never sees two sources at once. "Down" means not connected: a transport that is
+connected but silent counts as up. The order is the order of the list.
+
+This module knows nothing about any particular transport.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Sequence
+from functools import partial
+from typing import Any
+
+from ..domain.commands import Command
+from ..domain.events import Event
+from ..transport import NotConnectedError, Transport, UnsupportedError
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_FAIL_AFTER = 30.0   # seconds
+
+
+class FallbackTransport:
+    """Implements pylumencache.transport.Transport on top of an ordered list of transports."""
+
+    def __init__(self, transports: Sequence[Transport], *, fail_after: float = DEFAULT_FAIL_AFTER) -> None:
+        if not transports:
+            raise ValueError("give at least one transport")
+        self._transports = list(transports)
+        self._fail_after = fail_after
+        self._started = 0   # how many, from the front of the list, are running
+        self._active: int | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._connected = asyncio.Event()
+        self._changed = asyncio.Event()
+        self._listeners: list[Callable[[Event], Any]] = []
+        self._connection_listeners: list[Callable[[bool], Any]] = []
+        for index, transport in enumerate(self._transports):
+            transport.add_listener(partial(self._forward, index))
+            transport.add_connection_listener(partial(self._on_connection, index))
+
+    # --- Transport ----------------------------------------------------------
+
+    @property
+    def connected(self) -> bool:
+        return self._connected.is_set()
+
+    @property
+    def transports(self) -> tuple[Transport, ...]:
+        """The transports, in priority order."""
+        return tuple(self._transports)
+
+    @property
+    def active(self) -> Transport | None:
+        """The transport in use: the highest-priority one that is connected."""
+        index = self._first_connected()
+        return None if index is None else self._transports[index]
+
+    def add_listener(self, callback: Callable[[Event], Any]) -> Callable[[], None]:
+        self._listeners.append(callback)
+        return lambda: self._listeners.remove(callback)
+
+    def add_connection_listener(self, callback: Callable[[bool], Any]) -> Callable[[], None]:
+        """Called with True when some transport connects and False when none is connected."""
+        self._connection_listeners.append(callback)
+        return lambda: self._connection_listeners.remove(callback)
+
+    async def start(self) -> None:
+        if self._task is None:
+            self._started = 1
+            await self._transports[0].start()
+            self._task = asyncio.create_task(self._supervise(), name="lumencache-fallback")
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        for transport in self._transports[:self._started]:
+            await transport.stop()
+        self._started = 0
+        self._update()
+
+    async def wait_connected(self, timeout: float | None = None) -> None:
+        await asyncio.wait_for(self._connected.wait(), timeout)
+
+    async def send(self, command: Command) -> None:
+        await self._send_with(lambda transport: transport.send(command))
+
+    async def send_raw(self, message: dict[str, Any]) -> None:
+        """Send a command in a transport's own format, to the first connected transport that has one."""
+        async def call(transport: Transport) -> None:
+            send_raw = getattr(transport, "send_raw", None)
+            if send_raw is None:
+                raise UnsupportedError("this transport has no raw commands")
+            await send_raw(message)
+
+        await self._send_with(call)
+
+    # --- internals ----------------------------------------------------------
+
+    async def _send_with(self, call: Callable[[Transport], Any]) -> None:
+        unsupported = False
+        for transport in self._transports:
+            if not transport.connected:
+                continue
+            try:
+                await call(transport)
+                return
+            except UnsupportedError:
+                unsupported = True
+        if unsupported:
+            raise UnsupportedError("no connected transport can do this")
+        raise NotConnectedError("no transport is connected")
+
+    def _first_connected(self) -> int | None:
+        for index, transport in enumerate(self._transports):
+            if transport.connected:
+                return index
+        return None
+
+    def _forward(self, index: int, event: Event) -> None:
+        if index != self._first_connected():
+            return   # only the transport in use speaks; a lower-priority one is on its way out
+        for callback in list(self._listeners):
+            self._call(callback, event)
+
+    def _on_connection(self, index: int, connected: bool) -> None:
+        self._update()
+
+    def _update(self) -> None:
+        active = self._first_connected()
+        if active != self._active:
+            _LOGGER.info("Using transport %s", "none" if active is None else type(self._transports[active]).__name__)
+            self._active = active
+        self._changed.set()
+        connected = active is not None
+        if connected != self._connected.is_set():
+            self._connected.set() if connected else self._connected.clear()
+            for callback in list(self._connection_listeners):
+                self._call(callback, connected)
+
+    def _call(self, callback: Callable[..., Any], *args: Any) -> None:
+        try:
+            callback(*args)
+        except Exception:
+            _LOGGER.exception("A listener raised an exception")
+
+    async def _supervise(self) -> None:
+        """Start the next transport when all running ones stay down, stop the later ones when an earlier one is up."""
+        while True:
+            self._changed.clear()
+            first = self._first_connected()
+            if first is not None:
+                while self._started > first + 1:
+                    self._started -= 1
+                    _LOGGER.info("Stopping %s, a higher-priority transport is connected",
+                                 type(self._transports[self._started]).__name__)
+                    await self._transports[self._started].stop()
+                await self._changed.wait()
+            elif self._started < len(self._transports):
+                try:
+                    await asyncio.wait_for(self._changed.wait(), self._fail_after)
+                except TimeoutError:
+                    transport = self._transports[self._started]
+                    _LOGGER.warning("No transport connected after %s s, starting %s",
+                                    self._fail_after, type(transport).__name__)
+                    self._started += 1
+                    await transport.start()
+            else:
+                await self._changed.wait()

pylumencache/transports/mqtt/__init__.py

@@ -0,0 +1,4 @@
+"""The MQTT transport: the hosted broker's wire format and a client that speaks it."""
+from .client import MqttTransport
+
+__all__ = ["MqttTransport"]