Metadata-Version: 2.4
Name: zencontrol-python
Version: 1.0.0
Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
Author: Simon Wright
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
Keywords: dali,lighting,control,zencontrol,home-automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: colorama
Requires-Dist: colorama>=0.4.6; extra == "colorama"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: types-colorama; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: colorama>=0.4.6; extra == "dev"
Provides-Extra: mqtt
Requires-Dist: aiomqtt>=2.1.0; extra == "mqtt"
Requires-Dist: PyYAML>=6.0; extra == "mqtt"
Requires-Dist: colorama>=0.4.6; extra == "mqtt"
Dynamic: license-file

# zencontrol-python

This is an implementation of the **Zencontrol TPI Advanced** protocol, written in Python. This library has been written with three levels of abstraction:

- zencontrol.io: Implementation of the raw TPI Advanced UDP packet specification;
- zencontrol.api: Implementation of most TPI Advanced API commands and events;
- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables.

[**Documentation**](docs/overview.md)

In addition to an extensive test suite, this library is extensively tested by
[zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator), a nearly feature-complete simulator of zencontrol hardware.
As part of its own test suite, the simulator imports and implements this library to a substantial extent.

This library is actively used as a central part of [zencontrol-homeassistant](https://github.com/sjwright/zencontrol-homeassistant), a Home Assistant integration. This integration gives you GUI access to most zencontrol-python features, making it an excellent practical demonstration of the library.

## 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)
* Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)

## Install

```bash
pip install zencontrol-python
```

## 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
```

## TPI Advanced wishlist

* Command to return a controller's MAC address used for multicast packets _(There are other ways to get or infer the MAC access, but they're unreliable.)_
* Command to list active system variables _(As a workaround, you can query every number for its label. This assumes no system variables of interest are unlabelled.)_
* Command to read an ambient light sensor's lux value. _(As a workaround, you can target a light sensor to a system variable. Not elegant but it works.)_
* Event notification for ambient light sensor lux values. _(Same workaround as above.)_

## License

[MIT](LICENSE)

## Links

* [About TPI Advanced](https://support.zencontrol.com/hc/en-us/articles/360000337175-What-is-the-Third-Party-Interface-TPI)
