Generic Zigbee 3.0 device driver

.copier-answers.yml

@@ -3,7 +3,7 @@ _commit: v0.9.16
 _src_path: git@github.com:finitelabs/control4-driver-template.git
 distributions: drivercentral oss
 github_org: finitelabs
-primary_color: '#5D3FD3'
+primary_color: '#C8102E'
 project_description: Integrate generic Zigbee 3.0 devices into Control4 (device definitions
     generated from zigbee2mqtt)
 project_name: control4-zigbee3

.github/dependabot.yml

@@ -0,0 +1,48 @@
+version: 2
+
+# tools/generator is the only npm manifest in this repo. It builds the device
+# database from the zigbee2mqtt definitions and never ships inside a .c4z, so
+# these are build-time dependencies only. The root package.json was retired in
+# the v0.9.11 template update (docs now render with Python and WeasyPrint), so
+# there is nothing left to watch at "/".
+#
+# Bumping zigbee-herdsman-converters does not update the shipped device tables
+# on its own. After merging one of these PRs run `make generate && make build`
+# and commit the regenerated drivers/zigbee3_device/generated/* and
+# SUPPORTED_DEVICES.md, otherwise the pinned converter version and the
+# generated data drift apart.
+#
+# Both halves are required. `make generate` writes unformatted output, while the
+# committed files are post-`make fmt`: stylua wraps devices.lua and mdformat pads
+# the SUPPORTED_DEVICES.md tables. Committing raw generator output makes CI fail
+# its dirty-tree check, because `make build` runs fmt and rewrites everything.
+# It also makes the diff unreadable: raw output reads as roughly 10k insertions
+# against 78k deletions, where the real change after formatting is a few
+# thousand lines.
+#
+# CI cannot catch this drift. build.yml runs `make init` and `make build`, never
+# `make generate`, so its dirty-tree check only proves the committed files are
+# already formatted, not that they match the pinned converters version. A green
+# build says nothing about whether this step was run. The local run is the
+# verification.
+#
+# Read the formatted diff before merging, and check more than the channel list.
+# A converters release can:
+#   * re-key a model. DEVICES lookup in src/zigbee3/device.lua is an exact,
+#     case-sensitive index and Device:restoreModel() re-resolves the persisted
+#     string on every reload, so a re-key silently drops an already-installed
+#     device to generic handling on the next driver update.
+#   * drop a model outright, same effect.
+#   * drop channels, settings or Tuya datapoint maps from a retained model.
+#   * drop button wire keys from a retained model, which silently kills any
+#     Composer programming bound to those actions.
+#   * narrow a binding key in binding_keys.xml from a ManufacturerName wildcard
+#     to specific strings, which changes whether Director claims the device at
+#     all on a fresh pair.
+updates:
+  - package-ecosystem: npm
+    directory: /tools/generator
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: chore

.gitignore

@@ -3,3 +3,12 @@
 /.venv
 /.lua
 **/http-client.private.env.json
+
+# Python bytecode (tools/ scripts and their tests import each other as modules)
+__pycache__/
+*.pyc
+
+# Local screenshot-generation scripts. They drive the maintainer's review-driver
+# skill (shoot_ui.py), which lives outside this repo, so they are kept on disk but
+# not tracked here.
+/shots/

CHANGELOG.md

@@ -1,4 +1,4 @@
-# <span style="color:#5D3FD3">Changelog</span>
+# <span style="color:#C8102E">Changelog</span>
 
 <!--
 Template for a new release entry (copy below the heading, fill in, uncomment):
@@ -19,3 +19,42 @@ Template for a new release entry (copy below the heading, fill in, uncomment):
 -->
 
 ## Unreleased
