Hardware quickstart

Revka can drive physical microcontrollers and single-board computers as agent tools. This page takes you from a freshly plugged-in board to an agent that can read and write its GPIO pins. It covers how Revka discovers USB boards at boot, the stable aliases it assigns, how to register a board that wasn’t auto-discovered, and the [hardware] / [peripherals] config that controls all of it.

Use this page when you connect a Raspberry Pi Pico, Arduino, ESP32, or STM32 Nucleo for the first time. For the per-board details (VID/PID, LED pins, memory maps) see Supported boards reference; for flashing see Flashing firmware.

Caution

Hardware support is compiled in behind the hardware Cargo feature. A binary built without it exposes none of the commands or tools on this page. Build with cargo build --release --features hardware, and add peripheral-rpi for native Raspberry Pi GPIO. See Cargo feature flags & ADRs.

How hardware is split into two subsystems

Revka organizes hardware into two cooperating subsystems. Knowing which one a board belongs to tells you how it is registered and which tools it gets.

Subsystem	What it manages	How a board joins	Tools it loads
hardware	USB-level device registry. Scans serial ports, identifies boards by VID/PID, assigns aliases.	Auto-discovery at boot.	Pico GPIO/code tools (always present when the hardware feature is built) and Aardvark I2C/SPI/GPIO tools (only when an adapter is detected).
peripherals	Config-driven board table. Boards listed in config.toml with an explicit transport.	revka peripheral add or a manual [[peripherals.boards]] entry.	Serial/native GPIO tools plus board-info tools for the configured board.

Most first boards (a Pico or Arduino on USB) are handled by auto-discovery. You only touch the peripherals table when a board was plugged in after startup, has an unrecognized USB ID, or uses a non-serial transport (native Raspberry Pi GPIO or the Arduino Uno Q bridge).

The hardware boot subsystem

When the daemon starts (revka daemon), the hardware boot routine runs automatically — there is no separate command to invoke. At boot Revka:

1. Scans every USB serial port and matches each device’s vendor/product ID against a built-in board registry.
2. Registers aliases for known boards — stable, session-scoped names like pico0, arduino0, nucleo0, or aardvark0.
3. Pre-registers any boards listed in your [[peripherals.boards]] config (their serial transports open lazily on first use).
4. Attaches transports and loads the matching tools conditionally based on what hardware is present.
5. Injects context — the discovered device list plus any hardware context files are added to the agent’s system prompt so the model knows what it can control.

Aliases are stable for the life of a session and reset on the next daemon restart.

Note

Tool loading is conditional. The Pico tools (gpio_write, gpio_read, pico_flash, device_read_code, device_write_code, device_exec) are always loaded when the hardware feature is compiled, even with no board attached — they report “no device found” gracefully. Aardvark tools load only when an adapter is detected at startup. Native Raspberry Pi tools load only when the peripheral-rpi feature is built and /proc/device-tree/model identifies a Pi.

USB device auto-discovery

You can run the same scan the daemon runs at boot, on demand, to see exactly what Revka detects:

revka hardware discover

USB devices:

  2e8a:000a  raspberry-pi-pico  ARM Cortex-M0+  MicroPython v1.21
  2341:0043  arduino-uno        (unknown arch)  —

Known boards: nucleo-f401re, nucleo-f411re, arduino-uno, arduino-mega, cp2102

discover takes no flags. It matches each device’s USB vendor ID against the built-in registry; devices with an unrecognized VID are probed with a short firmware-ping handshake (about 300 ms) and are only registered if they answer with Revka firmware — everything else is skipped silently.

Board IDs and alias prefixes

Board	USB VID	Alias prefix
Raspberry Pi Pico	0x2E8A	pico0, pico1, …
Arduino	0x2341	arduino0
ESP32 (CP2102)	0x10C4	esp0
STM32 Nucleo	0x0483	nucleo0
Total Phase Aardvark	0x2B76	aardvark0
Unknown (firmware-ping match)	—	device0

If you already know a device path and just want to identify what’s on it, use introspect:

revka hardware introspect /dev/ttyACM0   # macOS/Linux
revka hardware introspect COM3           # Windows

Device at /dev/ttyACM0:

  VID:PID     0483:374b
  Board       nucleo-f401re
  Architecture ARM Cortex-M4
  Memory map  512 KB Flash, 128 KB RAM

See revka hardware & peripheral for the full CLI reference, including revka hardware info (probe-rs chip introspection with no firmware on the target).

Connect your first board

A Pico or Arduino on USB is discovered automatically — start the daemon and ask the agent to use it. The walk-through below registers a board explicitly so it works regardless of when you plug it in.

1. Build with hardware support and verify the board is seen.

   cargo build --release --features hardware
   revka hardware discover

   Your board should appear in the USB devices list with an alias.

2. Register the board (if it wasn’t auto-discovered).

   revka peripheral add nucleo-f401re /dev/ttyACM0
   revka peripheral list

   This writes a [[peripherals.boards]] entry to ~/.revka/config.toml. Use native instead of a path for on-board Raspberry Pi GPIO.

3. Restart the daemon so the new board is picked up.

   revka daemon

   revka peripheral add changes config, which only takes effect on a daemon restart.

