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