zencontrol-python 0.1.0__tar.gz → 0.1.2__tar.gz

zencontrol_python-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Wright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{zencontrol_python-0.1.0 → zencontrol_python-0.1.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
-License-Expression: LGPL-2.1-only
+License-Expression: MIT
 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
@@ -40,33 +40,46 @@ This is an implementation of the **Zencontrol TPI Advanced** protocol, written i
 
 - 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.
+- 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.
 
-Built on top of this is an example MQTT bridge for Home Assistant. See [examples/mqtt_bridge.md](examples/mqtt_bridge.md).
+This library has now undergone validation in multiple environments. There is an extensive test suite, some of which uses
+[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.
 
 ## Requirements
 
 * Python 3.11 (or later)
-* Controller firmware 2.2.11 (or later)
+* Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
 
-Refer to zencontrol-tpi project for now.
-For integrators, the library is also published on PyPI.
+This library is available on PyPI.
+
+## Testing
+
+Integration tests start [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator) on an ephemeral local port and exercise a real UDP TPI protocol path. Either install the simulator, or check it out as a sibling directory (`../zencontrol-simulator`); tests will pick it up automatically. Note that PyYAML is a simulator dependency.
+
+```bash
+pip install -e ".[dev]"
+pip install PyYAML
+# optional if not using a sibling checkout:
+# pip install -e ../zencontrol-simulator
+pytest -m simulator
+pytest -m "not simulator"
+# or run everything:
+pytest
+```
 
 ## 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)
+* 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)
 
-Not implemented:
+## 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.)_
@@ -74,6 +87,10 @@ Not implemented:
 * 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.)_
 
+## License
+
+[MIT](LICENSE)
+
 ## 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 → zencontrol_python-0.1.2}/README.md

@@ -4,33 +4,46 @@ This is an implementation of the **Zencontrol TPI Advanced** protocol, written i
 
 - 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.
+- 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.
 
-Built on top of this is an example MQTT bridge for Home Assistant. See [examples/mqtt_bridge.md](examples/mqtt_bridge.md).
+This library has now undergone validation in multiple environments. There is an extensive test suite, some of which uses
+[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.
 
 ## Requirements
 
 * Python 3.11 (or later)
-* Controller firmware 2.2.11 (or later)
+* Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
 
-Refer to zencontrol-tpi project for now.
-For integrators, the library is also published on PyPI.
+This library is available on PyPI.
+
+## Testing
+
+Integration tests start [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator) on an ephemeral local port and exercise a real UDP TPI protocol path. Either install the simulator, or check it out as a sibling directory (`../zencontrol-simulator`); tests will pick it up automatically. Note that PyYAML is a simulator dependency.
+
+```bash
+pip install -e ".[dev]"
+pip install PyYAML
+# optional if not using a sibling checkout:
+# pip install -e ../zencontrol-simulator
+pytest -m simulator
+pytest -m "not simulator"
+# or run everything:
+pytest
+```
 
 ## 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)
+* 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)
 
-Not implemented:
+## 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.)_
@@ -38,6 +51,10 @@ Not implemented:
 * 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.)_
 
+## License
+
+[MIT](LICENSE)
+
 ## Links
 
 * [About TPI Advanced](https://support.zencontrol.com/hc/en-us/articles/360000337175-What-is-the-Third-Party-Interface-TPI)

zencontrol_python-0.1.2/examples/dump_simulator_config.py

@@ -0,0 +1,489 @@
+#!/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
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+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: Optional[ZenColour]) -> Optional[dict[str, Any]]:
+    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[Optional[int]] | None) -> list[Optional[int]]:
+    out: list[Optional[int]] = [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[Optional[ZenColour]] | None) -> list[Optional[dict[str, Any]]]:
+    out: list[Optional[dict[str, Any]]] = [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) -> Optional[int]:
+    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.0/tests/test_controller.py → zencontrol_python-0.1.2/examples/live/controller.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test the async ZenProtocol with controller queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=True) as tpi: