52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
Control4 DriverWorks KNX driver for presence-based automation (lights/media) in the C3C house. Produces a `.c4z` package containing a Lua driver.
|
|
|
|
This project is part of a larger AI skill (`control4-driverworks`). Read the skill's SKILL.md and references/KNX.md for full Control4/DriverWorks/KNX API documentation.
|
|
|
|
## Build
|
|
|
|
Nix flake-based. Requires `direnv` or manual `nix develop`.
|
|
|
|
```bash
|
|
# Dev shell (provides luajit, zip, xmllint)
|
|
nix develop
|
|
|
|
# Build .c4z package
|
|
nix build
|
|
|
|
# Build and copy to ../compiled/ for Composer Pro
|
|
nix run
|
|
```
|
|
|
|
No test suite or linter configured.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
driver.xml # C4 device manifest (proxies, connections, events, properties)
|
|
driver.lua # Lua driver: lifecycle hooks, initialization logic
|
|
control4-utils/ # Driver library (logging, KNX wrappers, hooks), shared between drivers DO NOT MODIFY WITHOUT PRIOR CONSENT
|
|
lib/ # Custom driver logic (presence handling per room, daytime state)
|
|
www/
|
|
icons/ # Composer list icons (logo_16.png / logo_32.png)
|
|
documentation.html # Built output (generated by nix build from README.md via lowdown, DO NOT edit)
|
|
README.md # Built into src/www/documentation.html using lowdown
|
|
```
|
|
|
|
### Key conventions
|
|
|
|
- **Version injection**: `DRIVER_VERSION` in `driver.lua` is replaced by nix build with git rev. Bump `<version>` integer in `driver.xml` on every change.
|
|
- **Proxy binding ID**: `5000` used consistently across `driver.xml` (proxy) — this is a live, deployed binding id, do not change it.
|
|
- **Driver slug**: must match c4z filename (`c3c-knx-presence`). Defined as `driverName` in `flake.nix`, `DRIVER_NAME` in Lua, `<proxy>`/`<model>` in XML.
|
|
- **KNX group addresses**: accessed exclusively through `C3C.KnxAddresses.Get`/`.Watch` from `control4-utils/knx`. Never talk to the KNX proxy directly.
|
|
|
|
## Bump version
|
|
|
|
**ALWAYS increment `<version>` in `src/driver.xml` in the same response where you edit ANY source files.** Do not defer to commit time. Multiple bumps per session is fine. Nix does not auto-increment.
|