Skip to content
gunkslab

Project

The roadmap

Everything the fleet software has to do, in one place. Each item has a status.

  • decided. Settled.
  • proposed. Suggested, not agreed yet.
  • open. A question to answer first.
  • built. Done, with the day it was.

Started 2026-10-02.

At a glance

Works today Next Later
Simulated bots on your own machine, started with one command One real gl_zero driven from the cluster (F6.2), once it’s built Pirate Stage with its first module, Canterbury
Driving from a page in the browser, with a gamepad or by clicking where to go Pirate Stage on its own, the twelve checks of milestone 1 Tasks from the station: routes, patrols, a queue
Bots giving way to each other, checked by scenarios The overhead camera measured on a real desk Brains, computers that ride on a car and drive it
Recording a run and playing it back A fleet that keeps working without the station
Firmware for gl_zero and Pirate Stage, built and tested in CI. Neither has driven on the cluster yet
Primers on MQTT, ROS 2, the ESP32, time-of-flight sensors and batteries, beside tutorials 01 to 10

Below is the detail. Every area, its status, and the order to build it in.

Who it’s for (decided, 2026-10-02)

Two audiences. People with a small fleet on a desk, and education and research at a larger scale.

  • Desk users. A small fleet on a desk. Simple to install, simple to run.
  • Education and research. Bigger fleets and mixed robot types, run from one orchestration station.

It’s built for one operator first, with room to add more later.

Complexity is added one piece at a time, each after the last is cleaned up.

Ground rules

  • Automatable and portable (decided, 2026-10-02). Everything has to be automatable and portable to any OS. Everything runs from scripts in the repo, nothing is installed by hand on one machine, and every service runs in a container. That’s Apple’s container on macOS, docker or podman anywhere else.

  • Wi-Fi only (decided, 2026-10-02). Every bot, the broker and the operator share one network. It keeps things simple. Cellular is parked, at the end of this page.

  • The bot does the low-level work, and the cluster coordinates. The bot runs motion primitives, its own reflexes and its safety. The coordinator, tasks, records and dashboard run on the cluster. They talk over MQTT.

  • One protocol for all three machines. gl_zero, then Pirate Stage, then Soleil. The hardware differs. Soleil runs a Jetson, not an ESP32, so they share the message protocol, not one firmware.

Control side, the cluster and the operator

Area What it covers Status
Broker Mosquitto on the cluster, LAN only (backlog F6.1) built 2026-10-13. The cluster’s deployment is the lab’s own, kept privately. This repo has the development broker and its bench mode, with the same rules (broker/acl)
Security A login per bot, TLS, signed firmware updates, who may send commands (backlog F4.2) logins and who may send what, built 2026-10-13 on the cluster’s broker. TLS and signed updates are open
Fleet registry Which bots exist, their type, what each can do, settings, firmware version built, in memory, in the station (station/fleet)
Manual driving Drive one bot by hand from a web page, with a gamepad when one is plugged in. A speed cap per bot, and a dead-man switch built. The page’s drive panel and scripts/drive. The cap is fleet-wide for now
Tasks Go to a point, follow a route, patrol. A queue, priorities, taking a task back go to a point is built (goto). The rest is proposed
Task allocation Which bot gets which task proposed
Position On the desk, the overhead camera and ArUco markers (backlog F6.3). Pirate Stage adds encoders and IMU. Soleil uses GPS and cameras built 2026-10-24 for the desk. position/ (the guide), tested on drawn desks, not yet against a real camera
Coordination Bots keeping clear of each other, right of way proposed
Safety Fleet-wide e-stop and per-bot stop, low battery, no-go zones proposed
Docking and charging A bot drives onto its dock when its battery runs low or the queue is empty, the dock confirms it’s charging, and tasks are planned round the charge. Needs a dock and charge contacts on the car, planned with the car’s hardware proposed
Telemetry Battery, signal, position, faults, stored over time proposed
Recording Record a run and play it back to debug it built 2026-10-22. scripts/record saves a fleet’s messages to a file, to read as text or play back into another fleet for the page
Training sets A recording cut into episodes, each a task with its start, its end and whether it worked, in a format robot-learning tools read. The bot’s commands, odometry and IMU and the overhead camera’s positions, on one clock. A brain adds its own sensors (Brain side, Recording) proposed
Updates Firmware over the air, settings pushed, one bot first, roll back proposed
Dashboard Map with the bots, their health, tasks and controls proposed
Video Cameras are in the plans, but later, after the simple version is clean decided, later
Simulator Fake bots that speak the protocol, to build the coordinator without hardware built. sim/, gl_zero and Pirate Stage
Simulated bots while it runs Adding and removing simulated bots without restarting the simulator built 2026-11-03. --manage. Each bot’s distance sensor tests only what’s in its range and cone, so 30 bots keep up in real time
What the sensors find The station remembering what each bot’s distance sensor finds, and planning go-tos round it built 2026-10-30. gl_zero’s sensor is read as five regions, by the simulator and the firmware alike. Parked bots are kept apart by their outlines (2026-11-01), and a goal near the desk’s edge is lined up for or refused at once (2026-11-02)
Certificates running out Each bot says when its certificate runs out built 2026-10-30. The station and the page warn 60 days ahead
Classroom Running a class on one shared fleet: sign-in, a bot each, stops, missions and playing a session back built 2026-11-05. A first version, on our own cluster with simulated bots only. Not open to anyone yet. Real bots and selling it per site are planned