+
+Initial release. One generic driver that speaks ZCL directly to any joined
+Zigbee 3.0 device: adding a device is a data refresh from the zigbee2mqtt
+database rather than new code, so thousands of devices are supported. The driver
+resolves the joined model and builds its proxies, readings, and settings
+automatically.
+
+### Added
+
+- Sensors: motion, contact, and similar security sensors enroll automatically,
+  and every reading is published as a Control4 variable for programming. A
+  device that reports the same reading on more than one endpoint (a multi-probe
+  sensor, a multi-zone presence sensor) surfaces each one as its own reading,
+  variable, and reporting control rather than collapsing them into one.
+- Energy monitoring: metering plugs and switches publish power, voltage,
+  current, energy, and power factor, each scaled by the device's own multiplier
+  and divisor attributes.
+- Real-time bindings: reporting and button clusters are bound to the coordinator
+  so the device pushes changes at once instead of waiting for a poll. Binds
+  persist across reloads, confirm on a sleepy device's next wake, and are
+  reconciled against the device's own table. A Bindings tab shows their state,
+  and a Re-establish Bindings action re-runs them.
+- Tunable update rate: a cog on each Device-tab reading sets how often it
+  reports (minimum and maximum interval, and the change threshold).
+- Settings: per-device configuration from a Settings tab, covering standard ZCL
+  and manufacturer-specific settings (including vendor custom clusters),
+  delivered reliably to sleepy devices and enforced across reloads.
+- Alerts and actions: battery, trouble, and offline/online alerts, plus Identify
+  and other device actions from the Actions tab.
+- Buttons and remotes: wireless remotes and scene controllers fire Control4
+  programming events, one per button action (e.g. "1 Single", "2 Hold"), decoded
+  from standard ZCL Scenes, On/Off, and Level commands.
+- Companion drivers: a **Zigbee 3 Lock** and a **Zigbee 3 Light** bind to a
+  joined Zigbee 3 Device to present a deadbolt or lever, or a bulb or fixture,
+  as a standard Control4 lock or light. Lock, unlock, dimming, color
+  temperature, and color are enabled from what the device reports.
+- Switches and relays: any switch is presented as a Control4 relay, one per gang
+  over ZCL On/Off, with multi-gang endpoints (l1/l2, left/right) resolved from
+  the zigbee2mqtt database.

Makefile

@@ -233,14 +233,30 @@ zip: $(VENV_STAMP) ## Zip the c4z/, docs/, and source/ subfolders per distributi
 				"$$repo.zip" c4z docs source); \
 	done
 
+# ─── Generate ─────────────────────────────────────────────────────────────────
+# Project-specific: regenerate driver device data from the zigbee2mqtt database.
+# Runs before `preprocess`; the generated fragments are #embed-ed into the
+# hand-authored driver sources. Kept out of `build` so drivers/ stays reviewable
+# source, regenerated deliberately when refreshing device support.
+
+GEN := tools/generator
+
+$(GEN)/node_modules: $(GEN)/package.json
+	cd $(GEN) && npm install
+	@touch $@
+
+.PHONY: generate
+generate: $(GEN)/node_modules ## Regenerate drivers/ device data from the zigbee2mqtt database
+	cd $(GEN) && node extract-z2m.mjs && node map-c4.mjs && node gen-drivers.mjs && node gen-devices.mjs && node gen-compat.mjs
+
 # ─── Test ─────────────────────────────────────────────────────────────────────
 
 .PHONY: test
 # test/ is on LUA_PATH and c4_shim is preloaded, matching the environment
 # test/run_test.sh sets up. Existing suites are written against that shim and
 # fail on a bare `luajit <file>` with "attempt to index global 'C4'". A test that
 # defines its own C4 still wins, since it assigns after the preload has run.
-test: ## Run the Lua test suite (test/test_*.lua)
+test: $(VENV_STAMP) ## Run the Lua test suite (test/test_*.lua) + the Python tool tests
 	@found=0; \
 	for f in test/test_*.lua; do \
 		[ -e "$$f" ] || continue; \
@@ -250,6 +266,11 @@ test: ## Run the Lua test suite (test/test_*.lua)
 			luajit -e "require('c4_shim')" "$$f" || exit 1; \
 	done; \
 	if [ "$$found" = "0" ]; then echo "No test/test_*.lua files found; nothing to run."; fi
+	@for f in tools/test_*.py; do \
+		[ -e "$$f" ] || continue; \
+		echo "==> $$f"; \
+		$(VENV_PY) "$$f" || exit 1; \
+	done
 
 # ─── Build ────────────────────────────────────────────────────────────────────