Skip to content
gunkslab

Guides

Flash a bot

Build gl_zero’s firmware, flash it onto the bot’s ESP32 over USB, and update it over the air after that. For a first bot on the bench end to end, with the broker it talks to, see Put a real bot on the bench.

gl_zero is still being designed. Its electronics are an ESP32 devkit, a DRV8833 motor driver, an IMU, a distance sensor at each end and four N20 motors on a 2S lithium pack. They haven’t driven a motor yet. The firmware builds and its protocol rules pass their tests, so the steps here flash a board, but nothing on this page has run on a built bot.

Check it builds, and run its tests, with nothing installed but a container runtime, from the repo’s top folder:

scripts/firmware test        # the protocol rules (lib/agent) on this machine, and every message checked against the schemas
scripts/firmware build       # compile it for the ESP32

CI runs both on every merge request.

To flash a bot you need PlatformIO on this machine, since a container can’t reach the USB port. Once per board, over USB; after that, updates can go over the air, once the bot has its own password for them.

  1. Install PlatformIO as Install says for your OS.
  2. cp include/bot_config.example.h include/bot_config.h and fill in your Wi-Fi’s name, the broker’s address and the fleet. The Wi-Fi’s password goes into the bot over USB after flashing (A bot’s Wi-Fi), not here. For the development broker on this machine, start it in bench mode (scripts/broker up --lan): it prints the address to use. Plain scripts/broker up only listens on 127.0.0.1, which a bot can’t reach. Either way, MQTT_PORT is 8883 and MQTT_CA the CA scripts/bot-cert ca prints (the cluster’s with VAULT_ADDR set, this machine’s without), and the bot gets its certificate over USB after flashing: Logins and certificates. Put a real bot on the bench walks through it all. bot_config.h is gitignored, so credentials never get committed. (Not config.h: the ESP32 framework has one of its own, which gets picked up instead when ours is missing.)
  3. Plug the board in, from firmware/:
pio run -e gl-zero -t upload   # build + flash
pio device monitor           # 115200 baud

Over the air, to a bot that has its own password for updates and the key they’re signed with (Logins and certificates gives it both), with its address from the serial monitor or the router:

scripts/bot-ota upload bot-xxxxxx 192.168.1.50

It builds, signs and sends. The password and the signing key are in Vault (bench mode: this machine), never a file in the repo. The bot checks the signature before it restarts into the new firmware, and keeps what it had if it’s wrong.

Without bot_config.h it still builds, with the example’s placeholder Wi-Fi and broker, and says so with a warning. That’s what CI builds; it’s no use on a bot.

If the port doesn’t appear, see Install for your OS: the USB-serial driver on macOS, the dialout group and brltty on Linux, usbipd on Windows. pio device list shows the ports it can see.

If upload stalls at “Connecting…”, hold BOOT, tap EN, release BOOT. Most devkits auto-reset and never need this.

Unplug the battery while flashing. USB 5 V and the pack both on the rail isn’t dangerous, but a motor twitching during a bootloader reset is an annoying way to lose a session.