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.

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

2.2 KiB Raw Blame History