Skip to content
gunkslab

Reference

Firmware

The code that runs on each gl_zero, the first bot (firmware/src/gl-zero). One binary, flashed unchanged to every one of them. Each names itself from its own MAC address at boot, so there are no per-bot builds or config files to keep straight.

It speaks protocol v0 (the protocol). It hasn’t run on a bot yet. It builds, and its protocol rules pass their tests on a laptop. It’s written for gl_zero’s v31 circuit: its pins come from the car’s pin map (include/gl_zero_pins.h, written by bench/pins.py from the soleil repo’s pins.json), as Pirate Stage’s do. The first wired one is where the Wi-Fi, the motors, the battery reading and the sensors get proven. Values the bench hasn’t measured yet are named constants at the top of main.cpp: which way each side turns (MOTOR_FLIP_L, MOTOR_FLIP_R), the battery reading’s correction (VBAT_RATIO, or vbat-ratio over serial), and which way the sensor’s cells face (TOF_FLIP_ROWS, TOF_FLIP_COLS). The stall cutoff’s are in lib/chassis (STALL_*, below).

Building and flashing is a guide.

Pirate Stage’s firmware is started beside it (pio run -e pirate-stage). It has the car’s boot order, motors, encoders and battery, the IMU’s heading, the cliff sensors, and protocol v0 with the same rules (lib/agent, the reflex at both ends). It says hello as pirate-stage with encoders and an IMU, and its telemetry carries batt_v, heading, its wheels’ travel (odo_l_m, odo_r_m, once the encoders are measured) and its own dead reckoning from those (odo_x_m, odo_y_m). Its gyro’s scale is measured once by hand and kept in flash (gyro-cal over serial). What it does so far is on the Pirate Stage page. The rest of this page is gl_zero’s.

MQTT

Protocol v0, all of it. The protocol is the reference. The bot is bot-<last 3 bytes of its MAC>, e.g. bot-a4cf12, under gunkslab/v0/<fleet>/, the fleet from bot_config.h:

topic direction
<bot>/hello bot → retained, on every connect: type, firmware, sensors (tof if the sensor answered at boot), and with a certificate, the day it runs out (cert_until)
<bot>/status bot → retained {"state":"online"}. The broker sends offline, its last will
<bot>/cmd → bot {"l":0.6,"r":0.6}, {"stop":true}, {"identify":true}, each with an optional seq
<bot>/telemetry bot → 10 Hz: power, seq, stopped, Wi-Fi, free memory, and range_m, ranges, ranges_age_ms and reflex with the sensor. Pirate Stage’s also batt_v, battery, heading, range_rear_m and reflex_rear from its rear cliff sensor, and odo_l_m, odo_r_m, odo_x_m and odo_y_m once its encoders are measured
<bot>/event bot → boot (with why it restarted), timeout_stop, estop_on / estop_off, wifi_reconnect, mqtt_reconnect, obstacle_stop, edge_stop. Pirate Stage’s also stall_stop, battery_low, battery_empty, and "end":"rear" on a stop from its rear cliff sensor
estop/<who> → every bot everyone’s e-stop, each retained; the bot reads them all (estop/+)
<bot>/sync bot → bot its marker, {"marker":"<16 hex digits>"}, new on every connect

On each connect it reads the e-stops and its own sync first, sends a new marker to sync, and reads cmd only once that marker comes back, so every e-stop in force has reached it before any command (the protocol, rule 1). The serial monitor says waiting for its marker, then marker back, then taking commands. If the marker isn’t back in 10 s it says so once and takes no commands on that connection.

On the serial monitor it says who it is, whether the sensor answered (and what an empty desk should read), and every message it refuses.

With MQTT_CA in bot_config.h (the cluster’s broker), it connects over TLS, checking the broker’s certificate by broker.gunkslab.internal, and logs in with a certificate of its own (lib/brokertls). It makes its key, prints a request for it (cert-request over USB), and keeps the certificate pasted back (cert), checking it’s for itself, its key and the fleet’s CA. Without MQTT_CA, plain MQTT and no login, for the development broker. Logins and certificates walks through it.

