Skip to content
gunkslab

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.