zencontrol-python 0.1.0__py3-none-any.whl

zencontrol/io/event.py

@@ -0,0 +1,316 @@
+"""
+ZenControl wire-level event listener.
+
+This module implements the event/listener side of ZenControl TPI Advanced using asyncio.
+It contains the ZenListener class for receiving multicast or unicast event packets.
+
+Terms:
+- Event = A multicast or unicast packet sent by a controller
+- Listener = A class which receives Events
+
+Example usage:
+async def listen_for_events():
+    listener = await ZenListener.create(unicast=False)  # Multicast mode
+    async with listener:
+        async for event in listener.events():
+            print(f"Event: {event.event_code}, Target: {event.target}, Payload: {event.payload.hex()}")
+
+asyncio.run(listen_for_events())
+"""
+
+import asyncio
+import socket
+import struct
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, AsyncGenerator
+
+# Event classes
+@dataclass
+class ZenEvent:
+    """Represents a Zen TPI event"""
+    raw_data: bytes
+    event_code: int
+    target: int
+    payload: bytes
+    mac_address: bytes
+    ip_address: str
+    ip_port: int
+    timestamp: float = field(default_factory=time.time)
+
+# Constants
+class EventConst:
+    """Constants for event handling"""
+    MULTICAST_GROUP = "239.255.90.67"
+    MULTICAST_PORT = 6969
+    DEFAULT_MAX_QUEUE_SIZE = 1000
+    DROP_LOG_INTERVAL = 5.0  # seconds between queue-full warnings
+
+class ZenEventProtocol(asyncio.DatagramProtocol):
+    def __init__(
+        self,
+        event_handler: Callable[[bytes, Tuple[str, int]], Awaitable[None]],
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.event_handler = event_handler
+        self.logger = logger or logging.getLogger(__name__)
+        self.transport = None
+    def connection_made(self, transport):
+        self.transport = transport
+    def datagram_received(self, data, addr):
+        self._run_handler(self.event_handler(data, addr))
+
+    def _run_handler(self, coro: Awaitable[None]):
+        task = asyncio.ensure_future(coro)
+        task.add_done_callback(self._handler_done)
+
+    def _handler_done(self, task: asyncio.Task[None]):
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc:
+            self.logger.error(f"Event handler failed: {exc}", exc_info=exc)
+    def error_received(self, exc):
+        self.logger.error(f"Event protocol error: {exc}")
+    def connection_lost(self, exc):
+        if exc:
+            self.logger.error(f"Event connection lost: {exc}")
+        else:
+            self.logger.info("Event connection closed")
+
+class ZenListener:
+    def __init__(
+        self,
+        unicast: bool = False,
+        listen_ip: str = "0.0.0.0",
+        listen_port: int = 0,
+        logger: Optional[logging.Logger] = None,
+        max_queue_size: int = EventConst.DEFAULT_MAX_QUEUE_SIZE,
+    ):
+        self.unicast = unicast
+        self.listen_ip = listen_ip
+        self.listen_port = listen_port
+        self.logger = logger or logging.getLogger(__name__)
+        self.max_queue_size = max(1, max_queue_size)
+
+        # Modern asyncio components
+        self.transport: Optional[asyncio.DatagramTransport] = None
+        self.protocol: Optional[ZenEventProtocol] = None
+        self._stop_event = asyncio.Event()
+
+        # Bounded queue: drop-oldest under backpressure so the UDP path never stalls
+        self._event_queue: asyncio.Queue[ZenEvent] = asyncio.Queue(maxsize=self.max_queue_size)
+        self.dropped_events = 0
+        self._last_drop_log = 0.0
+
+    @classmethod
+    async def create(
+        cls,
+        unicast: bool = False,
+        listen_ip: str = "0.0.0.0",
+        listen_port: int = 0,
+        logger: Optional[logging.Logger] = None,
+        max_queue_size: int = EventConst.DEFAULT_MAX_QUEUE_SIZE,
+    ) -> "ZenListener":
+        """Create and start a ZenListener instance"""
+        self = cls(unicast, listen_ip, listen_port, logger, max_queue_size=max_queue_size)
+        await self._create_datagram_endpoint()
+        self.logger.info(f"Started event listener in {'unicast' if self.unicast else 'multicast'} mode")
+        return self
+
+    async def start_listening(self):
+        if self.transport and not self.transport.is_closing():
+            self.logger.warning("Event listener already running")
+            return
+        
+        self._stop_event.clear()
+        await self._create_datagram_endpoint()
+        self.logger.info(f"Started event listener in {'unicast' if self.unicast else 'multicast'} mode")
+
+    async def stop_listening(self):
+        if self.transport and not self.transport.is_closing():
+            self._stop_event.set()
+            self.transport.close()
+            self.transport = None
+            self.protocol = None
+            
+            # Clear any remaining events in queue
+            while not self._event_queue.empty():
+                try:
+                    self._event_queue.get_nowait()
+                    self._event_queue.task_done()
+                except asyncio.QueueEmpty:
+                    break
+        
+        self.logger.info("Stopped event listener")
+
+    async def close(self):
+        """Close the listener (alias for stop_listening for async context manager compatibility)"""
+        await self.stop_listening()
+
+    def is_listening(self) -> bool:
+        """Check if the listener is active and ready"""
+        return self.transport is not None and not self.transport.is_closing()
+
+    async def _create_datagram_endpoint(self):
+        loop = asyncio.get_running_loop()
+        
+        if self.unicast:
+            # Unicast mode
+            self.transport, _ = await loop.create_datagram_endpoint(
+                lambda: ZenEventProtocol(self._receive_event, self.logger),
+                local_addr=(self.listen_ip, self.listen_port),
+                reuse_port=True
+            )
+            sockname = self.transport.get_extra_info('sockname')
+            if sockname:
+                self.listen_port = sockname[1]
+            self.logger.info(f"Listening for unicast events on {self.listen_ip}:{self.listen_port}")
+        else:  
+            # Multicast mode
+            try:
+                self.transport, _ = await loop.create_datagram_endpoint(
+                    lambda: ZenEventProtocol(self._receive_event, self.logger),
+                    local_addr=('0.0.0.0', EventConst.MULTICAST_PORT),
+                    reuse_port=True
+                )
+                self.logger.info(f"Listening for multicast events on {EventConst.MULTICAST_GROUP}:{EventConst.MULTICAST_PORT}")
+
+                # Join the multicast group
+                sock = self.transport.get_extra_info('socket')
+                if sock:
+                    # Set socket options for multicast
+                    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                    group = socket.inet_aton(EventConst.MULTICAST_GROUP)
+                    mreq = struct.pack('=4sI', group, socket.INADDR_ANY)
+                    sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+            except Exception as e:
+                self.logger.critical(f"Failed to create multicast endpoint: {e}")
+                raise
+
+    async def _receive_event(self, data: bytes, addr: Tuple[str, int]):
+        """Process received event data"""
+        typecast = "unicast" if self.unicast else "multicast"
+        
+        # Drop packet if it doesn't match the expected structure
+        if len(data) < 13 or data[0:2] != bytes([0x5a, 0x43]):
+            self.logger.debug(f"Received {typecast} invalid packet: {addr} - {', '.join(f'0x{b:02x}' for b in data)}")
+            return
+
+        # Extract values
+        mac_address = data[2:8]
+        target = int.from_bytes(data[8:10], byteorder='big')
+        event_code = data[10]
+        payload_len = data[11]
+        payload = data[12:-1]
+        received_checksum = data[-1]
+
+        # Verify checksum
+        calculated_checksum = self._checksum(data[:-1])
+        if received_checksum != calculated_checksum:
+            self.logger.error(f"{typecast.capitalize()} packet has invalid checksum: {calculated_checksum} != {received_checksum}")
+            return
+        
+        # Verify data length
+        if len(payload) != payload_len:
+            self.logger.error(f"{typecast.capitalize()} packet has invalid payload length: {len(payload)} != {payload_len}")
+            return
+        
+        # Create event object and put in queue
+        event = ZenEvent(
+            raw_data=data,
+            mac_address=mac_address,
+            target=target,
+            event_code=event_code,
+            payload=payload,
+            ip_address=addr[0],
+            ip_port=addr[1],
+            timestamp=time.time()
+        )
+
+        if event_code != 7 and event_code != 8: # 7=system varaiable, 8=colour changed
+            self.logger.debug(f"Received {typecast} from {addr[0]}:{addr[1]}: target {target} event {event_code} payload [{', '.join(f'0x{b:02x}' for b in payload)}]")
+
+        self._enqueue_event(event)
+
+    def _enqueue_event(self, event: ZenEvent) -> None:
+        """Enqueue event; if full, drop the oldest and keep the newest."""
+        try:
+            self._event_queue.put_nowait(event)
+            return
+        except asyncio.QueueFull:
+            pass
+
+        try:
+            self._event_queue.get_nowait()
+            self._event_queue.task_done()
+        except asyncio.QueueEmpty:
+            pass
+
+        try:
+            self._event_queue.put_nowait(event)
+        except asyncio.QueueFull:
+            pass
+
+        self.dropped_events += 1
+        now = time.time()
+        if now - self._last_drop_log >= EventConst.DROP_LOG_INTERVAL:
+            self._last_drop_log = now
+            self.logger.warning(
+                "Event queue full (max=%d); dropped %d event(s) total",
+                self.max_queue_size,
+                self.dropped_events,
+            )
+
+    async def events(self, timeout: Optional[float] = None) -> AsyncGenerator[ZenEvent, None]:
+        """Async generator yielding events as they arrive"""
+        while not self._stop_event.is_set():
+            try:
+                event = await asyncio.wait_for(
+                    self._event_queue.get(), 
+                    timeout=timeout
+                )
+                yield event
+                self._event_queue.task_done()
+            except asyncio.TimeoutError:
+                if timeout is not None:
+                    break
+                continue
+    
+    async def get_event(self, timeout: Optional[float] = None) -> Optional[ZenEvent]:
+        """Get next event from queue"""
+        try:
+            event = await asyncio.wait_for(self._event_queue.get(), timeout=timeout)
+            self._event_queue.task_done()
+            return event
+        except asyncio.TimeoutError:
+            return None
+    
+    async def get_events(self, count: int, timeout: Optional[float] = None) -> list[ZenEvent]:
+        """Get multiple events from queue"""
+        events = []
+        for _ in range(count):
+            event = await self.get_event(timeout)
+            if event is None:
+                break
+            events.append(event)
+        return events
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        # If not already started, start listening
+        if not self.transport or self.transport.is_closing():
+            await self.start_listening()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit"""
+        await self.stop_listening()
+
+    def _checksum(self, buf: bytes) -> int:
+        acc = 0
+        for b in buf:
+            acc ^= b
+        return acc & 0xFF

zencontrol/utils.py

@@ -0,0 +1,67 @@
+"""
+Utility functions for the ZenControl library
+"""
+import asyncio
+import signal
+import socket
+import sys
+from typing import Callable, Any
+
+
+def local_ip_for_remote(remote_host: str) -> str:
+    """Return the local IPv4 address used to reach ``remote_host``.
+
+    Uses a UDP ``connect`` (no packets sent) so the OS picks the correct
+    interface on multi-homed hosts, Docker, and macOS — unlike
+    ``socket.gethostname()``.
+    """
+    try:
+        remote_ip = socket.gethostbyname(remote_host)
+    except OSError:
+        remote_ip = remote_host
+
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.connect((remote_ip, 1))
+            return sock.getsockname()[0]
+    except OSError:
+        try:
+            return socket.gethostbyname(socket.gethostname())
+        except OSError:
+            return "127.0.0.1"
+
+
+def run_with_keyboard_interrupt(main_func: Callable[[], Any]) -> None:
+    """
+    Run an async main function with graceful KeyboardInterrupt handling.
+    
+    This function wraps asyncio.run() to catch KeyboardInterrupt (Ctrl+C) and
+    provide a clean shutdown experience.
+    
+    Args:
+        main_func: The async main function to run
+    """
+    try:
+        asyncio.run(main_func())
+    except KeyboardInterrupt:
+        print("\n🛑 Interrupted by user (Ctrl+C)")
+        print("Shutting down gracefully...")
+        sys.exit(0)
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+def setup_signal_handlers() -> None:
+    """
+    Set up signal handlers for graceful shutdown.
+    
+    This function sets up handlers for SIGINT (Ctrl+C) and SIGTERM to ensure
+    clean shutdown of async operations.
+    """
+    def signal_handler(signum, frame):
+        print(f"\n🛑 Received signal {signum}, shutting down gracefully...")
+        sys.exit(0)
+    
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)

zencontrol_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: zencontrol-python
+Version: 0.1.0
+Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
+Author: Simon Wright
+License-Expression: LGPL-2.1-only
+Project-URL: Homepage, https://github.com/sjwright/zencontrol-python
+Project-URL: Repository, https://github.com/sjwright/zencontrol-python
+Project-URL: Issues, https://github.com/sjwright/zencontrol-python/issues
+Keywords: dali,lighting,control,zencontrol,home-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt>=2.1.0; extra == "mqtt"
+Requires-Dist: PyYAML>=6.0; extra == "mqtt"
+Dynamic: license-file
+
+# zencontrol-python
+
+This is an implementation of the **Zencontrol TPI Advanced** protocol, written in Python. This library has been written with three levels of abstraction:
+
+- zencontrol.io: Implementation of the raw TPI Advanced UDP packet specification;
+- zencontrol.api: Implementation of most TPI Advanced API commands and events;
+- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables. This code is still undergoing significant refinement.
+
+Built on top of this is an example MQTT bridge for Home Assistant. See [examples/mqtt_bridge.md](examples/mqtt_bridge.md).
+
+## Requirements
+
+* Python 3.11 (or later)
+* Controller firmware 2.2.11 (or later)
+
+## Install
+
+Refer to zencontrol-tpi project for now.
+For integrators, the library is also published on PyPI.
+
+## Limitations
+
+Implemented but untested:
+  
+* Dealing with multiple controllers (I only have one controller)
+* RGB+ and XY colour commands (I don't have any compatible lights)
+* Numerical (absolute) instances (I don't have any such ECDs)
+* Event filtering (I haven't tested it)
+
+Not implemented:
+
+* Any commands involving DMX, Control4, or virtual instances (I don't have licenses for any of these so I couldn't test them even if I wanted to, but the scaffolding is there if anyone wishes to add support)
+* Any commands described in the documentation as "legacy" (they aren't useful)
+## TPI Advanced wishlist
+
+* Command to return a controller's MAC address used for multicast packets _(There are other ways to get or infer the MAC access, but they're unreliable.)_
+* Command to list active system variables _(As a workaround, you can query every number for its label. This assumes no system variables of interest are unlabelled.)_
+* Command to read an ambient light sensor's lux value. _(As a workaround, you can target a light sensor to a system variable. Not elegant but it works.)_
+* Event notification for ambient light sensor lux values. _(Same workaround as above.)_
+
+## Links
+
+* [About TPI Advanced](https://support.zencontrol.com/hc/en-us/articles/360000337175-What-is-the-Third-Party-Interface-TPI)

zencontrol_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+examples/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+examples/mqtt_bridge.py,sha256=IXgZJ6yNDKUHRL_u9PcFCV2wiibiY9RIBYzpid45OVs,50668
+zencontrol/__init__.py,sha256=51vS8pYDLePpZsXte9SlrKG1xm_PUFP-c0mJagFYLyA,2790
+zencontrol/exceptions.py,sha256=PKlMHWfivA3QEZOEqfm5lmt3VdNV2LtIA_Ognm4w1O8,578
+zencontrol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zencontrol/utils.py,sha256=jxi6sV4sugTjKMKRS_WKxNUMpK56TOXaoGhKv5pbeh0,1955
+zencontrol/api/__init__.py,sha256=ORN0VQ0ahYBSo4HsMRNTcFlu8-RMxibUh9Ta2jEeE8U,825
+zencontrol/api/models.py,sha256=fFZU6QoSd168ddhX_ofJyKGeDBYs4Na4ixzfQoixyQw,11218
+zencontrol/api/protocol.py,sha256=cnww4iyZbi0UJ93SJugyoQUj05R34SZ-MnnR0hYAfTE,94904
+zencontrol/api/types.py,sha256=FtD74rwTxhOpqHl2p6DaZdgIvdwrAQrc3A4x0OMGg94,6665
+zencontrol/interface/__init__.py,sha256=gw_-LSlEwUL0vrOYTxTBwPHZmuNsNqXRqVFbz1ZBQuA,662
+zencontrol/interface/interface.py,sha256=iwP40cOwGblj2uwvJbtlwuYYYh_52wrztQnRXLe85Bo,73086
+zencontrol/io/__init__.py,sha256=cBfOKr0BqOI8E2LicAwcDzLhdlz7KHHrtcn-iUzRmcU,570
+zencontrol/io/command.py,sha256=Zknc0xv71ezniC-RmCsdCGcuya2u0aWVCObtEsfKJQE,14827
+zencontrol/io/event.py,sha256=CT9pP6vHRnMFvJuCy8T9cwXkz5AsuHSbHzdmEvRegQE,11692
+zencontrol_python-0.1.0.dist-info/licenses/LICENSE,sha256=NLFVE3E6u6qdN0zN9mzIRM69zZaCv78QgUOh5Mp4ckk,26508
+zencontrol_python-0.1.0.dist-info/METADATA,sha256=50dOXDVxcrRLSbNkXM7XQ_-LF7N1LpsWO8xBHVntHyc,3773
+zencontrol_python-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+zencontrol_python-0.1.0.dist-info/entry_points.txt,sha256=bowyQt57_veMMZzF7LvDwDajG2HcY4-99qYHJ_hasw4,62
+zencontrol_python-0.1.0.dist-info/top_level.txt,sha256=cKZS8nB2cZlXavIXB_0tzE16PfGGw6WZDqNzemZKZ4w,20
+zencontrol_python-0.1.0.dist-info/RECORD,,

zencontrol_python-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
+

zencontrol_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zencontrol-mqtt = examples.mqtt_bridge:main