ctrlPi

Install on your Pico W

Flash MicroPython, then plug the Pico into your Mac/PC and run this there - MicroPython has no shell to run it on the device itself. It downloads the release files, asks for an API key/agent name and your WiFi SSID/password, and deploys everything to the device over USB:

# on your Mac/PC
curl -fsSL https://raw.githubusercontent.com/ctrlpi/pico-gpio-api/main/install.sh | bash

One file, no dependencies

main.py is fully self-contained - WiFi, NTP, HTTP server, GPIO, config, all in one file, nothing to install. The firmware auto-runs it at power-on; once set up, the server starts itself on every boot.

WiFi credentials live in wifi.txt on the device (install.sh writes it for you from a prompt):

SSID = "YourNetwork"
PASSWORD = "YourPassword"

What it does

Outputs: write 0/1/"on"/"off"/"toggle", 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
Sensors: named readings from a MicroPython script in the agent's scripts/ folder, returned as JSON
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 to 7), readable over the API

Interchangeable by design: the ctrlPi integration test suite runs the same 45 REST tests against a Pi and a Pico, only the physical pin numbers are remapped.

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 GP number or name alias
`POST`	`/gpio/write/{name_or_gpio}`	Write a value, supports `"on"`/`"off"`/`"toggle"` 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 usable GP pins (GP0 to GP28, minus GP23/24/25/29 - wired to the onboard WiFi chip), includes physical `level`, platform, CPU temp
`POST`	`/sensor/config/{name}`	Configure a named sensor: a `script` (.py) to run from the agent's `scripts/` folder
`GET`	`/sensor/read`	Read all sensors (or `/sensor/read/{name}` for one) as JSON
`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 device - a microcontroller has no OS layer, so `{"reboot": true}` does the same thing
`POST`	`/upgrade`	Upgrade in place - downloads the latest `main.py` (backing up the old one) and resets
`GET`	`/logs`	Last 30 log lines as JSON (in-memory, cleared on reboot)

Try it

# configure GP15 as an output named "led"
curl -X POST http://<pico-ip>:8314/gpio/config/15 \
  -H "Api-Key: your-secret-key" -H "Content-Type: application/json" \
  -d '{"type": "output", "name": "led"}'

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

Webhooks

Mark any pin watched and the agent POSTs its state to your configured webhook URL on every change, that's how homebridge-ctrlpi gets real-time input events. While setting up, point webhook_url at ctrlPi's public test endpoint and watch your events live while wiring.

Pico W: http webhook targets only. A TLS handshake needs about 35-40 KB of contiguous heap, which the RP2040 often cannot spare once its memory is fragmented, so an https:// webhook delivers for a while and then quietly stops. The original Pico W therefore rejects an https:// webhook_url with a 400 rather than accept a target that will fail later, which also means the ctrlpi.com test endpoint is not usable from one (point it at an http listener on your own network instead). The Pico 2 W (RP2350) has the headroom and takes https:// normally.

In the family

Everything that drives a Pi agent drives a Pico or ESP32 agent unchanged: homebridge-ctrlpi, mcp-bridge, and the webhook flow to ctrlpi.com.

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.