Bot side

Area What it covers Status
Motors gl_zero sets power open loop. Pirate Stage holds speed with its encoders (PID). Both get ramps and stall detection proposed
Motion primitives Set speed and turn rate, turn by an angle, drive a distance, stop proposed
Power Battery voltage and charge left, low-voltage cutoff, sleep built 2026-11-05. gl_zero’s firmware warns at 7.0 V and stops the motors at 6.8 V. It hasn’t run on a board yet. Charge left and sleep are proposed
Reflexes Stop for an obstacle, stop on a tip-over, decided on the bot, without the cluster proposed
Link loss Stop 500 ms after the last command. The firmware does this today decided (existing)
Health Self-test at power-on, fault codes, watchdog, reason for the last reset proposed
Network setup Getting Wi-Fi and broker details onto a new bot, and reconnecting proposed
Capabilities Each bot says what it has (encoders, sensors, top speed) when it connects, so one station runs mixed fleets decided, mixed fleets

Brain side

A brain is a computer that rides on a car and drives it. The first is Morpheus, a Pirate Stage module with a Jetson Orin Nano Super. Soleil runs a Jetson too. Added 2026-10-18.

Area What it covers Status
Bring-up JetPack onto the NVMe drive from a script, and a guide to setting up a Jetson proposed
Containers Gunkslab’s services in containers on JetPack, on host networking, each given only the devices it needs. JetPack, NVIDIA’s camera service, Wi-Fi and the power-off signal stay native proposed
Place in the fleet Outside the cluster. A client of the broker with its own login, like a bot. No Kubernetes on the brain for now proposed
Car link Serial to the car’s ESP32. Commands in (speed and turn rate, a point to go to, stop), and the car’s odometry, IMU, battery and events back, at 50 to 100 Hz. Gunkslab’s own messages over serial, or micro-ROS open
Who drives With a brain fitted and talking, the brain drives and the station’s drive requests are refused. The e-stop still stops everything. The car stops 500 ms after the brain goes quiet open (see Open questions)
Sensors The lidar (RPLIDAR C1), the camera (IMX219) and the mic array (XVF3800), each tested on the bench with a program of its own first proposed
ROS 2 ROS 2 on the brain for the lidar driver, mapping and navigation, kept on the brain. The fleet stays on MQTT. A bridge on the brain turns ROS 2’s speed commands into the car link’s open
Recording Sensor data stamped on one clock, kept on the brain’s drive and copied to the cluster after each session, for training proposed
Power A clean shutdown, then the signal that cuts power. The UPS battery’s level in telemetry proposed
Models What runs on the brain open

Without the station

The fleet keeps working when the station is lost, as long as at least one brain is still running. The station becomes a role any brain can take, instead of one machine. Added 2026-10-18.

