Skip to content
gunkslab

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.py is 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 in run.py, which checks each one against the protocol’s schemas.

  • sim/gunksim/run.py puts the bots on the network: one MQTT connection each, the bodies moving at 50 Hz, telemetry and poses at 10 Hz.

  • sim/gunksim/types.py holds 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.py tests every rule, using simulated time, so seconds of driving take no time. scripts/sim test runs them:

    35 passed in 0.11s
    
  • viewer/viewer.js is the page. It subscribes to gunkslab/v0/desk/# and draws what arrives.

The driving tool

  • drive/gunkdrive/control.py is 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.py is the screen (Python’s curses) and the MQTT connection.

  • scripts/drive test runs the tests:

    24 passed in 0.05s
    

    Every 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.py is 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.py puts 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 test runs the tests:

    62 passed in 0.22s
    

The driving page

  • viewer/drive.js is 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.js is the rest of the page: the desk, the cards, the events. It tells drive.js when 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

  • steer in station/gunkstation/core.py is the steering, and goto_step runs it ten times a second.
  • station/tests/test_goto.py tests 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.py sends a simulated bot to a point through the real broker and station, and checks it arrived within 5 cm.

Scenarios

  • scenarios/gunkscen/world.py wires the bots and the station together and steps time.

  • scenarios/gunkscen/scenario.py reads and checks the files.

  • scenarios/gunkscen/geometry.py decides whether two bodies overlap and how far apart they are: under half a millimetre is touching, a collision.

  • scripts/scenario test runs the runner’s own tests:

    13 passed in 1.44s
    

Avoidance

  • station/gunkstation/avoid.py is 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.py tests both, with scripts/station test.

The distance sensor

  • sim/gunksim/tof.py is the sensor: a region of interest’s cone as a fan of rays, against the desk, boxes and bots. sim/gunksim/types.py says where gl_zero’s sensor is and which regions it’s read as (FIVE), in what order (FIVE_ORDER).
  • sim/gunksim/bot.py, sense() and applied(), is the reflex. read_tof() reads the next region in turn.
  • firmware/lib/agent, Agent::sense() with a Region, is the same reflex on the bot, tested in firmware/test/test_agent with the simulator’s cases. firmware/src/gl-zero/main.cpp aims the real sensor at each region in turn (TOF_REGIONS, TOF_ORDER, roiCentre()).
  • station/gunkstation/core.py ends a go-to as blocked (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, and no_way_round() looks round before giving up. cramped() and room_behind() back a bot off before it turns beside something found.
  • station/gunkstation/avoid.py has each type’s sensor (SENSORS, the simulator’s numbers again). found() is where a bot’s readings put what it saw, and gone() whether a region has since seen past it.
  • station/gunkstation/avoid.py, straight_in(), line_up() and can_end(), is coming in to a goal near the desk’s edge without the reflex stopping the bot short; core.py, way_in() and lining_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’s station/fleet row.
  • scenarios/box-in-the-way.toml, box-beside.toml, at-the-edge.toml, too-near-the-edge.toml, round-a-wall.toml test all of it, with boxes ([[box]]) and the go-to’s expected ending ([expect] end). scenarios/tests checks the station’s copy of the sensor is the simulator’s.
  • sim/tests/test_tof.py tests the sensor and the reflex.