Reference
The codebase
Where each piece lives in the repo, and the files that matter in each. Each tutorial links here for how the piece it teaches is built.
The repo
| Path | What |
|---|---|
docs/ |
These docs: one folder per section, each with a README listing its pages in order. |
protocol/ |
A JSON Schema per message of protocol v0, with example messages, checked by check.py. |
broker/, scripts/broker |
The development MQTT broker (Mosquitto 2.1.2) in a container on 127.0.0.1:1883: scripts/broker up, down, watch, send. Bench mode (up --lan, broker/lan.conf) adds TLS on the network with logins held to their topics (broker/acl), its certificates from this machine’s own CA (broker/ca, revoke). Apple container on macOS, docker or podman elsewhere. |
scripts/login, scripts/bot-cert, scripts/certs, tests/broker/ |
Logins for a broker that takes them: TLS only, a certificate per client as its login, from Vault’s CA with VAULT_ADDR set and this machine’s without. scripts/login gets one. scripts/bot-cert signs a bot’s, which makes its own key (firmware/lib/brokertls). scripts/certs lists what’s out there and revokes. Logins and certificates. tests/broker/ runs bench mode’s config against certificates from a throwaway CA. |
scripts/check-protocol |
Checks the protocol’s schemas against its examples, in a Python container. |
transport/ |
gunklink, how every Python program here reaches a fleet: one connection by name, kept messages, presence, the two kinds of delivery, and a marker that says every kept e-stop has arrived (what a transport needs). Over MQTT (gunklink/mqtt.py, the only code that uses paho), or over an in-memory hub that tests use in place of a broker (memory.py). The containers copy it in. |
sim/, scripts/sim |
The simulator: simulated gl_zero bots that speak protocol v0, in a container. scripts/sim up N, down, crash, test. |
viewer/, scripts/viewer |
The browser page: the desk from above with the bots, their cards and events, and a drive panel (keys, an on-screen pad, a gamepad) that drives through the station. scripts/viewer up, then http://127.0.0.1:8080/. |
station/, scripts/station |
The station: tracks the fleet, and is the only thing that commands bots. Clients ask it to drive. scripts/station up, down, crash, test. |
drive/, scripts/drive |
The driving tool: drive a bot from the keyboard in a terminal, through the station, with a live readout. scripts/drive, scripts/drive test. |
record/, scripts/record |
The recorder: keeps everything said on a fleet in a file (recordings/, out of git), lists and shows recordings, and plays one back into another fleet for the page. scripts/record start, stop, list, show, play, test. The guide. |
position/, scripts/position |
The position service: each bot’s pose from a network camera’s view of the markers on the desk’s corners and on each bot. The geometry (gunkposition/field.py), the tracker (track.py), the camera’s stream (camera.py), the lens’s calibration (calibrate.py) and the pages to print (sheets.py), tested on desks and checkerboards it draws itself (tests/render.py). Not yet run against a real camera. On Debian’s slim image, with its own lock file, since OpenCV has no build for Alpine. scripts/position print, calibrate, up, down, logs, test. The guide. |
accept/, scripts/accept |
The acceptance run: a go-to and a square on the bot’s own encoders and gyro, through the station, passed or failed on how far off it ends up. Its tests play it on the real simulator and station code. The guide. |
scenarios/, scripts/scenario |
Scenarios: where bots start, what they’re told to do, what must be true. Played out on the real simulator and station code, faster than real time (run), or at real speed for the page (watch). CI runs them all. |
scripts/check, .gitlab-ci.yml |
Every check: the protocol, the unit tests, the end-to-end test (tests/e2e/, also scripts/e2e), the shell and page scripts. CI runs them on every merge request and on main. scripts/check runs the same on your machine. |
.gitlab/ci/guards.yml |
Four jobs that guard the checks, on merge requests only: ignore comments and skipped tests can’t go up, a change to a check shows as a warning, a bug fix has to change a test, and so does a change to code in a part that has tests. Contributing says what each does. |
requirements.in, requirements.txt, scripts/lock |
The Python packages the containers install: requirements.in names them, requirements.txt is them and everything they need, each pinned with its hashes. scripts/lock writes it again after a change. |
scripts/lib.sh |
What the scripts share: which container runtime to use, and how containers reach the broker. |
security/, scripts/security |
The security checks (secrets, dependencies, code, containers, vendored code) that CI runs on every merge request. |
firmware/, scripts/firmware |
The ESP32 agent (PlatformIO). One binary for every gl_zero; each names itself from its MAC. Speaks protocol v0. scripts/firmware build, test. Pirate Stage’s is started in src/pirate-stage, speaking protocol v0 too, its motor and battery rules in lib/chassis. Flashing is a guide, and what it sends is the firmware reference. |
bench/, scripts/bench |
Bench programs: small programs that test a robot’s hardware on the desk, one PlatformIO environment each, with Pirate Stage’s pin map as a generated header. scripts/bench build, list. Flashing is a guide. |
The simulator and the viewer
-
sim/gunksim/bot.pyis one bot: what it does with each message, and how its body moves, stopping against the desk’s edge, boxes and other bots (SimBot.contact). The rules in the protocol are in there, most marked with their rule number. Refusing bad messages (rule 8) is inrun.py, which checks each one against the protocol’s schemas. -
sim/gunksim/run.pyputs the bots on the network: one MQTT connection each, the bodies moving at 50 Hz, telemetry and poses at 10 Hz. -
sim/gunksim/types.pyholds what a gl_zero is to the simulator: its size, top speed and how quickly its wheels respond. The size, the track and where the sensor sits are from gl_zero’s CAD. The speed and response are guesses until a real bot drives. -
sim/tests/test_bot.pytests every rule, using simulated time, so seconds of driving take no time.scripts/sim testruns them:35 passed in 0.11s -
viewer/viewer.jsis the page. It subscribes togunkslab/v0/desk/#and draws what arrives.
The driving tool
-
drive/gunkdrive/control.pyis the tool’s logic: what each key does, the mixing, and what it asks the station for. It never touches the network or the screen, so its tests feed it keys and messages directly. -
drive/gunkdrive/app.pyis the screen (Python’s curses) and the MQTT connection. -
scripts/drive testruns the tests:24 passed in 0.05sEvery message the tests make the tool send is checked against the protocol’s schemas, and one test checks it never sends a bot a command directly.
The station
-
station/gunkstation/core.pyis the station’s logic: the fleet it knows, who holds which bot, and the commands it sends. It never touches the network, so its tests drive it with simulated time. -
station/gunkstation/run.pyputs it on the network: one MQTT connection, every incoming message checked against the protocol’s schemas, and a clean shutdown that stops any bot it’s driving and says offline. -
scripts/station testruns the tests:62 passed in 0.22s
The driving page
viewer/drive.jsis the drive panel: the keys, the pad, the gamepad, and the requests to the station. It sends one request every 100 ms while you’re driving, and one stop when you let go.viewer/viewer.jsis the rest of the page: the desk, the cards, the events. It tellsdrive.jswhen the station sends a notice, or when the fleet changes.
The page’s message checker has tests (tests/page/check.mjs, in scripts/check). The drive panel has none. It was
tested by driving it in Chrome with every input, including a simulated gamepad, while watching the station’s traffic.
Go to
steerinstation/gunkstation/core.pyis the steering, andgoto_stepruns it ten times a second.station/tests/test_goto.pytests it closed-loop against a model of a gl_zero, from four different starting positions and headings, and every way a go-to can end.tests/e2e/test_e2e.pysends a simulated bot to a point through the real broker and station, and checks it arrived within 5 cm.
Scenarios
-
scenarios/gunkscen/world.pywires the bots and the station together and steps time. -
scenarios/gunkscen/scenario.pyreads and checks the files. -
scenarios/gunkscen/geometry.pydecides whether two bodies overlap and how far apart they are: under half a millimetre is touching, a collision. -
scripts/scenario testruns the runner’s own tests:13 passed in 1.44s
Avoidance
station/gunkstation/avoid.pyis the geometry: body sizes, “is something in my path”, where to put a detour waypoint, whether two paths meet, and the guard.station/gunkstation/core.py,avoiding(), applies the rules on each step of a go-to, before the steering. The guard runs after the steering, on the wheel powers about to be sent.station/tests/test_avoid.pytests both, withscripts/station test.
The distance sensor
sim/gunksim/tof.pyis the sensor: a region of interest’s cone as a fan of rays, against the desk, boxes and bots.sim/gunksim/types.pysays where gl_zero’s sensor is and which regions it’s read as (FIVE), in what order (FIVE_ORDER).sim/gunksim/bot.py,sense()andapplied(), is the reflex.read_tof()reads the next region in turn.firmware/lib/agent,Agent::sense()with aRegion, is the same reflex on the bot, tested infirmware/test/test_agentwith the simulator’s cases.firmware/src/gl-zero/main.cppaims the real sensor at each region in turn (TOF_REGIONS,TOF_ORDER,roiCentre()).station/gunkstation/core.pyends a go-to asblocked(BLOCKED_S,HELD_MAX_S).learn()remembers what a bot’s sensor finds (Station.seen), placing each reading at the heading the bot had when it was read (turned_by()),avoiding()goes round it, andno_way_round()looks round before giving up.cramped()androom_behind()back a bot off before it turns beside something found.station/gunkstation/avoid.pyhas each type’s sensor (SENSORS, the simulator’s numbers again).found()is where a bot’s readings put what it saw, andgone()whether a region has since seen past it.station/gunkstation/avoid.py,straight_in(),line_up()andcan_end(), is coming in to a goal near the desk’s edge without the reflex stopping the bot short;core.py,way_in()andlining_up(), applies it on a go-to, and refuses a point no way in reaches (edge).viewer/viewer.js,canEnd(), shades the same places on the page, from the numbers in the bot’sstation/fleetrow.scenarios/box-in-the-way.toml,box-beside.toml,at-the-edge.toml,too-near-the-edge.toml,round-a-wall.tomltest all of it, with boxes ([[box]]) and the go-to’s expected ending ([expect] end).scenarios/testschecks the station’s copy of the sensor is the simulator’s.sim/tests/test_tof.pytests the sensor and the reflex.