Home

radio-robot-lib

Hardware-agnostic C++/Python library pair for commanding a differential-drive robot over an ASCII radio/serial link — protocol v6, DiffDrive wheel kernel, and a host client, all testable on a laptop with no robot attached.

Two independent halves — a DiffDrive wheel control kernel and a protocol v6 line-grammar handler — meeting at exactly one seam, DiffDriveAdapter. Neither talks to a specific board; a MicroPython firmware image and a MakeCode package each embed them separately. A Python host client (robot_v6) and a compiled no-hardware simulator (tools/sim) make the whole link testable without a robot.

Code: https://github.com/League-Robotics/radio-robot-lib

Pages

• Overview — what the library is, what ships in it, and how its layers stack. Start here.
• Specification — consolidated index of every normative rule, each cited back to the canonical doc that owns it.
• Protocol — the v6 ASCII line grammar, handler, adapter contract, and sequence-id reliability layer. The wire authority.
• Radio addressing — channel and group from the board's name, decoded to a number and reduced by modulo: channels 11–83, groups 15–255. Adopted by microbit-radio-relay; replaces the 25-channel name map.
• Motion API — the six motion operations a program calls, and the three ways they can be executed.
• DiffDrive — the differential-drive wheel kernel: the control law, its caller contract, and its fidelity gate.
• WiFi link — dual-plane TCP-REPL + UDP-protocol over one AT module, as measured on the bench.
• Use cases — actor-by-actor use cases, each citing the canonical section it is drawn from.

Things to remember

• The protocol doc is the wire authority. Where any other page appears to disagree with Protocol about the grammar — spaces, #id, case-as-direction, the outcome model — the protocol page wins and the other page is the defect.
• The handler owns every wire byte; the adapter never parses or writes one. That boundary is what makes both halves testable in isolation.
• DiffDrive speaks encoder counts, never millimetres. No chassis geometry and no configuration storage live inside the kernel — those are the adapter's problem.
• Case is structural. Commands and replies are separated by case so a robot's own output can never be read as a command on a shared radio channel.
• Loss is designed for, not patched around. Mandatory strictly-incrementing sequence ids plus cumulative ack/nack. Measured per-line delivery on ch4 ranged 66.5–83.3% against a 99.5% wired control, and is unstable (protocol §8.0) — the older "~5% loss" figure is withdrawn as unsupported.
• One motion verb has real kinematic effect today: WHEELS_V. The other five (WHEELS_X / MOVE_X / MOVE_V / GO_TO_R / GO_TO_W) decode and dispatch correctly but have no planner behind them yet.
• This wiki is the published source of truth. It is generated from docs/design/*.md in the code repo — edit there and republish, or edit here and carry the change back; do not let the two drift.

Open tasks

• FUNCS — enumerate the RUN registry.
• HELLO banner: emit the specified colon announcement format.
• Kill the ack barrage — make ack/nack reply-only.
• v6 reliability layer: unsequence the query verbs and close three query-side gaps.
• Planners behind the five decoded-but-inert motion verbs.
• Implement the wifi-link design against this library's own transport (specified and bench-proven in a sibling firmware repo, not yet built here).
• Deferred, not scheduled: a rogo serve relay daemon, a camera-based --auto calibration mode, and go_to_w's world-frame pose source.

Update this page whenever you add a page or finish a task.