RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

RoboHub Pico Platform

The RP2040 and RP2350 platform for the RoboHub ecosystem: the interfaces
declared by robohub-common, implemented on Raspberry Pi Pico boards, with
board support packages for the Pico boards.

The platform

A Rho program on this platform runs on a Pico. The platform provides the
interfaces, the HAL, and the board support package that registers the board's
peripherals.

Building

cd examples/c/hello_world
rho build -target pico2w .

Flashing

rho flash -target pico2w -project . build/output/hello_world.elf

The platform converts the ELF to UF2 and writes it to the bootrom's drive, or
loads it over PICOBOOT through picotool when that is available. A board that
is already running a program is asked to reboot into BOOTSEL by picotool -f.
A Pico Shared to a Windows host is attached to WSL first, and re-attached after
the reboot, because the USB device comes back on the other side of the bridge.
Passwordless sudo is used only when it is already available; otherwise the
drive is the fallback.

Flashing as a user

picotool opens the bootrom's USB device, which belongs to root until a udev rule
says otherwise. The platform carries the rule (udev/60-robohub-pico.rules,
for every Raspberry Pi device, vendor 2e8a, to the plugdev group) and
declares it in system_deps, so rho doctor says when it is missing. Install
it once, then unplug and plug the board in again (on WSL, attach it again):

rho keeper install --path <robohub-pico> robohub-pico 60-robohub-pico.rules

Without it the flash says that picotool found the board but may not open it,
names that command, and falls back to the bootrom's drive — slower, and on WSL
done through the Windows host.

The examples

examples/c/hello_world is the smallest program that runs on real hardware.

examples/rho/hello_world is that program in Rho, written against the
contracts and nothing else.

examples/c/freertos_hello_world is that program with its work in a FreeRTOS
task: it links robohub-freertos and uses the RoboHub OSAL, so the same source
runs with or without the kernel beneath it. The board's USB console is pumped by
a task above the ordinary task priorities, so a console write cannot starve the
USB stack it waits for.

The board manifest declares the roles and transports a deployment planner may
offer (gateway, relay, node, edge, wireless, links and buses) and
the deployment block names how a gateway is built and reached. Adding a board
does not require a keeper rebuild.

The device keystore

The rotated device key (robohub/keystore.h) lives in the last two 4 KiB
sectors of flash — on a Pico 2W's 4 MB part, 0x103FE000-0x103FFFFF in the
XIP window — slot A then slot B, with the A/B records, CRC32 and sequence
numbers of robohub/keystore_core.h. src/platform/pico_keystore.c erases and
programs a sector through the SDK (hardware_flash) inside
flash_safe_execute (pico_flash), which disables interrupts and locks the
other core out; if core 1 runs without having called
flash_safe_execute_core_init (and no SDK-aware RTOS is in charge), the store
refuses rather than crash.

The SDK's linker script is left as it is. The platform adds an implicit script,
cmake/pico_keystore_reserve.ld, that fails the link when the image's end
reaches the keystore: a program that grows into it does not link, instead of
having its tail erased by a key rotation. The flash size is the board's
(PICO_FLASH_SIZE_BYTES), and the source refuses to compile if the two
disagree.

The RP2350's OTP is the better home for a key (it can be locked against
reading), and is planned. It is one-time programmable, so every rotation would
use up rows; until a scheme for that is settled the key stays in flash, which
SWD can read unless debug is disabled.

Production

CONFIG_RH_PRODUCTION=y (production/production.conf) builds a signed image
for RP2350 secure boot. Set RH_SECURE_BOOT_SIGNING_KEY to a secp256k1 PEM key
(openssl ecparam -name secp256k1 -genkey -out key.pem); the build seals the
ELF with picotool and writes the OTP rows that enable secure boot for that key
to build/output/<program>.otp.json. Building burns nothing. Signing needs a
picotool built with mbedtls (the SDK's lib/mbedtls submodule); one built
without it stops the build at picotool seal.

export RH_PICO_OTP_JSON=build/output/app.otp.json
rho flash -target pico2w build/output/app.elf --production --dry-run
rho flash -target pico2w build/output/app.elf --production

production/rp2350.json is the plan: with the board in BOOTSEL mode it loads
the OTP file (picotool otp load, irreversible: BOOTKEY0, BOOTFLAGS1
KEY
VALID, CRIT1 SECUREBOOTENABLE) and then writes the signed image. The OTP
file's contents are printed in full, and nothing runs until the board name is
typed. Disabling debug (CRIT1 DEBUG_DISABLE) is not part of the plan; it is
irreversible on its own and is left to a deliberate, separate decision.

Release history

All notable changes to this module are recorded here, one section per release.

[0.2.0] - 2026-11-01

The flash entry attaches a Pico Shared to a Windows host to WSL, reboots a running board into BOOTSEL, re-attaches it after that reboot, uses passwordless sudo only when available and falls back to the bootrom's drive. The board manifest declares the roles, links, buses and flash deployment a Mesh planner reads. The docs cover the FreeRTOS hello-world example and the USB-CDC pump.

[0.2.1] - 2026-11-13

A Pico in BOOTSEL that Windows has not shared with WSL yet is shared by the flash entry, which asks Windows for an administrator's consent once, and then attached; before, only a board already shared was attached, and the flash found no device.

[0.2.2] - 2026-11-13

The flash entry finds powershell.exe where Windows keeps it when a service's PATH lost the Windows directories, so on WSL it can still attach a board, load it over PICOBOOT or write the UF2 through Windows.

[0.2.3] - 2026-11-13

The 1-Wire bus runs each bit slot and the presence sample with interrupts off: a USB or Wi-Fi interrupt inside a slot stretched it, which read as a failed CRC or a missing presence pulse from the DS18B20.

[0.3.0] - 2026-11-14

The board key is kept in the last two flash sectors, reserved at link time. A production preset signs the image and lists the OTP steps, which rho flash --production runs only when confirmed. Host tests configure without the SDK.

[0.3.1] - 2026-11-14

The platform carries the udev rule a user needs to flash a board in BOOTSEL (udev/60-robohub-pico.rules, declared in system_deps, reported by rho doctor, installed by rho keeper install). When picotool finds the board but may not open it, the flash says so and names the command that installs the rule, before it falls back to the bootrom's drive.