zencontrol-python 0.1.3__tar.gz → 0.1.4__tar.gz

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.3
+Version: 0.1.4
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
 License-Expression: MIT
@@ -44,6 +44,30 @@ 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, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **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
+* **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 +92,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 → zencontrol_python-0.1.4}/README.md

@@ -10,6 +10,30 @@ 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, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **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
+* **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)
@@ -34,16 +58,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.4/examples/dump_simulator_config.py

@@ -0,0 +1,474 @@
+#!/usr/bin/env python3
+"""Dump a live Zencontrol controller into a zencontrol-simulator config.yaml.
+
+Read-only: queries labels, levels, colour, scenes, groups, ECDs/instances,
+profiles, and system variables. Does not send control commands.
+
+Example:
+  cd zencontrol-python
+  python examples/dump_simulator_config.py \\
+      -c examples/config.yaml \\
+      -o ../zencontrol-simulator/config.from-live.yaml
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from zencontrol import (
+    ZenColour,
+    ZenColourType,
+    ZenController,
+    ZenInstanceType,
+    ZenProtocol,
+    run_with_keyboard_interrupt,
+)
+from zencontrol.api.types import Const
+
+LOGGER = logging.getLogger("dump_simulator_config")
+
+INSTANCE_TYPE_NAMES = {
+    ZenInstanceType.PUSH_BUTTON: "push_button",
+    ZenInstanceType.ABSOLUTE_INPUT: "absolute_input",
+    ZenInstanceType.OCCUPANCY_SENSOR: "occupancy_sensor",
+    ZenInstanceType.LIGHT_SENSOR: "light_sensor",
+    ZenInstanceType.GENERAL_SENSOR: "general_sensor",
+}
+
+def _hex_int(value: int) -> str:
+    return f"0x{value:X}"
+
+def _colour_dict(colour: ZenColour | None) -> dict[str, Any] | None:
+    if colour is None or colour.type is None:
+        return None
+    if colour.type == ZenColourType.TC:
+        return {"type": "tc", "kelvin": colour.kelvin}
+    if colour.type == ZenColourType.RGBWAF:
+        return {
+            "type": "rgbwaf",
+            "r": colour.r,
+            "g": colour.g,
+            "b": colour.b,
+            "w": colour.w if colour.w is not None else 0,
+            "a": colour.a if colour.a is not None else 0,
+            "f": colour.f if colour.f is not None else 0,
+        }
+    if colour.type == ZenColourType.XY:
+        return {"type": "xy", "x": colour.x, "y": colour.y}
+    return None
+
+def _scene_levels(levels: list[int | None] | None) -> list[int | None]:
+    out: list[int | None] = [None] * 12
+    if not levels:
+        return out
+    for i, level in enumerate(levels[:12]):
+        out[i] = None if level is None else int(level)
+    return out
+
+def _scene_colours(colours: list[ZenColour | None] | None) -> list[dict[str, Any] | None]:
+    out: list[dict[str, Any] | None] = [None] * 12
+    if not colours:
+        return out
+    for i, colour in enumerate(colours[:12]):
+        out[i] = _colour_dict(colour)
+    return out
+
+async def _raw_byte(tpi: ZenProtocol, controller: ZenController, command: int, address: int = 0) -> int | None:
+    response = await tpi._send_basic(controller, command, address)
+    if response and len(response) >= 1:
+        return int(response[0])
+    return None
+
+async def dump_controller(tpi: ZenProtocol, controller: ZenController) -> dict[str, Any]:
+    LOGGER.info("Querying controller %s (%s:%s)", controller.mac, controller.host, controller.port)
+
+    version = await tpi.query_controller_version_number(controller)
+    version_parts = [2, 2, 0]
+    if isinstance(version, str):
+        try:
+            version_parts = [int(x) for x in version.split(".")[:3]]
+            while len(version_parts) < 3:
+                version_parts.append(0)
+        except ValueError:
+            pass
+    label = await tpi.query_controller_label(controller) or controller.label or "Controller"
+    startup = await tpi.query_controller_startup_complete(controller)
+    dali_ready = await tpi.query_is_dali_ready(controller)
+    event_mode = await _raw_byte(tpi, controller, tpi.CMD["QUERY_TPI_EVENT_EMIT_STATE"])
+
+    current_profile = await tpi.query_current_profile_number(controller)
+    last_scheduled = current_profile or 0
+    profile_info = await tpi.query_profile_information(controller)
+    if profile_info:
+        state, _profiles_detail = profile_info
+        current_profile = int(state.get("current_active_profile", current_profile or 0))
+        last_scheduled = int(state.get("last_scheduled_profile", last_scheduled))
+
+    profile_numbers = await tpi.query_profile_numbers(controller) or []
+    if current_profile is not None and current_profile not in profile_numbers:
+        profile_numbers = sorted(set(profile_numbers) | {current_profile})
+    profile_items = []
+    for number in sorted(profile_numbers):
+        plabel = await tpi.query_profile_label(controller, number)
+        profile_items.append({
+            "number": int(number),
+            "label": plabel or f"Profile {number}",
+        })
+        LOGGER.info("  profile %s: %s", number, plabel)
+
+    mac = controller.mac.replace("-", ":").lower()
+    world: dict[str, Any] = {
+        "controller": {
+            "bind_host": "0.0.0.0",
+            "bind_port": 5108,
+            "mac": mac,
+            "label": label,
+            "version": version_parts,
+            "startup_complete": bool(startup) if startup is not None else True,
+            "dali_ready": bool(dali_ready) if dali_ready is not None else True,
+            "event_mode": event_mode if event_mode is not None else 0x01,
+            # Dump is a static snapshot — disable occupancy heartbeat by default.
+            "heartbeat_interval": 0,
+        },
+        "lights": [],
+        "groups": [],
+        "devices": [],
+        "profiles": {
+            "current": int(current_profile or 0),
+            "last_scheduled": int(last_scheduled or 0),
+            "items": profile_items,
+        },
+        "system_variables": [],
+    }
+
+    # --- Groups (labels / scenes first so light membership can reference them) ---
+    group_addrs = await tpi.query_group_numbers(controller) or []
+    LOGGER.info("Groups: %d", len(group_addrs))
+    for gaddr in sorted(group_addrs, key=lambda a: a.number):
+        glabel = await tpi.query_group_label(gaddr)
+        glevel = await tpi.dali_query_level(gaddr)
+        scene_nums = await tpi.query_scene_numbers_for_group(gaddr) or []
+        scenes: dict[int, str] = {}
+        for scene in sorted(scene_nums):
+            if not 0 <= scene <= 11:
+                continue
+            slabel = await tpi.query_scene_label_for_group(gaddr, scene)
+            if slabel:
+                scenes[int(scene)] = slabel
+        world["groups"].append({
+            "number": int(gaddr.number),
+            "label": glabel or f"Group {gaddr.number}",
+            "level": 0 if glevel is None else int(glevel),
+            "scenes": scenes,
+        })
+        LOGGER.info("  group %s: %s (%d scenes)", gaddr.number, glabel, len(scenes))
+
+    # --- Control gear / lights ---
+    gears = await tpi.query_control_gear_dali_addresses(controller) or []
+    LOGGER.info("Control gear: %d", len(gears))
+    for addr in sorted(gears, key=lambda a: a.number):
+        status_raw = await _raw_byte(
+            tpi, controller, tpi.CMD["DALI_QUERY_CONTROL_GEAR_STATUS"], addr.ecg()
+        )
+        # Skip gear that does not answer status (absent / failed)
+        if status_raw is None:
+            LOGGER.warning("  ECG %s: no status — skipping", addr.number)
+            continue
+
+        dlabel = await tpi.query_dali_device_label(addr)
+        serial = await tpi.query_dali_serial(addr)
+        level = await tpi.dali_query_level(addr)
+        min_level = await tpi.dali_query_min_level(addr)
+        max_level = await tpi.dali_query_max_level(addr)
+        last_scene = await tpi.dali_query_last_scene(addr)
+        last_current = await tpi.dali_query_last_scene_is_current(addr)
+        cg_types = await tpi.dali_query_cg_type(addr) or []
+        groups = await tpi.query_group_membership_by_address(addr) or []
+        group_nums = sorted({int(g.number) for g in groups})
+
+        colour_features = {
+            "supports_xy": False,
+            "supports_tunable": False,
+            "primary_count": 0,
+            "rgbwaf_channels": 0,
+        }
+        colour = None
+        colour_temp_limits = None
+        if 8 in cg_types:
+            features = await tpi.query_dali_colour_features(addr)
+            if features:
+                colour_features = {
+                    "supports_xy": bool(features.get("supports_xy", False)),
+                    "supports_tunable": bool(features.get("supports_tunable", False)),
+                    "primary_count": int(features.get("primary_count", 0)),
+                    "rgbwaf_channels": int(features.get("rgbwaf_channels", 0)),
+                }
+            colour = _colour_dict(await tpi.query_dali_colour(addr))
+            if colour_features["supports_tunable"]:
+                colour_temp_limits = await tpi.query_dali_colour_temp_limits(addr)
+
+        scene_levels = _scene_levels(await tpi.query_scene_levels_by_address(addr))
+        scene_colours = _scene_colours(await tpi.query_scene_colours_by_address(addr))
+
+        light: dict[str, Any] = {
+            "address": int(addr.number),
+            "label": dlabel or f"Light {addr.number}",
+            "serial": _hex_int(int(serial)) if serial else 0,
+            "level": 0 if level is None else int(level),
+            "min_level": 1 if min_level is None else int(min_level),
+            "max_level": 254 if max_level is None else int(max_level),
+            "last_scene": 0 if last_scene is None else int(last_scene),
+            "last_scene_current": bool(last_current) if last_current is not None else False,
+            "cg_types": [int(x) for x in cg_types],
+            "colour": colour,
+            "colour_features": colour_features,
+            "groups": group_nums,
+            "scene_levels": scene_levels,
+            "status": status_raw,
+        }
+        if colour_temp_limits:
+            light["colour_temp_limits"] = {
+                "physical_warmest": int(colour_temp_limits["physical_warmest"]),
+                "physical_coolest": int(colour_temp_limits["physical_coolest"]),
+                "soft_warmest": int(colour_temp_limits["soft_warmest"]),
+                "soft_coolest": int(colour_temp_limits["soft_coolest"]),
+                "step_value": int(colour_temp_limits["step_value"]),
+            }
+        if any(c is not None for c in scene_colours):
+            light["scene_colours"] = scene_colours
+
+        world["lights"].append(light)
+        LOGGER.info(
+            "  ECG %s: %s level=%s groups=%s cg=%s",
+            addr.number,
+            dlabel,
+            light["level"],
+            group_nums,
+            cg_types,
+        )
+
+    # --- ECDs / instances ---
+    ecds = await tpi.query_dali_addresses_with_instances(controller, 0) or []
+    LOGGER.info("Devices with instances: %d", len(ecds))
+    for ecd in sorted(ecds, key=lambda a: a.number):
+        dlabel = await tpi.query_dali_device_label(ecd)
+        serial = await tpi.query_dali_serial(ecd)
+        instances = await tpi.query_instances_by_address(ecd) or []
+        inst_list: list[dict[str, Any]] = []
+        for inst in sorted(instances, key=lambda i: i.number):
+            if inst.type is None:
+                continue
+            type_name = INSTANCE_TYPE_NAMES.get(inst.type)
+            if type_name is None:
+                LOGGER.warning(
+                    "  ECD %s inst %s: unsupported type %s — skipped",
+                    ecd.number,
+                    inst.number,
+                    inst.type,
+                )
+                continue
+            ilabel = await tpi.query_dali_instance_label(inst)
+            entry: dict[str, Any] = {
+                "number": int(inst.number),
+                "type": type_name,
+                "label": ilabel or f"Instance {inst.number}",
+                "active": True,
+                "error": False,
+            }
+            if inst.type == ZenInstanceType.OCCUPANCY_SENSOR:
+                timers = await tpi.query_occupancy_instance_timers(inst)
+                if timers:
+                    entry["timers"] = {
+                        "deadtime": int(timers["deadtime"]),
+                        "hold": int(timers["hold"]),
+                        "report": int(timers["report"]),
+                        "last_detect": int(timers["last_detect"]),
+                    }
+                else:
+                    entry["timers"] = {
+                        "deadtime": 1,
+                        "hold": 60,
+                        "report": 20,
+                        "last_detect": 0,
+                    }
+            inst_list.append(entry)
+            LOGGER.info(
+                "  ECD %s.%s %s (%s)",
+                ecd.number,
+                inst.number,
+                type_name,
+                ilabel,
+            )
+        if not inst_list:
+            continue
+        world["devices"].append({
+            "address": int(ecd.number),
+            "label": dlabel or f"Device {ecd.number}",
+            "serial": _hex_int(int(serial)) if serial else 0,
+            "instances": inst_list,
+        })
+
+    # --- System variables (stop after consecutive unnamed IDs) ---
+    give_up_after = 10
+    failed = 0
+    LOGGER.info("System variables…")
+    for vid in range(Const.MAX_SYSVAR):
+        name = await tpi.query_system_variable_name(controller, vid)
+        if not name:
+            failed += 1
+            if failed >= give_up_after:
+                break
+            continue
+        failed = 0
+        value = await tpi.query_system_variable(controller, vid)
+        world["system_variables"].append({
+            "id": int(vid),
+            "name": name,
+            "value": 0 if value is None else int(value),
+        })
+        LOGGER.info("  sysvar %s: %s = %s", vid, name, value)
+
+    return world
+
+class _HexInt(int):
+    """YAML representable int that dumps as 0x…."""
+
+def _represent_hex_int(dumper: yaml.Dumper, data: _HexInt) -> Any:
+    return dumper.represent_scalar("tag:yaml.org,2002:int", f"0x{int(data):X}")
+
+def _prepare_for_yaml(obj: Any) -> Any:
+    """Convert serial hex strings back to ints tagged for hex dump where useful."""
+    if isinstance(obj, dict):
+        out = {}
+        for key, value in obj.items():
+            if key == "serial" and isinstance(value, str) and value.startswith("0x"):
+                out[key] = _HexInt(int(value, 0))
+            elif key == "event_mode" and isinstance(value, int):
+                out[key] = _HexInt(value)
+            elif key == "status" and isinstance(value, int):
+                out[key] = _HexInt(value)
+            else:
+                out[key] = _prepare_for_yaml(value)
+        return out
+    if isinstance(obj, list):
+        return [_prepare_for_yaml(x) for x in obj]
+    return obj
+
+def write_yaml(path: Path, world: dict[str, Any]) -> None:
+    class Dumper(yaml.SafeDumper):
+        pass
+
+    Dumper.add_representer(_HexInt, _represent_hex_int)
+    payload = _prepare_for_yaml(world)
+    header = (
+        "# Auto-generated by zencontrol-python/examples/dump_simulator_config.py\n"
+        "# Read-only snapshot of a live Zencontrol controller for zencontrol-simulator.\n"
+        "# Control commands mutate in-memory state only; nothing is written back to disk.\n\n"
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(header)
+        yaml.dump(
+            payload,
+            fh,
+            Dumper=Dumper,
+            sort_keys=False,
+            default_flow_style=False,
+            allow_unicode=True,
+            width=100,
+        )
+
+def build_parser() -> argparse.ArgumentParser:
+    example_dir = Path(__file__).resolve().parent
+    default_config = example_dir / "config.yaml"
+    default_out = example_dir.parents[1] / "zencontrol-simulator" / "config.from-live.yaml"
+    parser = argparse.ArgumentParser(
+        description="Dump a live Zencontrol controller to a zencontrol-simulator YAML world",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=default_config,
+        help=f"zencontrol-python config.yaml (default: {default_config})",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=default_out,
+        help=f"Output simulator config path (default: {default_out})",
+    )
+    parser.add_argument(
+        "--controller",
+        type=int,
+        default=0,
+        help="Index into zencontrol: list in config (default: 0)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Debug logging",
+    )
+    return parser
+
+async def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+    )
+
+    if not args.config.is_file():
+        LOGGER.error("Config not found: %s", args.config)
+        sys.exit(1)
+
+    with open(args.config, encoding="utf-8") as fh:
+        config = yaml.safe_load(fh) or {}
+    controllers = config.get("zencontrol") or []
+    if not controllers:
+        LOGGER.error("No zencontrol: entries in %s", args.config)
+        sys.exit(1)
+    if not 0 <= args.controller < len(controllers):
+        LOGGER.error("Controller index %s out of range (have %d)", args.controller, len(controllers))
+        sys.exit(1)
+
+    entry = dict(controllers[args.controller])
+    # ZenController / ZenProtocol do not need mqtt extras
+    for key in ("system_variables", "buttons", "unicast_ip", "unicast_port", "filtering"):
+        entry.pop(key, None)
+
+    async with ZenProtocol(print_traffic=False) as tpi:
+        # Coerce YAML types to what ZenController expects
+        entry["id"] = str(entry.get("id", "1"))
+        ctrl = ZenController(protocol=tpi, **entry)
+        tpi.set_controllers([ctrl])
+
+        ready = await tpi.query_controller_startup_complete(ctrl)
+        if ready is False:
+            LOGGER.warning("Controller reports startup incomplete — continuing anyway")
+        dali = await tpi.query_is_dali_ready(ctrl)
+        if dali is False:
+            LOGGER.warning("DALI bus not ready — continuing anyway")
+
+        world = await dump_controller(tpi, ctrl)
+
+    write_yaml(args.output, world)
+    LOGGER.info(
+        "Wrote %s (%d lights, %d groups, %d devices, %d profiles, %d sysvars)",
+        args.output,
+        len(world["lights"]),
+        len(world["groups"]),
+        len(world["devices"]),
+        len(world["profiles"]["items"]),
+        len(world["system_variables"]),
+    )
+
+if __name__ == "__main__":
+    run_with_keyboard_interrupt(main)

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/tests/test_lifecycle.py

@@ -11,7 +11,6 @@ from zencontrol.api.models import ZenAddress
 from zencontrol.api.types import ZenAddressType
 from zencontrol.interface.interface import (
     ZenControl,
-    ZenController,
     ZenLight,
 )
 
@@ -24,6 +23,34 @@ async def test_zencontrol_async_context_manager_calls_aclose() -> None:
         aclose.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_remove_controller_closes_client_and_purges_cache() -> None:
+    zen = ZenControl()
+    ctrl_a = zen.add_controller(
+        id=1, name="ctrl-a", label="A", host="127.0.0.1", port=5108
+    )
+    ctrl_b = zen.add_controller(
+        id=2, name="ctrl-b", label="B", host="127.0.0.2", port=5108
+    )
+    fake_client = MagicMock()
+    fake_client.close = AsyncMock()
+    ctrl_a.client = fake_client
+    address = ZenAddress(controller=ctrl_a, type=ZenAddressType.ECG, number=1)
+    ZenLight(protocol=zen.protocol, address=address)
+    assert "ctrl-a 1" in zen.protocol.entity_registry.lights
+
+    await zen.remove_controller(ctrl_a)
+
+    fake_client.close.assert_awaited()
+    assert ctrl_a.client is None
+    assert zen.controllers == [ctrl_b]
+    assert "ctrl-a" not in zen.protocol.entity_registry.controllers
+    assert "ctrl-a 1" not in zen.protocol.entity_registry.lights
+    assert "ctrl-b" in zen.protocol.entity_registry.controllers
+
+    await zen.aclose()
+
+
 @pytest.mark.asyncio
 async def test_aclose_closes_clients_and_clears_instances() -> None:
     zen = ZenControl()

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/zencontrol/__init__.py

@@ -58,7 +58,7 @@ from .exceptions import ZenError, ZenTimeoutError, ZenResponseError, ZenConnecti
 # Utilities
 from .utils import run_with_keyboard_interrupt
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 __author__ = "Simon Wright"
 
 # Public API - these are the main classes users should import

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/zencontrol/api/protocol.py

@@ -87,6 +87,21 @@ class EntityRegistry:
         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.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 +275,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)

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/zencontrol/interface/interface.py

@@ -10,7 +10,7 @@ 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
 
 """
@@ -245,6 +245,51 @@ 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) -> None:
+        """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.
+        """
+        if self.protocol.event_listener is None:
+            return
+        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,
+        )
+        await self.protocol.tpi_event_emit(
+            controller,
+            ZenEventMode(
+                enabled=True,
+                filtering=controller.filtering,
+                unicast=unicast,
+                multicast=not unicast,
+            ),
+        )
+
     async def discover(self, timeout: float = 5.0) -> list[DiscoveredController]:
         """Listen for multicast and return controllers identified within ``timeout`` seconds.
 
@@ -500,21 +545,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 +589,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 +603,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 +617,21 @@ 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_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

{zencontrol_python-0.1.3 → zencontrol_python-0.1.4}/zencontrol_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.3
+Version: 0.1.4
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
 License-Expression: MIT
@@ -44,6 +44,30 @@ 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, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **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
+* **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 +92,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 → zencontrol_python-0.1.4}/zencontrol_python.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 examples/__init__.py
+examples/dump_simulator_config.py
 examples/mqtt_bridge.py
 examples/live/controller.py
 examples/live/devices.py