zencontrol-python 0.1.0__py3-none-any.whl

zencontrol/__init__.py

@@ -0,0 +1,108 @@
+"""
+ZenControl Python Library
+
+A Python library for interfacing with ZenControl DALI lighting controllers.
+
+This library provides three distinct layers of abstraction:
+
+1. **zen_io**: Wire-level protocol implementation (UDP, message framing)
+2. **zen_api**: Zen API calls using zen_io (DALI commands, TPI protocol)
+3. **zen_interface**: Pythonic interface to Zen entities using zen_api (high-level objects)
+
+Example usage:
+    import zencontrol
+
+    # High-level interface (recommended for most users)
+    async with zencontrol.ZenControl() as zen:
+        zen.add_controller(
+            id=1,
+            name="living",
+            label="Living Room",
+            host="192.168.1.100",
+            port=5108,
+        )
+        await zen.start()
+        lights = await zen.get_lights()
+        for light in lights:
+            await light.set(level=50)
+
+    # Low-level API access (for advanced users)
+    async with zencontrol.ZenProtocol() as protocol:
+        controller = zencontrol.ZenController(protocol=protocol, ...)
+        await protocol.dali_arc_level(address, 50)
+"""
+
+# High-level interface (recommended for most users)
+from .interface import (
+    ZenControl,
+    ZenController,
+    ZenProfile,
+    ZenLight,
+    ZenGroup,
+    ZenButton,
+    ZenMotionSensor,
+    ZenSystemVariable,
+)
+
+# API-level models (used by zen_api)
+from .api.models import ZenAddress, ZenInstance, ZenColour
+from .api.protocol import ZenProtocol
+
+# Low-level models (used by zen_io)
+from .io import ZenClient, ZenListener, ZenEvent, Request, Response, ResponseType, RequestType
+
+# Shared types and exceptions
+from .api.types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventCode, ZenEventMask, ZenEventMode
+from .exceptions import ZenError, ZenTimeoutError, ZenResponseError
+
+# Utilities
+from .utils import run_with_keyboard_interrupt
+
+__version__ = "0.1.0"
+__author__ = "Simon Wright"
+
+# Public API - these are the main classes users should import
+__all__ = [
+    # High-level interface (recommended)
+    "ZenControl",
+    
+    # High-level models (for most users)
+    "ZenController",
+    "ZenProfile",
+    "ZenLight",
+    "ZenGroup",
+    "ZenButton",
+    "ZenMotionSensor",
+    "ZenSystemVariable",
+    
+    # API-level models (for advanced users)
+    "ZenAddress",
+    "ZenInstance",
+    "ZenProtocol",
+    "ZenColour",
+
+    # Low-level models (for advanced users)
+    "ZenClient",
+    "ZenListener",
+    "ZenEvent",
+    "Request",
+    "RequestType",
+    "Response",
+    "ResponseType",
+    
+    # Exceptions
+    "ZenError",
+    "ZenTimeoutError",
+    "ZenResponseError",
+    
+    # Types and enums
+    "ZenAddressType",
+    "ZenInstanceType",
+    "ZenColourType",
+    "ZenEventCode",
+    "ZenEventMask",
+    "ZenEventMode",
+    
+    # Utilities
+    "run_with_keyboard_interrupt",
+]

zencontrol/api/__init__.py

@@ -0,0 +1,30 @@
+"""
+API-level models and protocol implementation.
+
+This module contains models and types that belong to the API layer:
+- ZenController, ZenAddress, ZenInstance (API-level concepts)
+- ZenProtocol (implements TPI commands)
+- ZenColour, ZenProfile (API-level concepts used by TPI protocol)
+- Types and enums used by the API layer
+"""
+
+from .models import ZenController, ZenAddress, ZenInstance, ZenColour, ZenProfile
+from .protocol import ZenProtocol
+from .types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventMask, ZenEventMode
+
+__all__ = [
+    # API-level models
+    "ZenController",
+    "ZenAddress", 
+    "ZenInstance",
+    "ZenColour",
+    "ZenProfile",
+    "ZenProtocol",
+    
+    # API-level types
+    "ZenAddressType",
+    "ZenInstanceType",
+    "ZenColourType",
+    "ZenEventMask",
+    "ZenEventMode",
+]

