$ show mdeweerd/zha-toolkit
This repository is a Home Assistant custom component (integration) that provides a low-level toolkit for managing Zigbee devices over the ZHA (Zigbee Home Automation) stack. It exposes over 30 fine-grained services—attribute read/write, binding, reporting configuration, OTA firmware updates, coordinator backup/restore, and network scanning—to power users and automations that need direct access to zigpy/ZHA internals not exposed by the standard ZHA integration. It acts as a diagnostic and administrative layer for Zigbee mesh networks, delivering results via HA service responses, events, or exported state/CSV/JSON. The architecture is strictly service-driven. All commands are registered in `__init__.py` and routed through a dynamic dispatcher (`default.py`) that maps service names to modules (e.g., `attr_read` maps to `zcl_attr.command()`) via a naming convention. A shared parameter extraction layer in `utils.py` normalizes IEEE addresses, clusters, endpoints, retries, and event callbacks. Since it deeply probes the internal ZHA/zigpy stack, it relies heavily on version guards (`is_ha_ge`, `is_zigpy_ge`) and radio-specific libraries (Bellows, ZNP, EZSP), which makes it brittle across HA/zigpy releases but proactive about compatibility. The component uses HA's event bus for async feedback, supports state writing with Jinja2-like templates, and downloads OTA firmware from external repositories. While functionally strong and actively maintained, the codebase carries significant technical debt: it performs `importlib.reload` on its own modules per service call (discouraged by HA core guidelines), has thin test coverage (linting/HACS validation only), includes an undocumented user-supplied `_user.py` injection point, and contains many untested edge paths. The dynamic dispatcher and retry/parameter-util patterns are the most valuable, reusable pieces, but most modules are tightly coupled to HA configuration flow and zigpy internal APIs.
The LLM identified 2 files worth highlighting for reuse:
Contains a generic `retry_wrapper` decorator that can wrap any async zigpy call with configurable tries, delay, and exception handling, enabling resilient operations against sleepy devices. Also contains `extractParams`, which normalizes a very large, multi-field service API (IEEE, endpoints, clusters, attributes, report config) into a single dictionary. The retry pattern is safely extractable to any async I/O codebase; the parameter extraction demonstrates a clean approach to handling a sprawling CLI-like service surface.
Implements a dynamic command loader: service names like `module_command` are resolved to `module.py` -> `async def module_command(...)` without requiring explicit registration. New commands are added simply by creating a new module and function following the naming convention. This is a clean, self-documenting plugin architecture. Although the example is HA-specific, the dispatcher pattern itself is a reusable pattern for extensible service-oriented systems that want to minimize boilerplate and avoid central registration lists.