zencontrol-python 0.1.3__py3-none-any.whl → 0.1.6__py3-none-any.whl

zencontrol/__init__.py

@@ -40,6 +40,7 @@ from .interface import (
     ZenLight,
     ZenGroup,
     ZenButton,
+    ZenAbsoluteInput,
     ZenMotionSensor,
     ZenSystemVariable,
 )
@@ -58,7 +59,7 @@ from .exceptions import ZenError, ZenTimeoutError, ZenResponseError, ZenConnecti
 # Utilities
 from .utils import run_with_keyboard_interrupt
 
-__version__ = "0.1.3"
+__version__ = "0.1.6"
 __author__ = "Simon Wright"
 
 # Public API - these are the main classes users should import
@@ -72,6 +73,7 @@ __all__ = [
     "ZenLight",
     "ZenGroup",
     "ZenButton",
+    "ZenAbsoluteInput",
     "ZenMotionSensor",
     "ZenSystemVariable",
     

zencontrol/api/protocol.py

@@ -57,6 +57,7 @@ class ZenCallbacks:
         self.light_change: Callable[..., Awaitable[None]] | None = None
         self.button_press: Callable[..., Awaitable[None]] | None = None
         self.button_long_press: Callable[..., Awaitable[None]] | None = None
+        self.absolute_input_change: Callable[..., Awaitable[None]] | None = None
         self.motion_event: Callable[..., Awaitable[None]] | None = None
         self.system_variable_change: Callable[..., Awaitable[None]] | None = None
         self.controller_discovered: Callable[[DiscoveredController], Awaitable[None]] | None = None
@@ -75,6 +76,7 @@ class EntityRegistry:
         self.lights: dict[str, Any] = {}
         self.groups: dict[str, Any] = {}
         self.buttons: dict[str, Any] = {}
+        self.absolute_inputs: dict[str, Any] = {}
         self.motion_sensors: dict[str, Any] = {}
         self.system_variables: dict[str, Any] = {}
 
@@ -84,9 +86,26 @@ class EntityRegistry:
         self.lights.clear()
         self.groups.clear()
         self.buttons.clear()
+        self.absolute_inputs.clear()
         self.motion_sensors.clear()
         self.system_variables.clear()
 
+    def purge_controller(self, controller_name: str) -> None:
+        """Drop cached entities that belong to ``controller_name``."""
+        self.controllers.pop(controller_name, None)
+        prefix = f"{controller_name} "
+        for store in (
+            self.profiles,
+            self.lights,
+            self.groups,
+            self.buttons,
+            self.absolute_inputs,
+            self.motion_sensors,
+            self.system_variables,
+        ):
+            for key in [k for k in store if k == controller_name or k.startswith(prefix)]:
+                store.pop(key, None)
+
 
 class ZenProtocol:
 
@@ -260,6 +279,10 @@ class ZenProtocol:
         """Drop all interface entity singletons owned by this protocol."""
         self.entity_registry.clear()
 
+    def purge_controller_entities(self, controller_name: str) -> None:
+        """Drop interface-layer singletons for one controller."""
+        self.entity_registry.purge_controller(controller_name)
+
     def track_task(self, coro: Coroutine[Any, Any, Any]) -> asyncio.Task[Any]:
         """Schedule a background task and track it for cancellation on aclose."""
         task = asyncio.create_task(coro)
@@ -854,7 +877,7 @@ class ZenProtocol:
         min_payload = {
             ZenEventCode.BUTTON_PRESS: 1,
             ZenEventCode.BUTTON_HOLD: 1,
-            ZenEventCode.ABSOLUTE_INPUT: 1,
+            ZenEventCode.ABSOLUTE_INPUT: 3,
             ZenEventCode.LEVEL_CHANGE: 1,
             ZenEventCode.LEVEL_CHANGE_V2: 2,
             ZenEventCode.GROUP_LEVEL_CHANGE: 1,
@@ -902,10 +925,10 @@ class ZenProtocol:
                     await self.button_hold_callback(instance=instance, payload=payload)
 
             case ZenEventCode.ABSOLUTE_INPUT:
+                value = (payload[1] << 8) | payload[2]
                 if self.print_traffic: 
                     print(Fore.MAGENTA + f"{typecast.upper()} {ip_address}:" +
-                        Fore.CYAN + f" Absolute {target-64}" +
-                        Style.DIM + f" [{' '.join(f'0x{b:02X}' for b in payload)}]" +
+                        Fore.CYAN + f" Absolute {target-64}.{payload[0]} = {value}" +
                         Style.RESET_ALL)
                 if self.absolute_input_callback:
                     address = self._ecd_address_from_target(controller, target)

zencontrol/api/types.py

@@ -203,3 +203,7 @@ class Const:
     RECONNECT_MIN_DELAY = 1.0
     RECONNECT_MAX_DELAY = 30.0
     RECONNECT_HEALTHY_SECONDS = 60.0
+    
+    # Periodic emit-state check — controllers that reboot while our listener
+    # stays up lose TPI event config until we re-assert it.
+    EVENT_KEEPALIVE_INTERVAL = 30.0

zencontrol/interface/__init__.py

@@ -14,6 +14,7 @@ from .interface import (
     ZenLight,
     ZenGroup,
     ZenButton,
+    ZenAbsoluteInput,
     ZenMotionSensor,
     ZenSystemVariable,
 )
@@ -28,6 +29,7 @@ __all__ = [
     "ZenLight",
     "ZenGroup",
     "ZenButton",
+    "ZenAbsoluteInput",
     "ZenMotionSensor",
     "ZenSystemVariable",
 ]

zencontrol/interface/interface.py

@@ -4,13 +4,13 @@ import asyncio
 import json
 import time
 import logging
-from typing import Any, cast, Self
+from typing import Any, Literal, cast, Self
 from collections.abc import Coroutine, Callable, Awaitable
 
 from ..api import ZenProtocol, ZenController as SuperZenController, ZenAddress, ZenInstance, ZenAddressType, ZenColour, ZenColourType, ZenInstanceType
 from ..api.models import DiscoveredController
 from ..api.protocol import ZenCallbacks
-from ..api.types import Const
+from ..api.types import Const, ZenEventMode
 from ..exceptions import ZenConnectionError
 
 """
@@ -140,10 +140,13 @@ class ZenControl:
         self.protocol.callbacks = ZenCallbacks()
         self._stopping = False
         self._supervisor_task: asyncio.Task[None] | None = None
+        self._keepalive_task: asyncio.Task[None] | None = None
         self._first_connected = asyncio.Event()
+        self._controller_status_change: CallbackControllerStatusChange | None = None
         self.reconnect_min_delay = Const.RECONNECT_MIN_DELAY
         self.reconnect_max_delay = Const.RECONNECT_MAX_DELAY
         self.reconnect_healthy_seconds = Const.RECONNECT_HEALTHY_SECONDS
+        self.event_keepalive_interval = Const.EVENT_KEEPALIVE_INTERVAL
 
     async def __aenter__(self) -> Self:
         return self
@@ -207,7 +210,14 @@ class ZenControl:
     @button_long_press.setter
     def button_long_press(self, func: CallbackButtonLongPress | None) -> None:
         self.protocol.callbacks.button_long_press = func
-    
+
+    @property
+    def absolute_input_change(self) -> CallbackAbsoluteInputChange | None:
+        return self.protocol.callbacks.absolute_input_change
+    @absolute_input_change.setter
+    def absolute_input_change(self, func: CallbackAbsoluteInputChange | None) -> None:
+        self.protocol.callbacks.absolute_input_change = func
+
     @property
     def motion_event(self) -> CallbackMotionEvent | None:
         return self.protocol.callbacks.motion_event
@@ -229,6 +239,15 @@ class ZenControl:
     def controller_discovered(self, func: CallbackControllerDiscovered | None) -> None:
         self.protocol.callbacks.controller_discovered = func
 
+    @property
+    def controller_status_change(self) -> CallbackControllerStatusChange | None:
+        return self._controller_status_change
+    @controller_status_change.setter
+    def controller_status_change(
+        self, func: CallbackControllerStatusChange | None
+    ) -> None:
+        self._controller_status_change = func
+
     @property
     def discovered_controllers(self) -> list[DiscoveredController]:
         """Controllers identified from multicast but not yet registered."""
@@ -245,6 +264,137 @@ class ZenControl:
         self.protocol.set_controllers(cast(list[SuperZenController], self.controllers))
         return controller
 
+    async def remove_controller(self, controller: ZenController | str) -> None:
+        """Detach a controller and close its command client.
+
+        Safe to call while event monitoring is running. Does not stop the shared
+        listener; callers that own the last controller should ``aclose()``.
+        """
+        name = controller if isinstance(controller, str) else controller.name
+        removed = [c for c in self.controllers if c.name == name]
+        self.controllers = [c for c in self.controllers if c.name != name]
+        self.protocol.set_controllers(cast(list[SuperZenController], self.controllers))
+        self.protocol.purge_controller_entities(name)
+        for ctrl in removed:
+            client = ctrl.client
+            ctrl.client = None
+            if client is None:
+                continue
+            try:
+                await client.close()
+            except Exception:
+                pass
+
+    async def configure_controller_events(self, controller: ZenController) -> bool:
+        """Enable TPI event emit for one controller using this client's listen mode.
+
+        Call after ``add_controller`` when event monitoring is already running so a
+        newly attached controller joins the shared listener. Returns True when the
+        emit-enable command succeeds.
+        """
+        if self.protocol.event_listener is None:
+            return False
+        unicast = self.protocol.unicast
+        await self.protocol.set_tpi_event_unicast_address(
+            controller,
+            ipaddr=self.protocol.local_ip if unicast else None,
+            port=self.protocol.listen_port if unicast else None,
+        )
+        return bool(
+            await self.protocol.tpi_event_emit(
+                controller,
+                ZenEventMode(
+                    enabled=True,
+                    filtering=controller.filtering,
+                    unicast=unicast,
+                    multicast=not unicast,
+                ),
+            )
+        )
+
+    async def assert_controller_events(self, controller: ZenController) -> bool:
+        """Ping event emit state and re-assert config if the controller lost it.
+
+        Controllers that reboot while our listener stays up typically come back
+        with events disabled (or with a stale unicast target). Returns True when
+        the controller is reachable and events are confirmed/enabled, False when
+        the ping timed out / failed or re-assert could not enable emit.
+
+        Never re-asserts while ``is_controller_ready()`` is false — the startup
+        sequence can take several minutes after a reboot.
+        """
+        if self.protocol.event_listener is None:
+            return False
+
+        ready = await controller.is_controller_ready()
+        if ready is None:
+            self.logger.debug(
+                "No response from %s during event keepalive ping",
+                controller.name,
+            )
+            await self._notify_controller_status(controller, "unreachable")
+            return False
+        if ready is not True:
+            self.logger.debug(
+                "Controller %s still starting — deferring event re-assert",
+                controller.name,
+            )
+            await self._notify_controller_status(controller, "starting")
+            return True
+
+        unicast = self.protocol.unicast
+        needs_reassert = False
+        info = await self.protocol.query_tpi_event_unicast_address(controller)
+        if info is not None:
+            mode = info["mode"]
+            if not mode.enabled or bool(mode.unicast) != unicast:
+                needs_reassert = True
+            elif unicast and (
+                info.get("port") != self.protocol.listen_port
+                or info.get("ip") != self.protocol.local_ip
+            ):
+                needs_reassert = True
+        else:
+            enabled = await self.protocol.query_tpi_event_emit_state(controller)
+            if enabled is None:
+                self.logger.debug(
+                    "No response from %s during event keepalive ping",
+                    controller.name,
+                )
+                await self._notify_controller_status(controller, "unreachable")
+                return False
+            needs_reassert = not enabled
+
+        if needs_reassert:
+            self.logger.info(
+                "Controller %s TPI events not correctly enabled — re-asserting",
+                controller.name,
+            )
+            if not await self.configure_controller_events(controller):
+                self.logger.warning(
+                    "Failed to re-assert TPI events for %s",
+                    controller.name,
+                )
+                await self._notify_controller_status(controller, "unreachable")
+                return False
+        await self._notify_controller_status(controller, "online")
+        return True
+
+    async def _notify_controller_status(
+        self, controller: ZenController, status: ControllerRuntimeStatus
+    ) -> None:
+        """Notify listeners of online / starting / unreachable."""
+        if not callable(self._controller_status_change):
+            return
+        try:
+            await self._controller_status_change(controller, status)
+        except Exception as err:
+            self.logger.debug(
+                "controller_status_change error for %s: %s",
+                controller.name,
+                err,
+            )
+
     async def discover(self, timeout: float = 5.0) -> list[DiscoveredController]:
         """Listen for multicast and return controllers identified within ``timeout`` seconds.
 
@@ -289,6 +439,8 @@ class ZenControl:
         )
         if self._supervisor_task is None or self._supervisor_task.done():
             self._supervisor_task = asyncio.create_task(self._event_monitor_supervisor())
+        if self._keepalive_task is None or self._keepalive_task.done():
+            self._keepalive_task = asyncio.create_task(self._event_keepalive_loop())
         try:
             await asyncio.wait_for(
                 self._first_connected.wait(),
@@ -306,7 +458,7 @@ class ZenControl:
         was_running = bool(
             self.protocol.event_task and not self.protocol.event_task.done()
         )
-        await self._cancel_supervisor()
+        await self._cancel_background_tasks()
         await self.protocol.stop_event_monitoring()
         if was_running:
             await self.protocol.notify_disconnect()
@@ -317,15 +469,19 @@ class ZenControl:
         was_running = bool(
             self.protocol.event_task and not self.protocol.event_task.done()
         )
-        await self._cancel_supervisor()
+        await self._cancel_background_tasks()
         await self.protocol.aclose()
         if was_running:
             await self.protocol.notify_disconnect()
         self.clear_entity_caches()
 
-    async def _cancel_supervisor(self) -> None:
-        task = self._supervisor_task
-        self._supervisor_task = None
+    async def _cancel_background_tasks(self) -> None:
+        await self._cancel_task("_supervisor_task")
+        await self._cancel_task("_keepalive_task")
+
+    async def _cancel_task(self, attr: str) -> None:
+        task: asyncio.Task[None] | None = getattr(self, attr)
+        setattr(self, attr, None)
         if task is None or task.done():
             return
         task.cancel()
@@ -403,6 +559,33 @@ class ZenControl:
             except Exception:
                 pass
 
+    async def _event_keepalive_loop(self) -> None:
+        """Periodically ping controllers and re-enable TPI events if needed."""
+        try:
+            await self._first_connected.wait()
+        except asyncio.CancelledError:
+            raise
+        while not self._stopping:
+            try:
+                await asyncio.sleep(self.event_keepalive_interval)
+            except asyncio.CancelledError:
+                raise
+            if self._stopping or self.protocol.event_listener is None:
+                continue
+            for controller in list(self.controllers):
+                if self._stopping:
+                    return
+                try:
+                    await self.assert_controller_events(controller)
+                except asyncio.CancelledError:
+                    raise
+                except Exception as err:
+                    self.logger.debug(
+                        "Event keepalive failed for %s: %s",
+                        controller.name,
+                        err,
+                    )
+
     async def _protocol_disconnect_event(self) -> None:
         """Forward protocol-level disconnect to the high-level on_disconnect hook."""
         if callable(self.protocol.callbacks.on_disconnect):
@@ -419,7 +602,9 @@ class ZenControl:
         await ZenButton(protocol=self.protocol, instance=instance)._event_received(held=True)
 
     async def absolute_input_event(self, instance: ZenInstance, payload: bytes) -> None:
-        pass
+        await ZenAbsoluteInput(protocol=self.protocol, instance=instance)._event_received(
+            payload
+        )
 
     async def is_occupied_event(self, instance: ZenInstance, payload: bytes) -> None:
         await ZenMotionSensor(protocol=self.protocol, instance=instance)._event_received()
@@ -500,21 +685,23 @@ class ZenControl:
                 profiles.add(profile)
         return profiles
 
-    async def get_groups(self) -> set[ZenGroup]:
-        """Return a set of all groups."""
+    async def get_groups(self, controller: ZenController | None = None) -> set[ZenGroup]:
+        """Return a set of all groups (optionally for one controller)."""
         groups: set[ZenGroup] = set()
-        for controller in self.controllers:
-            addresses = await self.protocol.query_group_numbers(controller=controller)
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            addresses = await self.protocol.query_group_numbers(controller=ctrl)
             for address in addresses:
                 group = await ZenGroup.create(protocol=self.protocol, address=address)
                 groups.add(group)
         return groups
     
-    async def get_lights(self) -> set[ZenLight]:
-        """Return a set of all lights available."""
+    async def get_lights(self, controller: ZenController | None = None) -> set[ZenLight]:
+        """Return a set of all lights available (optionally for one controller)."""
         lights: set[ZenLight] = set()
-        for controller in self.controllers:
-            addresses = await self.protocol.query_control_gear_dali_addresses(controller=controller)
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            addresses = await self.protocol.query_control_gear_dali_addresses(controller=ctrl)
             for address in addresses:
                 light = await ZenLight.create(protocol=self.protocol, address=address)
                 lights.add(light)
@@ -542,11 +729,12 @@ class ZenControl:
                     addresses.append(addr)
         return addresses
 
-    async def get_buttons(self) -> set[ZenButton]:
-        """Return a set of all buttons available."""
+    async def get_buttons(self, controller: ZenController | None = None) -> set[ZenButton]:
+        """Return a set of all buttons available (optionally for one controller)."""
         buttons: set[ZenButton] = set()
-        for controller in self.controllers:
-            addresses = await self._get_addresses_with_instances(controller)
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            addresses = await self._get_addresses_with_instances(ctrl)
             for address in addresses:
                 instances = await self.protocol.query_instances_by_address(address=address)
                 for instance in instances:
@@ -555,11 +743,12 @@ class ZenControl:
                         buttons.add(button)
         return buttons
     
-    async def get_motion_sensors(self) -> set[ZenMotionSensor]:
-        """Return a set of all motion sensors available."""
+    async def get_motion_sensors(self, controller: ZenController | None = None) -> set[ZenMotionSensor]:
+        """Return a set of all motion sensors available (optionally for one controller)."""
         motion_sensors: set[ZenMotionSensor] = set()
-        for controller in self.controllers:
-            addresses = await self._get_addresses_with_instances(controller)
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            addresses = await self._get_addresses_with_instances(ctrl)
             for address in addresses:
                 instances = await self.protocol.query_instances_by_address(address=address)
                 for instance in instances:
@@ -568,16 +757,39 @@ class ZenControl:
                         motion_sensors.add(motion_sensor)
         return motion_sensors
 
-    async def get_system_variables(self, give_up_after: int = 10) -> set[ZenSystemVariable]:
-        """Return a set of all system variables. Variables must have a label. Searching will give_up_after [x] sequential IDs without a label."""
+    async def get_absolute_inputs(
+        self, controller: ZenController | None = None
+    ) -> set[ZenAbsoluteInput]:
+        """Return absolute (numerical) ECD instances (optionally for one controller)."""
+        absolute_inputs: set[ZenAbsoluteInput] = set()
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            addresses = await self._get_addresses_with_instances(ctrl)
+            for address in addresses:
+                instances = await self.protocol.query_instances_by_address(address=address)
+                for instance in instances:
+                    if instance.type == ZenInstanceType.ABSOLUTE_INPUT:
+                        absolute_input = await ZenAbsoluteInput.create(
+                            protocol=self.protocol, instance=instance
+                        )
+                        absolute_inputs.add(absolute_input)
+        return absolute_inputs
+
+    async def get_system_variables(
+        self,
+        give_up_after: int = 10,
+        controller: ZenController | None = None,
+    ) -> set[ZenSystemVariable]:
+        """Return labelled system variables (optionally for one controller)."""
         sysvars: set[ZenSystemVariable] = set()
-        failed_attempts = 0
-        for controller in self.controllers:
+        controllers = [controller] if controller else self.controllers
+        for ctrl in controllers:
+            failed_attempts = 0
             for variable in range(Const.MAX_SYSVAR):
-                label = await self.protocol.query_system_variable_name(controller=controller, variable=variable)
+                label = await self.protocol.query_system_variable_name(controller=ctrl, variable=variable)
                 if label:
                     failed_attempts = 0
-                    sysvar = await ZenSystemVariable.create(protocol=self.protocol, controller=controller, id=variable, label=label)
+                    sysvar = await ZenSystemVariable.create(protocol=self.protocol, controller=ctrl, id=variable, label=label)
                     sysvars.add(sysvar)
                 else:
                     failed_attempts += 1
@@ -600,6 +812,7 @@ class ZenController(SuperZenController):
     lights: set[ZenLight] = set()
     groups: set[ZenGroup] = set()
     buttons: set[ZenButton] = set()
+    absolute_inputs: set[ZenAbsoluteInput] = set()
     motion_sensors: set[ZenMotionSensor] = set()
     sysvars: set[ZenSystemVariable] = set()
     client_data: dict[str, Any] = {}
@@ -662,6 +875,7 @@ class ZenController(SuperZenController):
         self.lights = set()
         self.groups = set()
         self.buttons = set()
+        self.absolute_inputs = set()
         self.motion_sensors = set()
         self.sysvars = set()
         self.client_data = {}
@@ -785,6 +999,7 @@ class ZenLight:
         "RGB": False,
         "RGBW": False,
         "RGBWW": False,
+        "XY": False,
     }
     properties: dict[str, int | None] = {
         "min_kelvin": Const.DEFAULT_WARMEST_TEMP,
@@ -840,6 +1055,7 @@ class ZenLight:
             "RGB": False,
             "RGBW": False,
             "RGBWW": False,
+            "XY": False,
         }
         self.properties = {
             "min_kelvin": Const.DEFAULT_WARMEST_TEMP,
@@ -909,6 +1125,10 @@ class ZenLight:
             # If cgtype contains 8, it supports some kind of colour
             if 8 in self.cgtype:
                 cgtype = await self.protocol.query_dali_colour_features(self.address)
+                # XY is independent of TC/RGBWAF; a fixture may support more than one.
+                if cgtype and cgtype.get("supports_xy", False) is True:
+                    self.features["brightness"] = True
+                    self.features["XY"] = True
                 if cgtype and cgtype.get("supports_tunable", False) is True:
                     self.features["brightness"] = True
                     self.features["temperature"] = True
@@ -952,7 +1172,13 @@ class ZenLight:
         refreshed_scene = None
         if await self.protocol.dali_query_last_scene_is_current(self.address):
             refreshed_scene = await self.protocol.dali_query_last_scene(self.address)
-        if self.features["temperature"] or self.features["RGB"] or self.features["RGBW"] or self.features["RGBWW"]:
+        if (
+            self.features.get("temperature")
+            or self.features.get("RGB")
+            or self.features.get("RGBW")
+            or self.features.get("RGBWW")
+            or self.features.get("XY")
+        ):
             refreshed_colour = await self.protocol.query_dali_colour(self.address)
         
         if verifying:
@@ -1090,10 +1316,11 @@ class ZenLight:
             colour_type = colour
         else:
             return False;
-        if (colour_type == ZenColourType.TC and self.features["temperature"]) or \
-            (colour_type == ZenColourType.RGBWAF and self.features["RGB"]) or \
-            (colour_type == ZenColourType.RGBWAF and self.features["RGBW"]) or \
-            (colour_type == ZenColourType.RGBWAF and self.features["RGBWW"]):
+        if (colour_type == ZenColourType.TC and self.features.get("temperature")) or \
+            (colour_type == ZenColourType.RGBWAF and self.features.get("RGB")) or \
+            (colour_type == ZenColourType.RGBWAF and self.features.get("RGBW")) or \
+            (colour_type == ZenColourType.RGBWAF and self.features.get("RGBWW")) or \
+            (colour_type == ZenColourType.XY and self.features.get("XY")):
             return True
         return False
     # -----------------------------------------------------------------------------------------
@@ -1349,6 +1576,110 @@ class ZenButton:
                     await self.protocol.callbacks.button_long_press(button=self)
 
 
+class ZenAbsoluteInput:
+    """DALI ECD absolute (numerical) input instance — dials, sliders, etc.
+
+    Controllers emit value-change events only; TPI has no query/set command for
+    the current value, so ``value`` stays ``None`` until the first event.
+    Payload matches ``_protocol.txt``: ``[instance, value_hi, value_lo]``.
+    """
+
+    protocol: ZenProtocol
+    instance: ZenInstance
+    serial: (int | str) | None = None
+    label: str | None = None
+    instance_label: str | None = None
+    _value: int | None = None
+    client_data: dict[str, Any] = {}
+
+    def __new__(cls, protocol: ZenProtocol, instance: ZenInstance) -> ZenAbsoluteInput:
+        compound_id = f"{instance.address.controller.name} {instance.address.number} {instance.number}"
+        registry = protocol.entity_registry.absolute_inputs
+        if compound_id not in registry:
+            inst = super().__new__(cls)
+            registry[compound_id] = inst
+            inst.protocol = protocol
+            inst.instance = instance
+            inst._reset()
+        return registry[compound_id]
+
+    def __init__(self, protocol: ZenProtocol, instance: ZenInstance) -> None:
+        self.protocol = protocol
+        self.instance = instance
+
+    @classmethod
+    async def create(cls, protocol: ZenProtocol, instance: ZenInstance) -> ZenAbsoluteInput:
+        """Async factory method for ZenAbsoluteInput."""
+        absolute_input = cls(protocol, instance)
+        await absolute_input.interview()
+        return absolute_input
+
+    def __repr__(self) -> str:
+        return (
+            f"ZenAbsoluteInput<{self.instance.address.controller.name} "
+            f"ecd {self.instance.address.number} inst {self.instance.number}: "
+            f"{self.label} / {self.instance_label}>"
+        )
+
+    def _reset(self) -> None:
+        self.serial = None
+        self.label = None
+        self.instance_label = None
+        self._value = None
+        self.client_data = {}
+
+    def interview_serialize(self) -> str:
+        return json.dumps({
+            "serial": self.serial,
+            "label": self.label,
+            "instance_label": self.instance_label,
+        })
+
+    def interview_hydrate(self, data: str | dict[str, Any]) -> bool:
+        try:
+            data = _loads_interview_data(data)
+            self.serial = data.get("serial")
+            self.label = data.get("label")
+            self.instance_label = data.get("instance_label")
+            self.instance.address.label = self.label
+            self.instance.address.serial = cast(str | None, self.serial)
+            cast(ZenController, self.instance.address.controller).absolute_inputs.add(self)
+            return True
+        except Exception:
+            return False
+
+    async def interview(self) -> bool:
+        inst = self.instance
+        addr = inst.address
+        ctrl = cast(ZenController, addr.controller)
+        if addr.label is None:
+            addr.label = await self.protocol.query_dali_device_label(addr, generic_if_none=True)
+        if addr.serial is None:
+            addr.serial = cast(str | None, await self.protocol.query_dali_serial(addr))
+        self.label = addr.label
+        self.serial = addr.serial
+        self.instance_label = await self.protocol.query_dali_instance_label(
+            inst, generic_if_none=True
+        )
+        ctrl.absolute_inputs.add(self)
+        return True
+
+    @property
+    def value(self) -> int | None:
+        """Last-known 16-bit value from an absolute-input event, or None."""
+        return self._value
+
+    async def _event_received(self, payload: bytes) -> None:
+        if len(payload) < 3:
+            return
+        new_value = (payload[1] << 8) | payload[2]
+        changed = new_value != self._value
+        self._value = new_value
+        if changed and callable(self.protocol.callbacks.absolute_input_change):
+            await self.protocol.callbacks.absolute_input_change(
+                absolute_input=self, value=new_value
+            )
+
 
 class ZenMotionSensor:
     protocol: ZenProtocol
@@ -1625,6 +1956,7 @@ class ZenSystemVariable:
 
 
 # Callback type definitions (moved here after class definitions)
+type ControllerRuntimeStatus = Literal["online", "starting", "unreachable"]
 type CallbackOnConnect = Callable[[], Awaitable[None]]
 type CallbackOnDisconnect = Callable[[], Awaitable[None]]
 type CallbackProfileChange = Callable[[ZenProfile], Awaitable[None]]
@@ -1632,6 +1964,10 @@ type CallbackGroupChange = Callable[[ZenGroup, int], Awaitable[None]]
 type CallbackLightChange = Callable[[ZenLight, int, ZenColour, int], Awaitable[None]]
 type CallbackButtonPress = Callable[[ZenButton], Awaitable[None]]
 type CallbackButtonLongPress = Callable[[ZenButton], Awaitable[None]]
+type CallbackAbsoluteInputChange = Callable[[ZenAbsoluteInput, int], Awaitable[None]]
 type CallbackMotionEvent = Callable[[ZenMotionSensor, bool], Awaitable[None]]
 type CallbackSystemVariableChange = Callable[[ZenSystemVariable, int, bool, bool], Awaitable[None]]
 type CallbackControllerDiscovered = Callable[[DiscoveredController], Awaitable[None]]
+type CallbackControllerStatusChange = Callable[
+    [ZenController, ControllerRuntimeStatus], Awaitable[None]
+]

{zencontrol_python-0.1.3.dist-info → zencontrol_python-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.3
+Version: 0.1.6
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
 License-Expression: MIT
@@ -44,6 +44,32 @@ This library has now undergone validation in multiple environments. There is an
 [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator), a nearly feature-complete simulator of zencontrol hardware.
 A practical demonstration is [zencontrol-homeassistant](https://github.com/sjwright/zencontrol-homeassistant), a comprehensive Home Assistant integration.
 
+## Features
+
+Beyond basic lighting control, this library supports:
+
+* **Broad command surface** — inhibit, custom fade, step/up/down helpers, colour scene membership queries, EAN/serial, and most related TPI Advanced commands
+* **Object-based entity model** — Optional. Expresses lights, groups, profiles, buttons, motion sensors, absolute inputs, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **Event keepalive** — periodic emit-state ping; re-enables TPI events (and unicast target) if a controller reboots while the listener stays up
+* **Multicast controller discovery** — find controllers on the LAN without a preconfigured host
+* **Button events** — discovery of control-device button instances, plus press and long-press event callbacks
+* **Absolute inputs** — discovery of numerical ECD instances (dials/sliders) with 16-bit value-change event callbacks
+* **Event filtering** — configure which TPI events the controller emits
+* **System variables** — labelled SV discovery, read/write, and change events
+* **Profiles** — query, change, and return to the scheduled profile
+* **Simulator-backed tests** — protocol path exercised against [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator)
+
+## Known limitations
+
+* RGB+ and XY colour commands have not been tested with hardware
+* Numerical (absolute) instances have not been tested with hardware
+
+## Out of scope
+
+* 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)
+
 ## Requirements
 
 * Python 3.14 (or later)
@@ -68,16 +94,6 @@ pytest -m "not simulator"
 pytest
 ```
 
-## Limitations
-
-* RGB+ and XY colour commands are not tested (I don't have any compatible lights)
-* Numerical (absolute) instances are not tested (I don't have any such ECDs)
-
-## Out of scope
-
-* 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.)_

{zencontrol_python-0.1.3.dist-info → zencontrol_python-0.1.6.dist-info}/RECORD

@@ -15,22 +15,22 @@ examples/live/multicast_raw.py,sha256=EFRM7xA-xlZFS_0WXkQmqECBITG41W4jUEmTd9sIA1
 examples/live/profiles.py,sha256=Z0jZg8EEznMzSH5JJhhgtJRA_dazNSkuDHnfLqxpR44,1323
 examples/live/tpi_event_listener.py,sha256=phWI7Ib_g_nMGcPMjIZY6ukBpQpp9YdI3l5lAseYSjA,9309
 examples/live/variables.py,sha256=hio4vefJLgvCvoVpxLTrU0kxzStWYn6artoJbGnVyd4,1554
-zencontrol/__init__.py,sha256=PHBe_JAOkTtbT9WbWTtzpXFURnOhJ60LNd6haH3MrVM,2938
+zencontrol/__init__.py,sha256=bS69eXmifqSmw6XCZ5ml534IIft07evyzioVHz4Y7x8,2984
 zencontrol/exceptions.py,sha256=tqaLDYWu5J-j2ZKFdfTOcXLH9vULi5pZn8o_Y86bHRE,862
 zencontrol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 zencontrol/utils.py,sha256=cipUc2KXUfrgTRbCyGwNLhk7um2tjAw6I7kpU_eOu44,2005
 zencontrol/api/__init__.py,sha256=kZd1T3IKziyQc9qAfOJdYeeTPaB4L2Wkhfu3FKmRw-I,875
 zencontrol/api/models.py,sha256=W3kCFiJSxc9Z_5Bzfx7A1iICLL8PRmMroW1WReEzAfs,12334
-zencontrol/api/protocol.py,sha256=HD3IEDNfTB_b5qpXgcIYh9j1N20ft_nQhuof8n-u0Q4,101518
-zencontrol/api/types.py,sha256=cJtKY4Qer8u0QQ8J9Jcumg1C1Dee5DtJ9JGcSEfhIKw,6862
-zencontrol/interface/__init__.py,sha256=gw_-LSlEwUL0vrOYTxTBwPHZmuNsNqXRqVFbz1ZBQuA,662
-zencontrol/interface/interface.py,sha256=d3pjWDRBEaHXUEWPEjrc0Bak9ApPljuAzV6BlIoVN3s,75318
+zencontrol/api/protocol.py,sha256=zBPCcuvBc6F51LtPbPfFBHzdUro0P1fdNAKprQ61fC8,102471
+zencontrol/api/types.py,sha256=DxCi4dI_iBF5bPo-YqzYnmxA9fbTwp-bsHbD1fOSnVE,7042
+zencontrol/interface/__init__.py,sha256=HNGCBYlJ5W2Pap4DmaQe0EI06j0ZWyy4PCW3HzLLJm8,708
+zencontrol/interface/interface.py,sha256=SVFjlPIyf3oiDtQmET0v0VVAWV1MD1RC-lEGUYbp-x4,89504
 zencontrol/io/__init__.py,sha256=cBfOKr0BqOI8E2LicAwcDzLhdlz7KHHrtcn-iUzRmcU,570
 zencontrol/io/command.py,sha256=HVyMgYGSm166adIIU4KRSIfzPnfB9gnmw3pia_nZ4U8,15366
 zencontrol/io/event.py,sha256=dsjxFCGNljZOMwFqez9aYKvK1WF2w55X7iwsX93mpvQ,12994
-zencontrol_python-0.1.3.dist-info/licenses/LICENSE,sha256=cxmGKzqqXAjXOOw0D0tt5pVkNU9HCormEhNR8dEAYc4,1069
-zencontrol_python-0.1.3.dist-info/METADATA,sha256=oX53gJt4VEeoIAx0dcjgCxoMdHDCnu5FFYdJG2C6No8,4379
-zencontrol_python-0.1.3.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-zencontrol_python-0.1.3.dist-info/entry_points.txt,sha256=bowyQt57_veMMZzF7LvDwDajG2HcY4-99qYHJ_hasw4,62
-zencontrol_python-0.1.3.dist-info/top_level.txt,sha256=cKZS8nB2cZlXavIXB_0tzE16PfGGw6WZDqNzemZKZ4w,20
-zencontrol_python-0.1.3.dist-info/RECORD,,
+zencontrol_python-0.1.6.dist-info/licenses/LICENSE,sha256=cxmGKzqqXAjXOOw0D0tt5pVkNU9HCormEhNR8dEAYc4,1069
+zencontrol_python-0.1.6.dist-info/METADATA,sha256=-SqcQjeXr4oeskshMZ5FGo1OEPwM_S6sW4xpd3gbgBM,5698
+zencontrol_python-0.1.6.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+zencontrol_python-0.1.6.dist-info/entry_points.txt,sha256=bowyQt57_veMMZzF7LvDwDajG2HcY4-99qYHJ_hasw4,62
+zencontrol_python-0.1.6.dist-info/top_level.txt,sha256=cKZS8nB2cZlXavIXB_0tzE16PfGGw6WZDqNzemZKZ4w,20
+zencontrol_python-0.1.6.dist-info/RECORD,,