GPIO tools

GPIO tools let your agent drive and sense pins on a connected board through plain function calls. The two core tools — gpio_write and gpio_read — work the same way for every tethered board (Raspberry Pi Pico, Arduino Uno, ESP32, STM32 Nucleo) because they all speak the same Revka serial JSON protocol. This page covers those two tools, the serial transport that carries them, the hardware_capabilities discovery tool, the Arduino Uno Q Bridge variant that runs over a TCP socket, and the hardware context files that teach the agent about your specific board.

Use this page when you want the agent to flip an LED, read a button, or check which pins a board exposes. If Revka runs directly on a Raspberry Pi (not tethered over USB), use the native gpio_rpi_* tools instead — see Raspberry Pi (self-hosted). To connect and flash a board first, see Hardware quickstart and Flashing firmware.

Prerequisites

GPIO tools require a build with the hardware Cargo feature (cargo build --features hardware) and a flashed board running Revka firmware. The Pico tools (including gpio_write / gpio_read) are always loaded when the feature is compiled — even with nothing plugged in — and report “no device found” gracefully. See Cargo feature flags & ADRs.

GPIO Write (gpio_write)

gpio_write sets a GPIO pin HIGH or LOW on a registered device. The agent calls it as a function; you typically trigger it with natural language (“turn on pin 25”).

Parameter	Type	Required	Meaning
pin	integer	yes	GPIO pin number
value	integer	yes	1 = HIGH (on), 0 = LOW (off)
device	string	no	Device alias, e.g. pico0, arduino0. Auto-selected when exactly one GPIO-capable device is registered; required when multiple boards are present.

A typical agent invocation:

User:  Turn on pin 25
Agent: gpio_write(pin=25, value=1)

# With more than one board connected:
Agent: gpio_write(device="pico0", pin=25, value=1)

Under the hood the tool sends one newline-delimited JSON line over the device transport and reads one line back:

// Host → Device
{"cmd":"gpio_write","params":{"pin":25,"value":1}}
// Device → Host
{"ok":true,"data":{"pin":25,"value":1,"state":"HIGH"}}

On success the tool returns a line like GPIO 25 set HIGH on pico0. Values other than 0 or 1 are rejected before any I/O, and a missing pin or value returns a parameter error.

Don't loop gpio_write for blinks

Calling gpio_write repeatedly from the host to blink an LED is slow — each call is a full serial round-trip. For blink loops and repeated on-device GPIO work, push a small program to the board with device_exec (MicroPython) instead. See revka hardware & peripheral.

GPIO Read (gpio_read)

gpio_read reads the current HIGH/LOW state of a pin. It uses the same transport and the same auto-selection rules as gpio_write.

Parameter	Type	Required	Meaning
pin	integer	yes	GPIO pin number to read
device	string	no	Device alias; auto-selected if only one GPIO device is registered

Agent: gpio_read(pin=25)
# or, with multiple boards:
Agent: gpio_read(device="pico0", pin=25)

Wire exchange:

// Host → Device
{"cmd":"gpio_read","params":{"pin":25}}
// Device → Host
{"ok":true,"data":{"pin":25,"value":1,"state":"HIGH"}}

The tool output includes both the numeric value and the text state, for example:

GPIO 25 is HIGH (1) on pico0

Which GPIO tool runs

gpio_write and gpio_read are the same tool names across very different transports. Revka substitutes the right implementation based on how the board is registered, so the agent never has to choose.

Setup	Tools	Transport
Tethered Pico / Arduino / ESP32 / Nucleo over USB	gpio_write, gpio_read	Serial JSON protocol (this page)
Revka running natively on a Raspberry Pi	gpio_rpi_write, gpio_rpi_read, gpio_rpi_blink	Direct /dev/gpiomem via rppal — see Raspberry Pi (self-hosted)
Arduino Uno Q with transport = "bridge"	gpio_write, gpio_read	Bridge TCP socket on 127.0.0.1:9999 (below)
Total Phase Aardvark adapter	gpio_aardvark	8-pin bitmask over USB — see Aardvark I2C/SPI/GPIO & datasheets

On a Raspberry Pi, prefer the native tools

When Revka runs directly on an RPi, use gpio_rpi_write / gpio_rpi_read rather than the serial gpio_write / gpio_read. The native tools talk to the Pi’s own GPIO; the serial ones expect a tethered firmware board.

Serial Peripheral Transport

All tethered boards reach their GPIO through the serial transport, which carries the Revka serial JSON protocol over a serial port. You configure it implicitly by setting transport = "serial" on a board entry.

[peripherals]
enabled = true

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

Field	Type	Default	Meaning
path	string	—	Serial port path (e.g. /dev/ttyACM0, /dev/cu.usbmodem101)
baud	integer	115200	Serial baud rate

Two behaviors are worth knowing:

• Lazy open. The port is opened on the first command, not at daemon startup. The daemon starts cleanly even if the board is unplugged at boot — plug it in and the first gpio_write opens the connection.
• Firmware ping handshake. On first connection the transport sends a ping and expects a Revka firmware response within 300 ms. Boards that do not answer with Revka firmware are not treated as GPIO devices.

