Open-source GPIO automation

Control the real world with Raspberry Pi & Pico

ctrlPi turns every GPIO pin into something you can flip from anywhere, a REST call, the Apple Home app, a Matter ecosystem, or an AI agent. Relays, locks, lights, sensors: wired to a Pi, controlled by anything.

🚀 Get started on a Pi See how it works
you@laptop · any HTTP client works
$ curl -X POST http://garage-pi:8314/gpio/write/relay \
    -H "Api-Key: ●●●●●●" -d '{"value": 1, "duration": 2}'
{"gpio": 17, "value": 1, "duration": 2.0, "name": "relay"}
# 2 seconds later the relay reverts itself, and the webhook fires:
→ POST https://ctrlpi.com/webhook/test  {"agent": "garage-pi", "gpio": 17, "value": 0}
The story

One tiny server per board. Everything else talks to it.

It starts with an agent, a small, zero-fuss server you drop on a Raspberry Pi or a $6 Pico W. It exposes every GPIO pin over a clean REST API: read, write, pulse, watch. From there, the rest of the family builds up: smart-home bridges make your pins show up in Apple Home and Google Home, an MCP server hands the keys to AI assistants like Claude, and webhooks push every change back to you in real time. Each piece is a small, standalone, MIT-licensed project, use one, or use them all.

🔌

Agents: the muscle

A single-file REST server on the Pi or Pico W drives the pins: outputs, inputs, pull-ups, pulses with auto-revert, reversed relay logic, and webhooks on every change. Same API on both boards, clients never care which one answered.

🏠

Bridges: the home

Matter and native-HomeKit bridges declare your devices in one JSON file, lights, locks, garage doors, valves, sensors, buttons, and drive them through the agents' API. Pair once, control from your phone, your watch, or "Hey Siri".

🤖

MCP: the brain

A zero-dependency Model Context Protocol server exposes the whole GPIO surface as tools. Ask Claude to scan your LAN for agents, flip a relay, or watch a door sensor, in plain language.

How it works

Small pieces, one wire format

Every arrow below is plain HTTP with an Api-Key header, no hubs, no clouds required, everything on your LAN.

 [Claude / any MCP client]          [Apple Home]   [Google Home / Alexa]
            │                               │                │
       MCP (stdio/HTTP)                    HAP            Matter
            │                               │                │
            ▼                               ▼                ▼
     ctrlpi-mcp :8315            homekit-bridge :8316      matter-bridge :8317
            │                               │                │
            └────────────┬──────────────────┴────────────────┘
                         │  REST  /gpio/*  /config/*   (Api-Key)
                         ▼
        agents :8314 · raspberry-pi-gpio-api (Pi) · pico-gpio-api (Pico W)
                         │
              GPIO pins: relays · locks · lights · sensors · buttons
                         │
                         └── webhook POST on every change ──▶ bridges / ctrlpi.com

Drop an agent on a board

One file on a Pi (main.py, FastAPI) or a Pico W (MicroPython or CircuitPython). It serves the same 14 REST endpoints on port 8314, persists pin config across reboots, and needs nothing else.

Wire your devices, declare them once

Relays and sensors connect to GPIO pins. A bridge's config.json names each device, "Porch Light, type light, GPIO 17, agent garage", and the bridge configures the pins over REST automatically.

Inputs push, they don't poll

When a watched pin changes, a door opens, a button is pressed, the agent fires a webhook instantly. Bridges turn it into a HomeKit/Matter event; you can also watch the raw feed live on the web.

Let the AI drive (optional, but fun)

Point Claude Desktop at ctrlpi-mcp and every agent becomes conversational: "which agents are online?", "pulse the garage door for 2 seconds", "show me the logs from shed-pico".

The packages

Five projects, one family

Every project is standalone, MIT-licensed, and lives at github.com/ctrlpi, Node packages ship on npm under @ctrlpi.

AGENT · PYTHON
🍓

raspberry-pi-gpio-api

The core REST server for Raspberry Pi 2/3/4/5/Zero. FastAPI, one-liner install, API-key auth, mock mode on Mac/PC for development.

Overview GitHub
AGENT · MICROPYTHON
🎛️

pico-gpio-api

The same API on a $6 Raspberry Pi Pico W, MicroPython or CircuitPython, one self-contained file, boots straight into serving.

Overview GitHub
AI · NODE
🤖

ctrlpi-mcp

Zero-dependency MCP server: 10 tools that let Claude and other AI clients discover agents and drive their GPIO over REST.

Overview GitHub npm
BRIDGE · NODE
🏠

homekit-bridge

Native Apple HomeKit (hap-nodejs), no Homebridge, no hub. Garage doors, locks, fans, sensors and buttons straight into the Home app.

Overview GitHub npm
BRIDGE · NODE
🌐

matter-bridge

A Matter-over-IP bridge on matter.js, the same devices in Apple Home, Google Home, Alexa, and Home Assistant at once.

Overview GitHub npm
LIVE
📡

Webhook watch

Every agent can POST pin changes to ctrlpi.com. Watch the live event feed while you wire and test, no setup, it's the default webhook target.

Open the live feed
Reference

Pinouts, one click away

Interactive pinout references for both boards, keep one open while you wire.

🍓

Raspberry Pi GPIO pinout

The 40-pin J8 header: BCM numbers, physical pins, power rails, and alternate functions for Pi 2/3/4/5/Zero.

Open pinout
🎛️

Pico W pinout

All GP0–GP28 pins of the Pico W: GPIO numbers, ADC inputs, power pins, and the onboard LED.

Open pinout
AI & MCP

"Claude, open the garage."

Two lines of config connect Claude Desktop to every agent on your LAN.

Add to Claude Desktop

Point an MCP entry at server.js, on first run it scans your LAN and builds its own agent list:

{
  "mcpServers": {
    "ctrlpi": {
      "command": "node",
      "args": ["/path/to/ctrlpi-mcp/server.js"]
    }
  }
}

Then just ask

Ten tools cover the whole surface, discovery, read, write, pulse, config, logs, restart:

  • 💬 "Which agents are online right now?"
  • 💬 "Turn on the porch light on garage-pi."
  • 💬 "Pulse GPIO 26 for two seconds."
  • 💬 "Is the front door contact open?"
Full MCP instructions