Skip to content
gunkslab

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.

Everyone's own e-stop: each driver sets and clears their own, an admin may
clear anyone's, and every bot stays stopped while any is on

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.