Area What it covers Status
Station as a role While the cluster is up, its station runs the fleet. When it goes, the brains still online elect a leader (the lowest ID, for example), and the leader runs the same station code proposed
Brokers on the brains Each brain runs its own MQTT broker, bridged to the cluster’s while it’s there and to the other brains’ when it isn’t. The message layouts don’t change proposed
A broker list on the bots The firmware keeps a list of brokers (the cluster’s first, then each brain’s) instead of one compiled-in address, and moves down it when one fails proposed
Logins on the brains Each brain’s broker holds the bots’ hashed passwords and the rules for who may send what, and never the cluster’s credentials. A lost brain means rotating the bots’ passwords proposed
Cars without a brain They carry on under the leader brain’s station. Their position is the limit. It could come from the overhead camera on a computer of its own (not the station), dead reckoning for short spells, or a brain’s lidar tracking the cars near it proposed
Avoidance without a referee Every robot broadcasts its position and planned path, and every brain runs the station’s right-of-way rules on the same data, so they all reach the same answer proposed
Shared map One robot maps the space, the station keeps the map, and every brain finds itself on it. Robots start from known points (a dock or a marker). Later, changes go out as patches merged into numbered versions, with a full copy on every brain proposed
Link loss Unchanged. A car stops 500 ms after its last command, and moves again when the next leader takes over decided (existing)
When the station goes Finish the current tasks then hold, keep taking tasks from the leader, or hold where it is open
The network Wi-Fi is assumed on the desk and in the house. Outdoors, see the outdoor radio question open

Light brains

A light brain is a small Linux board on a module, in the Orange Pi Zero 3W class, not a Jetson. The first is the arm module’s controller. It doesn’t lead the fleet. It can finish its own work without a brain or the station. Added 2026-10-18.

Area What it covers Status
Tasks handed over whole A task arrives with all its steps and what counts as complete (go to A, pick up, go to B, put down). The robot runs it and reports progress. The station or a brain still hands out tasks and supervises proposed
Position Dead reckoning from the car’s encoders and IMU over the car link, corrected by a camera reading markers on the home dock and around the room proposed
Map A copy of the shared map proposed
Holding something when contact is lost If the task defines complete, or there are instructions for what it’s holding, and it can finish on its own, it finishes. Otherwise it sets the payload down. At a larger scale, it also checks that the spot is safe to set it down first (proposed) decided, 2026-10-18
Losing contact Finish the current arm move. Then the rule above. Then go to where it last heard a brain or the station, and if nobody is there, go home, park and wait proposed
Leading the fleet Not a light brain’s job. It never carries the fleet’s login list proposed
Partners A light brain can drive a car without a brain as its partner, for example the arm loading a bin bot. The station or a brain pairs them for a task and leases the partner’s driving to the light brain until the task ends. The e-stop still overrides. Without the station, the light brain runs a small broker that holds only its partner’s login. The two line up by a marker on the partner, read by the light brain’s camera proposed

Shared

Area What it covers Status
Message protocol Topics, message layouts, units, coordinate frames, a version on every message built 2026-10-02. v0, with JSON Schemas that the simulator, station, scenarios and firmware are held to
Firmware CI Build the firmware on every push built 2026-10-03. CI builds it and tests its protocol rules on every merge request
Time sync So positions and logs from different bots line up proposed
Bench programs Pirate Stage’s parts, tested one at a time on the bench before the car is built. Motors, IMU, battery reading, cliff sensor, drive and encoders (bench/), with pins generated from the car’s pin map built 2026-10-12
Docs Split by kind into get started, tutorials, guides, concepts, reference, robots and project (docs/). The scripts reference is generated from the scripts. CI fails on a broken link, an unlisted page or a stale generated page built 2026-10-13
Install One launcher, ./gunkslab: up, down, status, doctor, logs and version built 2026-10-25. doctor says what’s wrong and what to do. Versions and release notes, an install checklist, known issues and an issue tracker. The first release, 0.1.0, isn’t out yet
Early access How to get the code before it’s public built 2026-11-01. One route: a confidential request in the issue tracker. Once it’s approved, access follows within about 15 minutes. Install starts there
CI runner Where every merge request’s checks run built 2026-11-02. On gunkslab’s own runner, on the cluster
Primers Short pages on what the tutorials lean on built 2026-11-05. MQTT, ROS 2, the ESP32, time-of-flight sensors and batteries
gl_zero’s bench programs gl_zero’s parts tested one at a time on the bench: IMU, battery reading, distance sensors, drive, and how far the battery dips with the motors at full power built 2026-11-05. Five programs in bench/, pins from gl_zero’s pin map

