homekit-bridge · ctrlPi

Quick start

git clone https://github.com/ctrlpi/homekit-bridge.git
cd homekit-bridge
npm install
cp config.json.example config.json   # name your agents and devices
node bridge.js                        # prints the HomeKit setup code + X-HM:// URI

Scan the setup code with the Home app and every declared device appears, individually automatable. Pairing state persists in .homekit/; node bridge.js -c clears it for a fresh pairing.

Declare devices, not code

{
  "name": "MyBridge",
  "agents": [{ "name": "garage", "ip": "192.168.1.20", "api-key": "..." }],
  "devices": [
    { "id": "light1", "name": "Porch Light",  "type": "light",      "gpio": 17, "agent": "garage" },
    { "id": "door1",  "name": "Garage Door",  "type": "garagedoor", "gpio": 27, "agent": "garage" },
    { "id": "pir1",   "name": "Hall Motion",  "type": "motion",     "gpio": 22, "agent": "garage", "pull": "up" }
  ]
}

Device types → HomeKit services

Config `type`	HomeKit service
`light`	Lightbulb
`plug` / `outlet`	Outlet
`fan`	Fan
`lock`	Lock Mechanism
`garagedoor`	Garage Door Opener, real open/close states
`valve` / `shades`	Valve / Window Covering
`contact` / `motion` / `occupancy`	Contact / Motion / Occupancy Sensor
`smokeco` / `waterleak`	Smoke / Leak Sensor
`switch`	Stateless Programmable Switch, single, double & long press

How it drives the pins

Outputs go over REST to the agent (reversed relay logic applied by the bridge; pulse uses the agent's native timed auto-revert, locks and garage doors pulse by default)
Inputs push in real time: the bridge points each agent's webhook at its own listener (port 8316), so a door contact or PIR fires into the Home app instantly, no polling
No local GPIO: the bridge runs identically on a Pi, a Mac, or any Linux box; agents do the electrical work
Gentle on Picos: pin configs are only rewritten when they actually change, avoiding needless flash writes

🌐Prefer Google Home or Alexa? The matter-bridge sibling exposes the same config file to every Matter ecosystem, run both side by side if you like (they use different webhook ports).

In the family

Same device vocabulary and config schema as matter-bridge; drives any mix of Pi and Pico W agents.