homebridge-nilan: Instructions file for Codex

Repository guide for coding agents

Project overview

homebridge-nilan is a Homebridge dynamic-platform plugin for Nilan Compact P units using the older, non-touchscreen CTS 700 controller. It exposes the unit's ventilation, room temperature, domestic hot water, humidity, and temperature readings to HomeKit over Modbus TCP.

This is a small, mature TypeScript codebase. Prefer focused changes that preserve existing HomeKit identities and device behavior over broad rewrites.

Repository map

• src/index.ts registers the Homebridge platform.
• src/settings.ts contains the public plugin and platform identifiers.
• src/platform.ts handles Homebridge startup, accessory caching, discovery, updates, and removal.
• src/compactPAccessory.ts maps one configured Compact P to HomeKit services, polls it every 10 seconds, and translates HomeKit writes into device writes.
• src/cts700Data.ts defines Modbus register addresses and protocol data types.
• src/cts700Modbus.ts owns the TCP connection, reconnect behavior, register encoding/decoding, device reads and writes, and week-schedule selection.
• test/ contains Vitest tests. Protocol tests use a mocked Modbus client and must never contact real hardware.
• config.schema.json is the Homebridge Config UI schema. Keep it aligned with configuration behavior and the configuration example in README.md.
• .github/workflows/release.yml validates GitHub Releases and publishes the inspected package through npm trusted publishing. Follow RELEASING.md.
• dist/ is generated by TypeScript and ignored by git. Never edit or commit it.

Environment and commands

Use Node.js 22 or 24; .nvmrc selects Node.js 22 by default.

nvm use                 # or select Node 22 with another version manager
npm ci
npm run check           # lint, build, and test with coverage

Individual commands:

npm run lint
npm run build
npm test

npm run watch performs npm link and launches a real Homebridge instance using the user's default ~/.homebridge configuration; do not run it as routine validation. It requires an explicitly prepared local Homebridge environment and may connect to or write to real hardware.