ctrlPi

Quick start

In the Homebridge UI open Plugins, search for ctrlPi, install it, and fill in the settings form. There is no terminal step and nothing to configure on the Pi first.

Restart Homebridge and the accessories appear in the Home app, each one individually automatable.

Accessories

`accessory`	HomeKit service	Backed by
Output Devices
`fan`	Fan	an output pin
`lightbulb`	Lightbulb	an output pin
`outlet`	Outlet	an output pin, optional in-use input
`switch`	Switch	an output pin
Input Devices
`button`	Stateless Programmable Switch	an input pin, single / double / long press
`contact`	Contact Sensor	an input pin
`dioxide`	Carbon Dioxide Sensor	an input pin
`indicator`	Lightbulb, read-only	an input pin, shows its state as a light; taps are ignored
`leak`	Leak Sensor	an input pin
`monoxide`	Carbon Monoxide Sensor	an input pin
`motion`	Motion Sensor	an input pin
`occupancy`	Occupancy Sensor	an input pin
`smoke`	Smoke Sensor	an input pin
Combined Devices
`garagedoor`	Garage Door Opener	a relay pin, optional open and close sensors
`irrigation`	Irrigation System	one relay pin per zone, each zone a Valve
`lock`	Lock Mechanism	one or two relay pins, optional door and bolt sensors
`shades`	Window Covering	an up and a down relay, optional limit sensors
`valve`	Valve	one or two relay pins, optional position sensor
Environment Sensors
`humidity`	Humidity Sensor	an agent script, polled
`lux`	Light Sensor	an agent script, polled
`temperature`	Temperature Sensor	an agent script, polled

How it drives the pins

The plugin configures the agent, not the other way round: on every start it pushes each pin's type, pull resistor and name to its agent, so the wiring is described once, in the Homebridge settings form
Nothing is polled except sensors: every pin is configured watched, and the agent POSTs to the plugin's listener (port 8318, its own callback slot on the agent) the moment it changes, so a wall switch or a physical button shows up in HomeKit instantly, not on the next poll
Sensors are configured: you give the script, the plugin creates the sensor on the agent under the device's own name and polls it every 15 minutes by default - a reading runs a script on the device, so it is deliberately slow
Callbacks are authenticated: a fresh 12-character key per agent is generated on every start and pushed alongside the callback URL, so an event without it is refused with a 401 and a stale key from a previous run stops working immediately
Pulses are timed by the agent: a momentary output sends its duration with the write, so if Homebridge restarts mid-pulse the relay still releases
No GPIO inside Homebridge: the plugin holds no GPIO logic. Put Homebridge on the same Pi as the agent, or on any other machine on your LAN, and the agents do the electrical work

In the family

Drives any mix of pi-gpio-api Pis, pico-gpio-api Pico Ws and esp32-gpio-api ESP32s, so one Homebridge can put every board in the house into Apple Home side by side.

To talk to the same agents from Claude or another AI assistant, see mcp-bridge. To test endpoints, watch webhook events and tail logs in the browser, open ctrlpi-lab, and to find and drive agents from a terminal, use ctrlpi-cli.

To get an agent onto a board over USB, use pico-bay. It can install MicroPython, manage the board's files and run code on a Pico and an ESP32. pi-bay, for a Raspberry Pi over the network, is coming soon.