This page was generated from the source of RoboHub. Edit the source, not this page.
The RoboHub wire protocol in one place: the identity and message families both levels share, L2 between a board and its gateway, L1 between gateways, and the gateway's whole wire, copied into every consumer and regenerated there by one tool.
robohub-protocol
The RoboHub wire protocol, written once. A board, a gateway and a relay each
generate their payloads from these schemas with rho protocol generate; this
module is where the schemas are edited, and the copies every consumer keeps are
written from it.
| Schema | Level | Who generates it |
|---|---|---|
common.rho | both | included by the others: the device and gateway identity, MessageId, diagnostics, control, PowerReading, StateReading, SensorReading |
link.rho | L2, board ↔ gateway | a node: Hello, Telemetry |
uplink.rho | L1, gateway ↔ gateway | a relay: Announce, Reading |
gateway.rho | both | a gateway, which speaks both levels |
One MessageId numbers the whole wire. A message that has a name at each
level is one number: HELLO and ANNOUNCE are both 0x0101, TELEMETRY and
READING both 0x0201.
RELAYED (0x0013) is a board's frame carried whole by a relay that holds no
key of the board's: port(u8) | inner_msg_id(u16) | inner_tx_id(u16) |
inner_payload, sealed under the relay's own session. Its payload runs to the end
of the frame, so it is written out in common.rho rather than declared as a
message; the gateway and the C relays read and write it by hand.
REKEY (0x0014) and REKEY_ACK (0x0015) rotate a board's key to its next
epoch, sealed under the board's current session and never plain:
new_epoch(u32) | wrapped(16) from the gateway, and new_epoch(u32) | proof(8)
back. The key derivation and what each field is are in common.rho and in
robohub/docs/architecture/security.md.
SESSION_RESET (0x0016) asks a board to drop its session and say hello again.
It is only ever sent sealed, gateway to board, under the session it ends; its
payload is empty or one reason byte (1: the gateway restarted). A gateway sends
it for a session it restored after a restart, whose upward counter it could only
place past a safety margin.
Changing the protocol
- Edit the schema here, in
schemas/. - Run
tools/sync.py. It copies the schemas into every consumer listed in
consumers.ymland runsrho protocol generate --platform robohubthere, so
the generated C or Rho is the new protocol's. - Build and test each consumer, and commit it with its new copy.
tools/sync.py --check changes nothing and exits 1 when a copy or a generated
file is not what the source makes: a schema edited in a consumer, a generated
file edited by hand, or code generated by an older toolchain. A consumer that is
not checked out is passed over.
Consumers
| Consumer | Carries | Generates |
|---|---|---|
robohub-gateway | all four | Rho, from gateway.rho: src/gateway/wire |
robohub-devices/runtime/device-node, nodes/gateway-node | common, link | C: src/protocol |
robohub-drivers gateway examples (relay, relay-host, uplink-host) | all four | C: src/protocol |
robohub-drivers repeater and the DS18B20 telemetry node | common, link | C: src/protocol |
consumers.yml is the list tools/sync.py reads: each consumer's path, the
schemas it carries, and what is generated where. A consumer keeps its copy in its
own schemas/ directory, byte for byte the source's.
This is not an interface an application calls. Applications reach readings
through robohub.gateway (see robohub-gateway-contract/index); the wire is
what boards and gateways speak (see robohub-gateway/index).
Release history
[1.0.0] - 2026-11-14
The wire protocol has one source: the schemas the gateway carried — common, link, uplink and gateway, namespace robohub.v1 — moved here, with consumers.yml naming the eight places they are generated from and tools/sync.py writing every copy and regenerating its code. The two robohub-devices nodes had fallen behind: their copies lacked SensorReading and their generated code lacked the PLUG device kind; both are the source's now.
[1.1.0] - 2026-11-14
RELAYED (19): a relay carries a board's handshake and sealed frames unchanged inside its own sealed frame, so the gateway checks the board itself and a relay can only drop or delay.
[1.2.0] - 2026-11-14
REKEY (20) and REKEY_ACK (21): a gateway hands a board its next key sealed under the current one, and the board confirms with a proof made under the new key.
[1.3.0] - 2026-11-14
SESSION_RESET (22): a gateway that restarted asks a board, sealed under the session it restored, to start a new session.