Motors

Each side’s power rises over 150 ms from a standstill to full (agent::Ramp, RAMP_MS), so a start or a reversal doesn’t pull the stall current from the battery all at once. The pack’s protection board can cut out on it. Slowing down and stopping are immediate, so a stop, the e-stop and the 500 ms timeout are never delayed. A reversal drops to zero first, then rises. Telemetry reports the power the rules ask for, not the ramped power.

The distance sensor

gl_zero’s VL53L1X sits level in its nose pod, its lens 33 mm above the desk. The firmware reads it as five regions of interest, as the simulator does: each a small patch of the chip’s cells, about 15° across. bottom is aimed 6° down at the desk ahead, middle and top straight ahead and up, left and right to each side. It takes one reading every 20 ms, bottom every other time, so the edge is watched every 40 ms and the rest take turns between.

The reflex (lib/agent) is the simulator’s:

  • bottom reading long, or nothing back, twice running: the desk ends ahead.
  • Any region reading nearer than bottom’s empty desk, twice running: something is in front.

Telemetry’s range_m is bottom’s reading, ranges has each region’s last one for the station, and ranges_age_ms how long ago each was read. Which cells look which way hasn’t been tried on a sensor yet: the bench check settles it.

The battery

gl_zero runs on a 2S pack, read on GPIO 32 through a 100k / 33k divider: the mean of 32 readings, ten times a second. It warns at 7.0 V (battery_low) and stops the motors at 6.8 V (battery_empty), 3.5 and 3.4 V a cell; a reading has to hold a second to count, so a motor start’s dip doesn’t. Both latch. Empty is kept in flash, so a restart doesn’t drive an empty pack further, and clears only once the pack reads 7.4 V, charged. The rules are Pirate Stage’s (chassis::BatteryGuard), with gl_zero’s thresholds. Telemetry carries batt_v and battery, and l and r read 0 while it’s empty (rule 10).

The stop was 6.6 V before gl-zero-0.8.0. The carrier board’s circuit simulation has all four motors stalled from 6.6 V pulling the ESP32’s 3.3 V supply to 2.86 V, under its 3.0 V rating; from 6.8 V it holds 3.06 V. That’s simulated, not yet measured on a board.

The rear sensor

A second VL53L1X in the ToF module at the rear, the same socket and aim as the front one. Both boards answer at 0x29 when they power up, so the firmware holds the rear one off (its XSHUT, GPIO 13), moves the front one to 0x30, then lets the rear one up at 0x29. The rear is read as one beam, its bottom region alone: it holds back reversing, as the front holds back driving forward, and its hello lists tof-rear (rule 9). After a restart with the power left on, the front board is still at 0x30: the firmware soft-resets it and starts it wherever it answers. A front board that answers but doesn’t start stays at 0x29, and then the rear one is kept off rather than brought up beside it.

The encoders

Each motor’s encoder is counted in hardware by the ESP32’s pulse counter (PCNT), every edge of both channels, as Pirate Stage’s are. Nothing uses the counts yet: status over serial shows each one’s total since boot. hello doesn’t list encoders, as that promises an odometer in telemetry, and that needs a wheel turn’s counts, which aren’t measured. Which way each one counts for forward (encSign) isn’t measured either.

The counter’s glitch filter is on, ignoring pulses under 1.25 µs. Powering up ADC1 for the battery reading pulls GPIO 36 and 39 low for about 80 ns (Espressif’s ESP32 errata), and those are the front right and rear left encoders’ first channel. Counted without the filter, each battery reading could add a false count. At full speed on a full pack, each channel’s pulses last about 0.2 ms, over 100 times the filter. That’s worked out from the motors’ 105 RPM rating, assuming a usual N20’s 7 pulses a motor turn and about 150:1 gearing (neither is recorded), not measured.

The driver’s fault line

