Concepts
The protocol's design
How bots, the station and the position service talk: over MQTT today, and written so another transport could carry a fleet (what it needs from one). The simulator, the station, the driving tool and the page speak it, and so does the firmware, though it hasn’t run on a bot yet.
v0 is deliberately small: drive a bot by hand, see it, stop it, tell the bots apart, and find out why one stopped. That covers the simulator’s first steps (one fake bot driven from the laptop, then the web page). Tasks, waypoints and speed control come in later versions, one at a time.
The full reference, every topic and rule, is Protocol v0.
Versions in the topics
A new version of the protocol gets new topics (gunkslab/v0/..., then v1), so bots on two versions can share one
broker while they’re updated, and a fleet ID in every topic keeps fleets apart. Those rules are in the
reference’s topics.
Changes from the firmware before v0
| Before | v0 |
|---|---|
fleet/<id>/cmd, /telemetry, /status |
gunkslab/v0/<fleet>/<bot>/… |
status is the bare text online / offline |
{"state":"online"} / {"state":"offline"} |
no hello |
hello, retained, on connect |
| no e-stop | everyone’s own estop/<name>, retained; the fleet stops while any is on |
telemetry carries id |
dropped: the ID is in the topic |
| telemetry has no stopped flag | stopped (optional) |
| no command numbers | seq on cmd, echoed in telemetry (optional) |
| no events | event: boot with the reset reason, timeouts, e-stop, reconnects |
| no identify | {"identify":true} |
| no distance sensor | range_m in telemetry, the reflex, obstacle_stop and edge_stop (rule 9) |
| no IMU readings | heading in telemetry, from the bot’s own gyro (rule 4), added 2026-10-21 |
| stall and battery only in the serial log | stall_stop, battery_low, battery_empty, and battery in telemetry (rule 10), added 2026-10-22 |
cmd keeps the old {"l","r"} and {"stop":true}, with seq added as an option. The firmware was brought up to
v0 on 2026-10-03, and publishes at the QoS the protocol asks for since 2026-10-04.
Not in v0
These come later, one at a time:
- speed and turn-rate commands, and drive a distance or turn an angle;
- tasks, waypoints and routes;
- battery state of charge;
- IMU readings beyond the heading (tilt, acceleration);
- TLS to the broker (backlog F4.2; the cluster’s broker has logins);
- firmware updates over the air;
- cameras.