raspberry-pi-gpio-api

Install on your Pi

One-liner, no git required, downloads the release files, safe to re-run to update (config and logs are never touched):

# on the Pi
curl -fsSL https://raw.githubusercontent.com/ctrlpi/raspberry-pi-gpio-api/main/install.sh | bash
cd raspberry-pi-gpio-api
./run.sh     # sets up venv, installs deps, starts the server on :8314

💻No Pi handy? It runs on Mac/PC too, a built-in mock GPIO mode kicks in automatically on non-Pi systems, so you can develop clients anywhere.

What it does

Outputs: write 0/1/"flip", pulse for a duration with automatic revert, clamp with a per-pin max, invert relay logic with reversed
Inputs: pull-up/down/none, name aliases, and watched pins that fire a webhook on every state change
Persistence: pin config and last output values survive restarts and reboots (init: "last")
Identity: every agent reports its name, IP, platform, OS, and CPU temperature; unauthenticated /hello makes LAN discovery trivial
Logging: request log with configurable retention (log_days 0–7), readable over the API

The REST API

All routes require the Api-Key header except /hello:

Method	Path	Description
`GET`	`/hello`	Discovery & health check, returns the agent's name, no auth
`GET`	`/gpio/read`	Read all configured pins
`GET`	`/gpio/read/{name_or_gpio}`	Read one pin by GPIO number or name alias
`POST`	`/gpio/write/{name_or_gpio}`	Write a value, supports `"flip"` and timed `duration` pulses
`POST`	`/gpio/config/{name_or_gpio}`	Configure a pin: type, name, init, pullup, max, reversed, watched
`GET`	`/gpio/watched`	List watched pins and the active webhook URL
`GET`	`/gpio/scan`	Scan all BCM pins (Pi hardware), includes physical `level`, platform, CPU temp
`GET`	`/config/read`	Agent identity + full config
`POST`	`/config/update`	Update config fields (auto-backup first)
`POST`	`/config/load`	Replace the whole config (`{}` resets)
`POST`	`/restart`	Restart the server process, or reboot the device with `{"reboot": true}`
`GET`	`/logs`	Last 50 log lines as JSON

Try it

# configure GPIO 17 as an output named "relay", active-low
curl -X POST http://raspberrypi:8314/gpio/config/17 \
  -H "Api-Key: your-secret-key" -H "Content-Type: application/json" \
  -d '{"type": "output", "name": "relay", "reversed": true}'

# pulse it for 2 seconds, reverts automatically
curl -X POST http://raspberrypi:8314/gpio/write/relay \
  -H "Api-Key: your-secret-key" -H "Content-Type: application/json" \
  -d '{"value": 1, "duration": 2}'

Webhooks

Mark any pin watched and the agent POSTs its state to a webhook URL on every change, that's how the HomeKit and Matter bridges get real-time input events. With no URL configured it defaults to ctrlPi's test endpoint, so you can watch your events live while wiring.

In the family

This is the reference agent. pico-gpio-api speaks the identical wire format on a Pico W; the bridges and ctrlpi-mcp drive any mix of both interchangeably.