4. Ask the agent to drive a pin. With one GPIO-capable board attached, the agent can call gpio_write without naming a device:

   revka agent -m "Turn on pin 25"

   The agent calls gpio_write(pin=25, value=1); Revka serializes the serial frame and the board responds.

Tip

To attach a board for a single session without editing config, pass --peripheral <board>:<path> to revka agent — for example revka agent --peripheral nucleo-f401re:/dev/ttyACM0. See revka agent.

Board registration via config

revka peripheral add <board> <path> is a convenience wrapper around a config entry. The equivalent manual ~/.revka/config.toml block:

[peripherals]
enabled = true

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

Field	Type	Default	Meaning
board	string	—	Board identifier: nucleo-f401re, nucleo-f411re, arduino-uno, arduino-uno-q, esp32, or rpi-gpio.
transport	string	—	serial (USB/serial), native (local GPIO, e.g. Raspberry Pi), or bridge (Arduino Uno Q bridge app).
path	string	—	Device path for serial; omit for native.
baud	integer	115200	Serial baud rate.

Note

The serial transport opens lazily — the port is opened on the first command, not at startup. This means the daemon starts successfully even if the board is unplugged, and revka peripheral add works for a board that isn’t connected yet. The change still requires a daemon restart to load the board’s tools.

[hardware] vs [peripherals]

The [peripherals] section (above) is the board table — it is the one you edit to register boards. A separate [hardware] section provides a master on/off switch and global transport hints for the USB-level subsystem:

Key	Type	Values	Meaning
[hardware].enabled	bool	true / false	Master switch for the USB-level hardware subsystem.
[hardware].transport	string	native / serial / probe	Default transport mode for discovered boards.
[hardware].serial_port	string	e.g. /dev/ttyACM0	Explicit serial port override.
[peripherals].enabled	bool	true / false	Enables the config-driven peripheral board subsystem.
[[peripherals.boards]]	table array	—	One entry per registered board (see fields above).

For the full set of config keys and their schema, run revka config schema and see Configuration overview.

Hardware discovery & peripheral management

The two CLI groups map cleanly onto the two subsystems:

• revka hardware — read-only discovery and identification (discover, introspect, info). This is the USB-level subsystem.
• revka peripheral — register, flash, and set up boards (list, add, flash, flash-nucleo, setup-uno-q). This manages the config-driven peripheral table.

Discover & identify

revka hardware discover                  # enumerate connected USB boards
revka hardware introspect /dev/ttyACM0   # identify the device at a path
revka hardware info --chip nucleo-f401re # chip info via probe-rs (needs `probe`)

Register & flash

revka peripheral list                          # list configured boards
revka peripheral add nucleo-f401re /dev/ttyACM0
revka peripheral add rpi-gpio native           # native GPIO (Raspberry Pi)
revka peripheral flash                         # flash Arduino (arduino-cli)
revka peripheral flash-nucleo                  # build + flash Nucleo (probe-rs)
revka peripheral setup-uno-q --host 192.168.0.48

Once a board is registered, the agent reaches it through tools. With exactly one GPIO-capable board attached the device argument is optional; with several, name the alias, e.g. gpio_write(device="pico0", pin=25, value=1). For the full GPIO tool set — including the native Raspberry Pi gpio_rpi_* tools and the Aardvark bitmask GPIO — see GPIO tools.

Tip

Running Revka directly on a Raspberry Pi is different from tethering a board over USB. Native GPIO uses gpio_rpi_write / gpio_rpi_read (BCM pin numbering) and requires the peripheral-rpi feature. The Pi is self-discovered at boot — no config entry needed. See Raspberry Pi (self-hosted).

Hardware context files

Beyond the auto-injected device list, Revka loads Markdown from ~/.revka/hardware/ at boot and injects it into the agent’s system prompt. This lets you teach the agent about your hardware without touching code:

• ~/.revka/hardware/HARDWARE.md — global hardware notes.
• ~/.revka/hardware/devices/<alias>.md — per-device profiles, e.g. pico0.md.
• ~/.revka/hardware/skills/*.md — hardware skills, loaded in alphabetical order.

mkdir -p ~/.revka/hardware/devices
cat > ~/.revka/hardware/devices/pico0.md <<'EOF'
# pico0 — Raspberry Pi Pico
Port: /dev/cu.usbmodem1101
Pin 25 is the onboard LED.
Use device_exec for blink loops rather than repeated gpio_write calls.
EOF

Missing files are skipped silently. The native Raspberry Pi discovery writes its own rpi0.md profile into this directory automatically on every boot. For loops and repeated GPIO work on a tethered board, prefer running code on the device with device_exec instead of issuing many gpio_write calls from the host.

Next steps

Supported boards reference VID/PID, LED pins, memory maps, and feature flags for every board.

Flashing firmware Pico (UF2 + pico_flash), Arduino (arduino-cli), and Nucleo (probe-rs).

GPIO tools gpio_write / gpio_read, native RPi tools, and Aardvark bitmask GPIO.

revka hardware & peripheral The full CLI reference for discovery, registration, and flashing.