zencontrol/api/models.py

@@ -0,0 +1,273 @@
+"""
+ZenControl API-level models.
+
+This module contains models that belong to the zen_api layer:
+- ZenController, ZenAddress, ZenInstance (API-level concepts)
+- ZenColour, ZenProfile (API-level concepts used by TPI protocol)
+- These are the core objects used by the TPI protocol
+"""
+
+import logging
+import socket
+import struct
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional, Self
+
+from ..io import ZenClient
+from .types import ZenAddressType, ZenInstanceType, ZenColourType, Const
+
+
+@dataclass
+class ZenController:
+    """Represents a ZenControl controller
+    
+    The 'host' field can be any resolvable hostname or IP address.
+    The 'ip' property will resolve the hostname to an IP address and cache it.
+    """
+    id: str
+    name: str
+    label: str
+    host: str
+    port: int
+    mac: Optional[str] = None
+    mac_bytes: Optional[bytes] = field(init=False, default=None)
+    # Any avoids an import cycle with protocol.py (which imports this module).
+    protocol: Optional[Any] = None
+    version: Optional[str] = None
+    startup_complete: bool = False
+    dali_ready: bool = False
+    filtering: bool = False
+    last_seen: float = field(default_factory=time.time)
+    client: Optional[ZenClient] = None
+    _ip: Optional[str] = field(init=False, repr=False, default=None)
+
+    def __post_init__(self):
+        self._update_mac_bytes(self.mac)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        object.__setattr__(self, name, value)
+        # After init, keep mac_bytes in sync when mac is assigned.
+        if name == "mac" and "mac_bytes" in self.__dict__:
+            self._update_mac_bytes(value if isinstance(value, str) or value is None else None)
+
+    def _update_mac_bytes(self, value: Optional[str]) -> None:
+        """Update mac_bytes from a MAC string (or clear it)."""
+        if value is not None:
+            object.__setattr__(
+                self,
+                "mac_bytes",
+                bytes.fromhex(value.replace(":", "").replace("-", "")),
+            )
+        else:
+            object.__setattr__(self, "mac_bytes", None)
+    
+    @property
+    def ip(self) -> str:
+        """Get the resolved IP address from the host field.
+        
+        Resolves DNS names to IP addresses and caches the result.
+        If resolution fails, returns the original host value.
+        """
+        if self._ip is None:
+            try:
+                # Try to resolve the hostname to an IP address
+                self._ip = socket.gethostbyname(self.host)
+            except (socket.gaierror, socket.herror):
+                # If resolution fails, use the host value as-is (might already be an IP)
+                self._ip = self.host
+        return self._ip
+    
+    def refresh_ip(self) -> str:
+        """Force a fresh DNS lookup and return the resolved IP address."""
+        self._ip = None
+        return self.ip
+
+
+@dataclass
+class ZenAddress:
+    """Represents a DALI address"""
+    controller: ZenController
+    type: ZenAddressType
+    number: int
+    label: Optional[str] = field(default=None, init=False)
+    serial: Optional[str] = field(default=None, init=False)
+    
+    @classmethod
+    def broadcast(cls, controller: ZenController) -> Self:
+        return cls(controller=controller, type=ZenAddressType.BROADCAST, number=255)
+    
+    def ecg(self) -> int:
+        if self.type == ZenAddressType.ECG: return self.number
+        raise ValueError("Address is not a Control Gear")
+    
+    def ecg_or_group(self) -> int:
+        if self.type == ZenAddressType.ECG: return self.number
+        if self.type == ZenAddressType.GROUP: return self.number+64
+        raise ValueError("Address is not a Control Gear or Group")
+    
+    def ecg_or_group_or_broadcast(self) -> int:
+        if self.type == ZenAddressType.ECG: return self.number
+        if self.type == ZenAddressType.GROUP: return self.number+64
+        if self.type == ZenAddressType.BROADCAST: return 255
+        raise ValueError("Address is not a Control Gear, Group or Broadcast")
+    
+    def ecg_or_ecd(self) -> int:
+        if self.type == ZenAddressType.ECG: return self.number
+        if self.type == ZenAddressType.ECD: return self.number+64
+        raise ValueError("Address is not a Control Gear or Control Device")
+    
+    def ecg_or_ecd_or_broadcast(self) -> int:
+        if self.type == ZenAddressType.ECG: return self.number
+        if self.type == ZenAddressType.ECD: return self.number+64
+        if self.type == ZenAddressType.BROADCAST: return 255
+        raise ValueError("Address is not a Control Gear, Control Device or Broadcast")
+    
+    def ecd(self) -> int:
+        if self.type == ZenAddressType.ECD: return self.number+64
+        raise ValueError("Address is not a Control Device")
+    
+    def group(self) -> int:
+        if self.type == ZenAddressType.GROUP: return self.number
+        raise ValueError("Address is not a Group")
+
+    def entity_id_string(self) -> str:
+        """Return a stable HA-friendly identifier for this address."""
+        return f"{self.type.name.casefold()}{self.number}"
+    
+    def __post_init__(self):
+        match self.type:
+            case ZenAddressType.BROADCAST:
+                if self.number != 255:
+                    raise ValueError("Broadcast address must be 255")
+            case ZenAddressType.ECG:
+                if not (0 <= self.number <= 63):
+                    raise ValueError(f"ECG address must be 0-63, got {self.number}")
+            case ZenAddressType.ECD:
+                if not (0 <= self.number <= 63):
+                    raise ValueError(f"ECD address must be 0-63, got {self.number}")
+            case ZenAddressType.GROUP:
+                if not (0 <= self.number <= 15):
+                    raise ValueError(f"Group address must be 0-15, got {self.number}")
+
+
+@dataclass
+class ZenInstance:
+    """Represents a DALI ECD instance"""
+    address: ZenAddress
+    type: ZenInstanceType
+    number: int
+    active: Optional[bool] = None
+    error: Optional[bool] = None
+    def __post_init__(self):
+        if not 0 <= self.number < Const.MAX_INSTANCE: 
+            raise ValueError(f"Instance number must be between 0 and {Const.MAX_INSTANCE-1}, received {self.number}")
+
+    def entity_id_string(self) -> str:
+        """Return a stable HA-friendly identifier for this instance."""
+        return f"{self.address.entity_id_string()}_{self.number}"
+
+
+@dataclass
+class ZenColour:
+    """Represents a DALI color"""
+    type: Optional[ZenColourType] = None
+    kelvin: Optional[int] = None
+    r: Optional[int] = None
+    g: Optional[int] = None
+    b: Optional[int] = None
+    w: Optional[int] = None
+    a: Optional[int] = None
+    f: Optional[int] = None
+    x: Optional[int] = None
+    y: Optional[int] = None
+    
+    @classmethod
+    def from_bytes(cls, bytes: bytes) -> Optional[Self]:
+        if not bytes: # If bytes is empty, return None
+            return None
+        if bytes[0] == ZenColourType.RGBWAF.value and len(bytes) == 7:
+            return cls(type=ZenColourType.RGBWAF, r=bytes[1], g=bytes[2], b=bytes[3], w=bytes[4], a=bytes[5], f=bytes[6])
+        if bytes[0] == ZenColourType.TC.value and (len(bytes) == 3 or len(bytes) == 7):
+            kelvin = (bytes[1] << 8) | bytes[2]
+            return cls(type=ZenColourType.TC, kelvin=kelvin)
+        if bytes[0] == ZenColourType.XY.value and (len(bytes) == 5 or len(bytes) == 7):
+            x = (bytes[1] << 8) | bytes[2]
+            y = (bytes[3] << 8) | bytes[4]
+            return cls(type=ZenColourType.XY, x=x, y=y)
+        return None
+    
+    def __post_init__(self):
+        if self.type == ZenColourType.TC:
+            kelvin = self.kelvin
+            if kelvin is None:
+                raise ValueError("Kelvin is required for TC colour type")
+            if not Const.MIN_KELVIN <= kelvin <= Const.MAX_KELVIN:
+                #raise ValueError(f"Kelvin must be between {Const.MIN_KELVIN} and {Const.MAX_KELVIN}, received {self.kelvin}")
+                logging.getLogger(__name__).warning(
+                    "Kelvin %s out of range [%s, %s]; clamping",
+                    kelvin, Const.MIN_KELVIN, Const.MAX_KELVIN,
+                )
+                # set to the nearest valid value
+                self.kelvin = max(Const.MIN_KELVIN, min(Const.MAX_KELVIN, kelvin))
+        if self.type == ZenColourType.RGBWAF:
+            r, g, b = self.r, self.g, self.b
+            if r is None or not 0 <= r <= 255:
+                raise ValueError(f"R must be between 0 and 255, received {self.r}")
+            if g is None or not 0 <= g <= 255:
+                raise ValueError(f"G must be between 0 and 255, received {self.g}")
+            if b is None or not 0 <= b <= 255:
+                raise ValueError(f"B must be between 0 and 255, received {self.b}")
+            if self.w is not None and not 0 <= self.w <= 255:
+                raise ValueError(f"W must be between 0 and 255, received {self.w}")
+            if self.a is not None and not 0 <= self.a <= 255:
+                raise ValueError(f"A must be between 0 and 255, received {self.a}")
+            if self.f is not None and not 0 <= self.f <= 255:
+                raise ValueError(f"F must be between 0 and 255, received {self.f}")
+        if self.type == ZenColourType.XY:
+            x, y = self.x, self.y
+            if x is None or not 0 <= x <= 65535:
+                raise ValueError(f"X must be between 0 and 65535, received {self.x}")
+            if y is None or not 0 <= y <= 65535:
+                raise ValueError(f"Y must be between 0 and 65535, received {self.y}")
+    
+    def __repr__(self) -> str:
+        if self.type == ZenColourType.TC:
+            return f"ZenColour(kelvin={self.kelvin})"
+        if self.type == ZenColourType.RGBWAF:
+            return f"ZenColour(r={self.r}, g={self.g}, b={self.b}, w={self.w}, a={self.a}, f={self.f})"
+        if self.type == ZenColourType.XY:
+            return f"ZenColour(x={self.x}, y={self.y})"
+        return f"ZenColour(type={self.type})"
+    
+    def __eq__(self, other):
+        if isinstance(other, self.__class__):
+            return self.__dict__ == other.__dict__
+        else:
+            return False
+    
+    def to_bytes(self, level: int = 255) -> bytes:
+        """Encode colour data as returned by QUERY_DALI_COLOUR (no address or arc level)."""
+        if self.type == ZenColourType.TC:
+            return struct.pack('>BH', 0x20, self.kelvin)
+        if self.type == ZenColourType.RGBWAF:
+            return struct.pack('BBBBBBB', 0x80, self.r, self.g, self.b, self.w if self.w is not None else 0, self.a if self.a is not None else 0, self.f if self.f is not None else 0)
+        if self.type == ZenColourType.XY:
+            return struct.pack('>BHH', 0x10, self.x, self.y)
+        return b''
+
+    def command_payload(self) -> bytes:
+        """Colour type and channel bytes for DALI_COLOUR (follows address and arc level)."""
+        return self.to_bytes()
+
+
+@dataclass
+class ZenProfile:
+    """Represents a DALI profile"""
+    controller: ZenController
+    address: ZenAddress
+    profile: int
+    
+    def __post_init__(self):
+        if not (0 <= self.profile <= 255):
+            raise ValueError(f"Profile must be 0-255, got {self.profile}")