The protocol starts from what the firmware sends today.

  • fleet/<id>/cmd takes {l, r}
  • fleet/<id>/telemetry at 10 Hz
  • fleet/<id>/status online or offline, retained

Decisions, 2026-10-02

  1. Operators. One operator now, built so more can be added later. A fleet ID goes in the topics from the start, and nothing works only on one particular cluster.
  2. Manual driving. A web page, with gamepad support.
  3. Video. Later. Cameras are in the plans.
  4. Fleets. Mixed robot types under one orchestration station.
  5. Simulator. First.
  6. Language. Python. The protocol is written down so the coordinator could be rewritten later, in Go, without the bots noticing.
  7. State. In memory for now. Likely Redis in the long run.

Open questions

  • ROS 2. Many research labs run ROS 2, so a bridge between this protocol and ROS 2 topics might matter.
  • A plug-in interface. Researchers will want to drop in their own task allocation or path planning.
  • Data export. Recordings of runs in a form researchers can analyse.
  • Licensing for the education and research tier.
  • Outdoor radio (2026-10-12). Wi-Fi only is decided for the desk. A fleet in a case, outdoors, would run over a long-range or mesh radio plus Starlink, none chosen yet. The question is what carries the protocol outdoors, and whether MQTT still fits at a few Mbps.
  • Who commands a car with a brain module mounted (2026-10-12). The station is the only thing that commands bots. A Morpheus module takes over the car, and the car’s ESP32 obeys the module. The question is whether the station commands the module, the car or both, and who wins a conflict.
  • Where the coordinator runs outdoors (2026-10-12). Today it’s a namespace on the cluster. A fleet in a case would put it in a command case, in the cloud when linked and local when not, and later on each brain module. The question is how the station’s role splits across those.
  • How far ahead the front sensor sees. gl_zero’s sensor sits level, its lens 33 mm above the desk and 72.45 mm ahead of the middle (its nose pod, modelled 2026-10-30), and is read as five regions of interest, each about 15° across: three straight ahead (aimed 6° down, level and 6° up) and one to each side. The bottom one meets the desk about 14 cm ahead of the lens, so a bot facing an edge stops with its middle about 20 cm from it. The level ones see obstacles out to about 25 cm, and the top one tall things across the desk. The simulator and the firmware both read it this way (the firmware since 2026-10-30). The numbers, and which way each region really looks, get checked once the pod is fitted and real readings are in. The view is as wide as the bot only about 22 cm ahead, and level there, so something low at the very edge of the bot’s path isn’t seen: for a 2 cm box, about the outer 4 mm at the tyres (2026-10-30, worked out and in the simulator). gl_zero keeps this sensor; a wider one would need new firmware and a new nose pod.

First runs (decided, 2026-10-20)

Three milestones on Pirate Stage, in order. Each passes its whole list before the next one starts.

  1. The car alone, on its ESP32.
  2. The car with Canterbury and its two filaments.
  3. Plans: tasks run from the station.

Brains come after these, with a list of their own. Mapping, more than one car and video are out of scope for all three. The thresholds below are proposed, to be tightened once real readings are in.

1. The car alone

This closes F6.2 (step 11 below) for Pirate Stage.

