Guides
Troubleshooting
What goes wrong, and what fixes it. For flashing problems (no port, stuck at “Connecting…”), see Flash a bot.
The simulated fleet
Start with ./gunkslab doctor. It checks the container runtime, the ports (1883, 9001, 8080), what’s running
and what’s left over, and for each problem prints FIX and what to do. Whatever it is, ./gunkslab down && ./gunkslab up puts it right; down keeps each piece’s log in logs/ first.
port 8080 (the page) is taken by ...: another program holds it. Stop that program; if it’s an old gunkslab,./gunkslab down.not running: stationwhile the rest run: it crashed.logs/gunkslab-station.logsays why, after./gunkslab down(or./gunkslab logs, without stopping anything).stopped containers left over: a crash, or the machine restarting, left a stopped container holding its name../gunkslab downclears it.
Apple container is installed but not running, or docker is installed but not answering: start the
runtime.
macOS
container system start
Or start Docker Desktop, if that’s the one you use.
Ubuntu / Debian
docker runs as a service. Start it, and have it start with the machine:
sudo systemctl enable --now docker
If it’s running but docker info says permission denied, you’re not in the docker group yet. Add yourself as
Install says, then log out and back in.
podman has no service, so it has nothing to start.
RHEL / Fedora
podman has no service, so it has nothing to start. If the doctor says podman is installed but not answering,
podman info says why.
Windows
Start Docker Desktop. If it’s running and the Ubuntu shell still can’t reach it, turn on Settings, then Resources, then WSL integration for Ubuntu (Install).
A real bot
Nothing moves, no errors. EEP/SLP isn’t high. This is the single most
common DRV8833 bring-up mistake. The chip sits in sleep and reports nothing.
Bot resets when it accelerates. Brownout: four motors starting at once sag the 9V faster than its boost converter recovers, and the ESP32 reboots. Fit the 470–1000 µF capacitor across the ESP32’s supply, physically close to its VIN/GND pins. If it persists, the pack’s converter is current-limited. Measure before buying anything.
One side runs backwards. Swap that side’s two motor leads, or swap its
two pin numbers in main.cpp. Don’t fix it in the coordinator; the bots must
stay interchangeable.
Motors fight each other on one side. Mismatched gear ratios wired in parallel. The faster motor drives the slower one. Keep the ratio consistent per side, ideally fleet-wide.
Flaky WiFi on one bot only. Its antenna may be sitting over the steel motor cans. The board’s mounting holes are symmetric, so rotate it 180° to swing the antenna over the battery bay instead.