Bob

BleRiot

BleRiot is a compact request/response protocol for reading and writing named integer registers on low-power RF nodes. A Linux hub polls the nodes and bridges their registers to an external Registry service. Registry change requests become idempotent absolute register assignments.

The radio uses GFSK with BLE Coded PHY framing: S8 provides about 125 kbps for maximum range, while S2 provides about 500 kbps at shorter range. It is not a standard BLE connection: BleRiot selects raw RF channels and uses its own fixed packet, addressing, transaction, and encryption rules.

Architecture

Registry service
       ^  provide values / consume assignments
       |
Linux hub: lib/site
  - inventory and per-node XTEA keys
  - one polling scheduler per RF channel
  - retries, liveness, Registry publication, diagnostics
       |
       | USB HID
       v
MCP2210 --SPI-- PAN211x radio   one passive dongle per active channel
       |
       | BLE-compatible raw RF framing (S8 ~125 kbps / S2 ~500 kbps)
       v
nodes sharing that channel

Each independent group uses one half-duplex RX/TX radio channel. The hub permits one in-flight GET or SET transaction on a channel, including its retries and reply wait. Different channels have independent transaction lanes and run concurrently.

The MCP2210 dongle is a passive USB-to-SPI bridge driving a PAN211x. It has no microcontroller, firmware, keys, or protocol state. All protocol and scheduling logic runs on the Linux host.

Protocol Summary

Every packet is 13 bytes: a four-byte plaintext source address, a one-byte plaintext packet version, and one XTEA-encrypted eight-byte block containing type, flags, register tag, and raw int32 value. The four packet types are:

There is no transaction token. Channel ownership serializes requests, and the hub accepts a reply only when its source, register, and response type match the active transaction. See the authoritative protocol specification for packet fields, pacing, retry, and register semantics.

Repository Layout

Register identity is a permanent, nonzero per-device-type uint16 tag. Deployments are ordinary Go inventory.Inventory values; there is no JSON descriptor. bleriot node build generates the TinyGo entry point that bakes one instance's address, key, channel, spread factor, and config into its firmware.

Quick Start

Run the reference hub against a Registry service:

cd example/bob
go run ./cmd/dev hub --registry http://localhost:8080 --sweep-interval 1s

The hub discovers MCP2210 dongles and assigns them to inventory channels. It starts with no dongle attached and brings channels online as dongles appear. Install the shipped udev rule first so the hub can use /dev/hidraw* without root; see USB access.

Useful optional flags include --timeout 50ms, --retries 3, --diagnostics bleriot, and --diag-interval 1s. The persistent --debug flag may appear before or after the subcommand:

go run ./cmd/dev --debug hub --registry http://localhost:8080 --diagnostics bleriot

Create and flash an inventory identity from the reference module:

cd example/bob
go run ./cmd/dev node new
go run ./cmd/dev node build --name bob --flash --rtt

node new works offline and prints an inventory.Instance stub with a random nonzero address and XTEA key. node build selects the inventory instance, generates its baked firmware entry point, and follows the build and pyOCD policy declared by the device type's firmware manifest.

The reference firmware exposes bob.led as the single writable LED register; it controls the green LED. The red LED is reserved for connection status: off while hub packets are arriving, and a 200 ms pulse once per second after five seconds without a packet.

Documentation

• Protocol specification: authoritative wire format, RF, transactions, reliability, register model, and identity.
• Host library: inventory, commands, polling scheduler, Registry behavior, USB access, and diagnostics.
• Diagnostic metrics: schema 10 catalog, accounting rules, and Prometheus examples.