Item Passes when
Runs from its program It powers on into a known state, motors off, and reports its firmware version and what it has. No laptop on a cable
On Wi-Fi It joins the network and the broker under its own login, from settings flashed by a script, none typed in by hand
Browser remote It drives forward, back and turning from the station’s page, with the speed cap on and the dead-man holding
Sensors Every sensor’s reading is live on the page and sane. Encoder distance within about 5% of a measured metre, the IMU heading following a 90° turn by hand, the distance sensor reading a known distance, the battery voltage within about 0.1 V of a meter
Stops The page’s e-stop, the master switch, letting go of the dead-man, and pulling the Wi-Fi (within 500 ms) each stop it
Reflexes It stops for an obstacle and at the desk’s edge with nobody driving
Reconnects After a Wi-Fi drop and a broker restart it comes back on its own, and stays stopped until driven again
A full run 15 minutes of driving with no reset or brownout, nothing hot to the touch, nothing loose or shifted after
Power The low-battery warning shows on the page, and the run time on one charge is measured
Recorded The run’s commands and sensor readings are kept, and can be played back
Repeatable Firmware and settings go on from the repo’s scripts, no secrets in git, and the runbook takes a second car to the same point
An acceptance run One script drives a square and a go-to, and passes or fails on how far off the car ends up

Built so far. The odometer in telemetry (odo_l_m, odo_r_m), shown on the page once the encoders’ counts per wheel turn are measured. And the acceptance run, scripts/accept (the guide), which passes on a simulated Pirate Stage. Until the desk has a position service, it runs by hand (--by-hand). The car steers by its own odometer and gyro, and whoever runs it measures with a tape. The cliff sensors’ firmware, the reflex at both ends, is built and compiles. It hasn’t run on a sensor yet.

2. The car with Canterbury

Item Passes when
Fits Canterbury latches on the click rail (latch B)
Seen The car sees it fitted (DETECT) and the page shows it
Powered Fitting it turns the connector’s power on. The module grounds PWR_EN, which turns on the car’s load switch, with no firmware in between. Canterbury’s buck reads 5.0 V on a meter
Lit Both filaments light
Off The connector’s power goes off when the car turns off, and when Canterbury comes off
Still drives Milestone 1’s drive, stop, reflex and full-run checks pass again with Canterbury on
Power The run time on one charge is measured again, with the filaments lit

3. Plans

Its list gets written once milestone 2 passes. It starts from go to a point (built, in the simulator), a route, a patrol and the task queue.

Proposed order

  1. Message protocol v0. Done 2026-10-02.
  2. A simulated bot that speaks it, and a read-only browser viewer. Done 2026-10-02.
  3. A command-line driving tool. Done 2026-10-02.
  4. The station core. Done 2026-10-02. Fleet summary, one driver per bot, the station’s dead-man, a fleet power cap.
  5. The driving page with gamepad support. Done 2026-10-02.
  6. Click to send a bot somewhere (go-to, steered by the station from its pose). Done 2026-10-02.
  7. A scenario runner, with the first scenarios (crossing, head-on, parked in the way, all failing, as expected). Done 2026-10-02.
  8. Station-level avoidance, so those scenarios pass. Done 2026-10-02. Right of way, giving way early, going round, a guard against driving at a bot, and detours kept on the desk. Two harder scenarios added, three-way and four corners.
  9. A simulated distance sensor and a stop reflex on the bot (an obstacle_stop event, a distance reading). Done 2026-10-03. The VL53L1X modelled as a cone of rays, the reflex for obstacles and the desk’s edge, blocked go-tos, boxes in scenarios.
  10. The broker on the cluster (F6.1). Done 2026-10-13. A login per bot (kept in its flash) and per client, each held to its own topics. F6.1 itself closes when a real bot connects and goes offline when unplugged.
  11. One bot driven from the cluster (F6.2). The firmware has spoken v0 since 2026-10-03. It needs a wired bot.
  12. The overhead camera and position (F6.3). Built 2026-10-24 (scripts/position). It closes when a real camera’s error is measured across the desk.

Parked

  • A phone on the bot (parked 2026-10-02). An Android phone as the bot’s hotspot, cellular link, GPS, IMU and camera, the way Soleil’s electronics list already has the Note 10+. Parked for Wi-Fi only.
    • If it comes back, the ESP32 talks to the phone app, and the app relays to the cluster. Hotspot clients can’t reach the home network through a VPN running on the phone.
    • gl_zero is too small to carry one. Pirate Stage can.