The wire contract is the newline-delimited ZcCommand / ZcResponse pair shown throughout this page: a host command (cmd + params) for each request, and a device response (ok + data, plus error when ok is false). Both firmware and host must agree on this format, so the Pico, Arduino, ESP32, and Nucleo all implement it identically.

Register a board that wasn't auto-discovered

Boards plugged in after startup, or with unknown USB vendor IDs, can be added with revka peripheral add <board> <path>, which writes to ~/.revka/config.toml. A daemon restart picks up the new entry. Details: revka hardware & peripheral.

Discover available pins (hardware_capabilities)

Before writing to a pin, the agent can ask each serial board which pins it exposes and which pin drives the onboard LED. The hardware_capabilities tool queries the firmware’s capabilities command and reports the result.

Parameter	Type	Required	Meaning
board	string	no	Filter to a single board name. Omit to query every configured serial board.

Agent:  hardware_capabilities()
Output: arduino0: gpio [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], led_pin 13

This tool is only registered when the hardware feature is built and serial boards are configured. The firmware must implement the capabilities command in its serial JSON handler; the Revka Arduino firmware enables it alongside gpio_read and gpio_write. If no board matches the filter, the tool reports that capabilities are not supported.

Arduino Uno Q Bridge GPIO Tools

The Arduino Uno Q is a Linux board with a companion MCU. Instead of a serial port, GPIO goes through a small Bridge app (Python + MCU socket server) that listens on TCP port 9999 and exposes the MCU’s pins to the Linux side. When you configure the board with transport = "bridge", Revka transparently swaps the standard gpio_read / gpio_write tools for socket-backed implementations — the agent uses the same tool names.

[[peripherals.boards]]
board = "arduino-uno-q"
transport = "bridge"

Calling the tools is identical to the serial case:

User:  Turn on pin 13 on the Arduino
Agent: gpio_write(pin=13, value=1)

Internally the Bridge tools open a TCP connection to 127.0.0.1:9999 and send a space-delimited, newline-terminated line — for example gpio_write 13 1\n for a write or gpio_read 13\n for a read — then read the reply.

Timeout	Value
Connection	5 s
Response	3 s

The Bridge app must be running

These tools fail if the Bridge app isn’t up. Deploy and start it with revka peripheral setup-uno-q --host <ip> (or run it from the Uno Q itself). Error responses from the Bridge are returned verbatim and begin with an error: prefix. Full deployment walkthrough: revka hardware & peripheral and Supported boards reference.

Hardware Context Files

GPIO tools work on raw pin numbers, but the agent reasons better when it knows what each pin does on your board. Revka loads markdown from ~/.revka/hardware/ at boot and injects it into the LLM system prompt, so you can teach the agent about your hardware without touching code. Three kinds of files are supported:

Path	Purpose
~/.revka/hardware/HARDWARE.md	Global hardware notes shared across every device
~/.revka/hardware/devices/<alias>.md	Per-device profile, named for the session alias (e.g. pico0.md)
~/.revka/hardware/skills/*.md	Hardware skills, loaded in alphabetical order by filename

1. Write global notes. Capture board-agnostic rules and pin conventions.

   cat > ~/.revka/hardware/HARDWARE.md << 'EOF'
   # Hardware Notes
   - Pin 25 is the onboard LED on Pico
   - Use device_exec for blink loops
   EOF

2. Add a device profile. Name the file after the device alias so it loads only when that board is present.

   mkdir -p ~/.revka/hardware/devices
   cat > ~/.revka/hardware/devices/pico0.md << 'EOF'
   # pico0 — Raspberry Pi Pico
   Port: /dev/cu.usbmodem1101
   Use pin 25 for the onboard LED.
   EOF

3. Restart the daemon so the boot subsystem re-reads the directory and injects the new context.

How loading works:

• Files are plain markdown — no schema or frontmatter required.
• Sections are joined with double newlines when injected into the system prompt; missing files are silently skipped, and empty files are ignored.
• Device profiles load only for aliases that are actually registered in the session.

HARDWARE.md must mention device_exec

A behavioral gate (unit-tested) requires your HARDWARE.md to mention device_exec. This keeps the agent aware that blink and loop operations belong on the device, not as a flood of host-side gpio_write calls. The line Use device_exec for blink loops in the example above satisfies it.

The RPi profile writes itself

When Revka runs natively on a Raspberry Pi (peripheral-rpi feature), it auto-generates ~/.revka/hardware/devices/rpi0.md on every boot with the live board model, IP, RAM, temperature, and GPIO tool-usage rules. You don’t create that file by hand. See Raspberry Pi (self-hosted).

Related pages

Hardware quickstart Connect your first board, auto-discovery, aliases, and a minimal config.toml.

Flashing firmware Flash Revka firmware to Pico, Arduino, and Nucleo so GPIO tools work.

Raspberry Pi (self-hosted) Native gpio_rpi_write / read / blink when Revka runs on the Pi itself.

Aardvark I2C/SPI/GPIO & datasheets The gpio_aardvark bitmask tool and the I2C/SPI adapter stack.

revka hardware & peripheral Discover, add, and flash boards; deploy the Uno Q Bridge.

Supported boards reference VID/PID, alias prefixes, LED pins, and feature flags per board.