The DRV8833 pulls its ULT line (GPIO 34) low on overcurrent or overheating, and cuts its own outputs. The firmware keeps the motors off once it has held for 5 ms (chassis::FaultLatch), rather than letting them lurch back on the driver’s retry, until the station asks for nothing, and sends stall_stop with motor drv: one line for all four motors, so it can’t say which. status over serial shows the line.

The stall cutoff

gl_zero has no current sensing, doesn’t use its encoders yet, and the driver’s fault line doesn’t see a motor stalled at its normal stall current, which can heat its printed clamp. So the firmware listens for the motors with the IMU (the GY-521 on the same bus): a turning motor buzzes through the car, and a stalled one is silent. A car driving straight at a steady speed is also still to the IMU, so it’s the buzz that tells, not the car moving.

A quarter-second at a time (chassis::BuzzGuard), the motors driven but nothing heard, or driven straight while the car keeps turning (one side stuck, the other driving it round), counts as stalled. Stalled time adds heat, more for more power, and other time takes it away slowly. At about 3 s of a full-power stall the motors go off and stay off until the station asks for nothing, and the firmware sends stall_stop with motor imu. The heat stays across that, so a retry into the same wall stops again quickly. status over serial shows the IMU, the cutoff and its heat.

Its numbers (STALL_* in lib/chassis/chassis.h) are starting points, set to stop too easily rather than miss, until the gz-stall bench program measures a still car, a turning motor and a held one. It can’t catch one motor stuck while the other three turn, one side stuck while the other only slips, or wheels spinning against a wall. With no IMU answering, the car drives without it and says so at boot and in status; the same if its samples stop for a second while driving, until they come back (it sets the chip up again each second, so one that reset comes back too). gl_zero’s hello doesn’t list imu: that promises a heading, which it doesn’t send.

The loop’s watchdog

The dead-man, the reflex and the stall cutoff all run in the firmware’s main loop, so a loop that hung would leave the motors on whatever they were last set to. A watchdog restarts the ESP32 if the loop doesn’t come round for 15 s (LOOP_WDT_S, gl-zero-0.7.0 on, as Pirate Stage’s). The restart is like a power-up: the firmware puts the driver to sleep and the motors off in its first lines. The longest a working loop holds is a broker that’s slow to answer, about 8 s and some over, motors off throughout, so 15 s leaves room. The watchdog starts once Wi-Fi is up (the wait for it has no end), and an over-the-air update switches it off while it runs. A watchdog restart’s boot event says watchdog.

To check it on the bench: point MQTT_HOST in bot_config.h at an address with no broker, flash it and watch the serial monitor for two minutes. It keeps saying [mqtt] TLS failed ... retrying, and never [boot] again: the longest a working loop holds doesn’t trip it. Nothing in the firmware hangs its loop on purpose, so the restart itself isn’t something you can make happen.

Known gaps

  • Secrets sit unencrypted in the bot’s flash. Its Wi-Fi password, update password and broker key are kept there. Anyone holding a bot can read them out over USB (all three are that bot’s alone, on the bots’ own network, and each can be taken away). Flash encryption would fix it, at the cost of a harder first flash. It isn’t done.
  • The sensor’s numbers are from gl_zero’s CAD, not measured. An empty desk should read about 0.14 m in bottom (the serial monitor says what it expects). If it doesn’t, bottom’s aim in main.cpp (TOF_DOWN_DEG) is the number to fix.

Size and headroom

The build is 1,023 KB, 78% of an app slot (2026-11-09, with the battery, the rear sensor, the driver’s fault line, the stall cutoff, the loop’s watchdog and the encoders). The update code is always in it now: before each bot had its own password, CI’s build, with the example’s placeholder, left it out. The WROOM-32 has 4 MB of flash, but OTA needs two app slots, so the real ceiling is the partition size: 1.25 MB per slot on the default scheme. RAM is at 16%.

A camera driver would push a build toward 1.1–1.2 MB and crowd the default partitions. The fix then is the minimal-SPIFFS scheme (~1.9 MB slots).