RoboHub

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.

SchemaLevelWho generates it
common.rhobothincluded by the others: the device and gateway identity, MessageId, diagnostics, control, PowerReading, StateReading, SensorReading
link.rhoL2, board ↔ gatewaya node: Hello, Telemetry
uplink.rhoL1, gateway ↔ gatewaya relay: Announce, Reading
gateway.rhobotha 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

  1. Edit the schema here, in schemas/.
  2. Run tools/sync.py. It copies the schemas into every consumer listed in
    consumers.yml and runs rho protocol generate --platform robohub there, so
    the generated C or Rho is the new protocol's.
  3. 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

ConsumerCarriesGenerates
robohub-gatewayall fourRho, from gateway.rho: src/gateway/wire
robohub-devices/runtime/device-node, nodes/gateway-nodecommon, linkC: src/protocol
robohub-drivers gateway examples (relay, relay-host, uplink-host)all fourC: src/protocol
robohub-drivers repeater and the DS18B20 telemetry nodecommon, linkC: 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.