Concepts
Safety
A bot that moves can hurt something, so safety doesn’t depend on any one piece working. The bot stops on its own when commands stop, obeys the fleet’s e-stop directly, and won’t drive into what its sensor sees, with or without the station. The station adds its own dead-man and a guard. The rules themselves are in the protocol reference; this is how the firmware carries them out, and why. Every stop in one table: Every stop. A one-page version to print: the safety sheet.
On the bot
Command timeout (500 ms). If the station goes quiet (a dropped packet,
a crashed pod, a Wi-Fi hiccup), the bot stops and says timeout_stop. The station
sends commands continuously, not once: a bot that receives {"l":0.5} and
nothing else stops half a second later.
The e-stop. Everyone has one of their own, estop/<their name>. While
anyone’s says stop, every bot stays stopped and ignores commands, identify
included (that only blinks the LED). Clearing yours doesn’t clear someone
else’s: on the cluster’s broker, only they or an admin can. After the last is
cleared, a bot waits for a fresh command.
The reflex. With the sensor fitted, the bot won’t drive forward into
something closer than the desk ahead, or off the desk’s edge: it drops the
forward part of its wheel commands, still turning or backing off when told.
Backwards it has no sensor, unless it has a rear one too (tof-rear: Pirate Stage), which
holds it back from reversing the same way.
Updates over the air need the bot’s own password. Until it has one, typed in
over USB (Logins and certificates), the
bot doesn’t listen for updates at all: USB only. Otherwise anyone on the Wi-Fi
could flash their own code onto a bot. Each bot’s is its own, so one bot’s doesn’t
open another. The serial monitor says which: [ota] on, with this bot's own password or [ota] off.
A silent sensor counts as the edge. If the sensor stops giving readings for 200 ms, the bot holds back as if the desk had ended ahead, rather than drive on blind.
QoS as the protocol asks. hello, status and events go out at QoS 1, so
the broker acknowledges them; telemetry, ten times a second, at QoS 0. A QoS 1
publish waits at most 250 ms for the acknowledgement, half the command timeout.
(arduino-mqtt since 2026-10-04; PubSubClient, before it, could only publish at
QoS 0.)
Motors down before the driver wakes, and during a reconnect. The ESP32
floats its GPIOs during boot, so the firmware holds EEP/SLP low, sets every
PWM channel to zero, and only then wakes the DRV8833. Otherwise a bot can
twitch on power-up. A try at reconnecting to the broker blocks for a moment,
so the motors go off first.