Skip to content
gunkslab

Reference

Scripts

Every command in scripts/. Run them from the repo’s top folder. Each runs its tools in containers: Apple’s container on macOS, docker or podman anywhere else, or the one RUNTIME names. docs/gen.py copies each script’s own help here. Run a script with no command to see the same text.

accept

The acceptance run (milestone 1): one bot, through the station, makes a go-to, then drives a square on its own
encoders and gyro; the position service says how far off it ends up. Needs scripts/broker up, the station, and a
bot with encoders and a gyro: Pirate Stage, or scripts/sim up 1 --type pirate-stage.

  scripts/accept --bot BOT [OPTIONS]   run it; exits 0 if every check passes
  scripts/accept --bot BOT --by-hand   no position service (no overhead camera yet): you mark the desk at the car's
                                       nose and type in what you measure with a tape, when it asks
  scripts/accept test                  its tests, on the simulator and station code
  scripts/accept options               list the OPTIONS: --side 0.3, --goto 0.6,0.4, --desk 1.2x0.8, --fleet lab,
                                       --clockwise, ...

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

bench

The bench programs (bench/): small sketches for testing a robot's hardware on the desk. Built in a container.

  scripts/bench build          compile every program for the ESP32
  scripts/bench list           the programs, one per PlatformIO environment

Flashing one needs its USB port, which a container can't reach: see bench/README.md.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

bot-cert

A bot's certificate for a broker on Vault's CA, from Vault (docs/guides/logins.md, "A bot"). The bot makes
its own key and prints a request for it over USB (cert-request); this signs the request, as an admin (your Vault
login needs gunkslab-admin), and prints the certificate to paste back into the bot (cert).

  scripts/bot-cert BOT.csr   sign the request saved from the bot; writes BOT.crt and prints it
  scripts/bot-cert ca        the fleet's CA, as bot_config.h's MQTT_CA wants it

VAULT_ADDR is your Vault; VAULT_USER, your Vault login, if you'd rather not type it. Without VAULT_ADDR, this
machine's own CA, for bench mode (scripts/broker up --lan): no login asked.

bot-ota

A bot's own password for updates over the air (docs/guides/logins.md, "Updates over the air"). Each bot has its
own: made here, kept in Vault at secret/gunkslab/ota/<bot> (your Vault login needs gunkslab-admin), and typed into
the bot over USB (ota-password), which keeps it in its flash. One bot in hand then gives up its own and no other's.

  scripts/bot-ota new BOT                make BOT's password and keep it; prints the line to type into the bot.
                                         Refused if BOT has one already
  scripts/bot-ota replace BOT            the same, over the one it has: updates need the new one once the bot has
                                         it, and the old one until then (Vault keeps the old as a version before)
  scripts/bot-ota upload BOT ADDRESS [ENV]   build the firmware, sign it (scripts/fw-sign) and send it to BOT, at
                                         ADDRESS, over the air, with its password. ENV is gl-zero-ota (the default)
                                         or pirate-stage-ota. Needs PlatformIO here (pio), python3 and openssl: the
                                         bot connects back to this machine for the image, which a container's
                                         network doesn't let it. The bot checks the signature before it restarts
                                         into the new firmware; if it refuses, the upload still says it went, and
                                         the bot keeps running what it had (its hello's fw says which)

BOT is the bot's name, bot-xxxxxx, as it says at boot. VAULT_ADDR is your Vault; VAULT_USER, your Vault login, if
you'd rather not type it. Without VAULT_ADDR, kept on this machine instead, for bench mode: ~/.gunkslab/bench/ota,
readable by you only.

bot-wifi

A bot's own Wi-Fi password, for the bots' network (docs/security/bot-network.md), which gives each device a password
of its own (UniFi's private pre-shared keys). Made here, kept in Vault at secret/gunkslab/wifi/<bot> (your Vault
login needs gunkslab-admin), added to the network by hand, and typed into the bot over USB (wifi-password), which
keeps it in its flash. One bot in hand then gives up its own and no other's, and it can be taken off the network alone.

  scripts/bot-wifi new BOT       make BOT's password and keep it; prints it, for the network, and the line to type
                                 into the bot. Refused if BOT has one already
  scripts/bot-wifi replace BOT   the same, over the one it has: add the new one to the network, give it to the bot,
                                 then remove the old one from the network (Vault keeps the old as a version before)
  scripts/bot-wifi show BOT      the password kept, for the network again

BOT is the bot's name, bot-xxxxxx, as it says at boot. VAULT_ADDR is your Vault; VAULT_USER, your Vault login, if
you'd rather not type it. Without VAULT_ADDR, kept on this machine instead, for bench mode: ~/.gunkslab/bench/wifi,
readable by you only.

broker

The development MQTT broker, in a container: MQTT on 127.0.0.1:1883, and MQTT over WebSockets on 127.0.0.1:9001
for the browser viewer.

  scripts/broker up        start it (pulls the image the first time); one left stopped by a crash is cleared first
  scripts/broker up --lan [ADDRESS]   bench mode: as well, MQTT over TLS on this machine's network address, port
                           8883, so a real bot on the Wi-Fi can reach it, with logins: a certificate per client
                           from this machine's own CA (made the first time), each held to its own topics
                           (broker/acl) and client ID. 1883 and the WebSockets stay on 127.0.0.1, with no logins,
                           for this machine. ADDRESS if the one it finds is wrong.
  scripts/broker revoke NAME        bench mode: refuse every certificate NAME holds, from now on, and start
                           again so nothing using one stays connected
  scripts/broker down      stop and remove it
  scripts/broker logs      follow its log
  scripts/broker watch     print every gunkslab message going past
  scripts/broker send TOPIC JSON    publish one message
  scripts/broker stream SECONDS TOPIC JSON    publish the same message every 100 ms, for that long
  scripts/broker pub ARGS...        mosquitto_pub with your own flags (-r, -q 1, ...)
  scripts/broker sub ARGS...        mosquitto_sub with your own flags
  scripts/broker unplug ID          kill the client started with -i ID, as if its power was cut

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one. The image and
broker/mosquitto.conf are the same on every runtime.

certs

The fleet's certificates: which are out there, when each runs out, and taking a name's away (docs/guides/logins.md).
With VAULT_ADDR set, the cluster's (Vault's pki-gunkslab, as an admin: your Vault login needs gunkslab-admin); without,
this machine's CA, for bench mode.

  scripts/certs list            every certificate still valid: its name, serial, when it runs out, days left. A bot's
                                or the broker's running out within 60 days is marked, and the exit status is 1
  scripts/certs revoke NAME     every certificate NAME holds, revoked; then the broker drops anyone using one, at once

Revoking on the cluster also needs kubectl for it: the broker reloads its revocation list by itself within ten
minutes, but a client already connected stays on until it reconnects, so this has the new list fetched now and
restarts the broker (every client drops for a moment; bots and the station come back by themselves). VAULT_USER is
your Vault login, if you'd rather not type it.

check

Every check CI runs (.gitlab-ci.yml), on this machine, in containers: the protocol, the docs (generated pages
current, every link resolving), the transport layer's tests, the unit tests (the acceptance run's among them), the firmware, the bench
programs, the scenarios, the shell scripts, the page's scripts, the broker's bench mode, the transport layer on a
real Zenoh router, and the end-to-end test (scripts/broker up first).

  scripts/check

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

check-protocol

Check the protocol's JSON Schemas against its examples (protocol/check.py), in a Python container: nothing is
installed on this machine. Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

drive

Drive a bot from the keyboard, in this terminal (scripts/broker up first, and some bots: scripts/sim up 2).

  scripts/drive [OPTIONS]     start driving: the first bot online, fleet desk
  scripts/drive test          run the driving tool's tests
  scripts/drive options       list the OPTIONS: --bot sim-2, --max 0.5, --fleet lab, ...

The keys are on screen. q stops the bot and quits.
On the cluster's broker, as a driver: MQTT_HOST=192.0.2.10 MQTT_LOGIN=driver-1 scripts/drive (scripts/login first)
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

e2e

The end-to-end test: the simulator (two bots) and the station on their own fleet, "e2e", and a test client that
drives through the station. Needs the broker (scripts/broker up), or with TRANSPORT=zenoh the development Zenoh
router (scripts/zenoh up); it doesn't touch the desk fleet.

  scripts/e2e

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

firmware

The bot's firmware (firmware/): build it, and test its protocol rules, in a container.

  scripts/firmware build     compile it for the ESP32, gl_zero's and Pirate Stage's (both use
                             firmware/include/bot_config.h if it's there, else the example)
  scripts/firmware test      the protocol rules (firmware/lib/agent) and Pirate Stage's (lib/chassis) on this
                             machine, and every message the protocol rules build checked against the protocol's
                             schemas

Flashing a bot needs its USB port, which a container can't reach: see firmware/README.md.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

fw-sign

Sign the bots' firmware for updates over the air, and check a signed image: firmware/tools/fwsign.py says how
(scripts/fw-sign with no arguments prints it). Needs python3 and openssl on this machine, as scripts/bot-ota upload
does.

gunkslab

The fleet on your desk, in one command: the broker, simulated bots, the station and the page, each in its own
container, on this machine only (127.0.0.1, no logins). From the repo's top folder, as ./gunkslab:

  ./gunkslab up [N]      start everything with N simulated bots (2 if not said), then open the page
                         (GUNKSLAB_OPEN=0 to leave the browser alone)
  ./gunkslab down        stop everything gunkslab started, keeping each one's log in logs/ first
  ./gunkslab status      what's running, and the page's address
  ./gunkslab doctor      check the container runtime, the ports, the disk and what's left over; says what to fix
  ./gunkslab logs        every running service's log, into logs/ (one file each), and where they are
  ./gunkslab version     which gunkslab this is (VERSION, and the commit if it's a git checkout)

Anything wrong: ./gunkslab down && ./gunkslab up puts it right, and ./gunkslab doctor names what it can't. Each
service also has a script of its own (scripts/broker, sim, station, viewer) for more than this.

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

lock

The Python packages, locked: each requirements.txt from its requirements.in, every package named and its dependencies
too, each pinned to a version and the hashes of its published files (pip-compile). The stack's containers' and CI's
(requirements.txt); the position service's (position/) and the firmware's build tools' (firmware/), on the Debian
images they run on; and the security checks' tools (security/).

  scripts/lock          write every requirements.txt again, after changing a requirements.in

With hashes, pip installs a file only if it's byte for byte the one published: a package swapped on the way in fails
the install, whatever certificates pip trusts.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

login

A certificate for a broker on Vault's CA, from Vault: the broker takes no passwords, and the certificate's name is
the login (docs/guides/logins.md). Asks for your Vault login and password, gets a certificate for NAME, and
keeps it in ~/.gunkslab/certs/NAME (GUNKSLAB_CERTS to put them elsewhere), readable by you only. Then
MQTT_LOGIN=NAME (with MQTT_HOST) makes scripts/drive, scripts/station and the rest use it.

  scripts/login NAME     driver-1 and so on: your own; station, position, recorder: an admin's

A driver's certificate lasts 12 hours, a service's a week: log in again when it runs out. VAULT_ADDR is your Vault;
VAULT_USER, your Vault login, if you'd rather not type it.

Without VAULT_ADDR, from this machine's own CA instead, for bench mode (scripts/broker up --lan): no login asked, 30
days, into ~/.gunkslab/bench/certs/NAME. Programs on this machine don't need one (they use 127.0.0.1); it's for one
on another machine on the network, which keeps the folder as its own ~/.gunkslab/certs/NAME.

position

The position service (position/): where each bot is on the desk, from a network camera over it, looking down at the
markers on the desk's corners and on each bot. It publishes each bot's pose, as the simulator does for its bots.
The camera's address goes in CAMERA_URL, its password in it if it has one (rtsp://user:pass@192.168.1.60/stream1, or
http://192.168.1.60:8080/video). Its lens file and the pages to print are kept in position/local/ (out of git).

  scripts/position print             write the pages to print: the markers, and the checkerboard
  scripts/position calibrate         calibrate the camera's lens from the checkerboard (once per camera)
  scripts/position up [OPTIONS]      start it: --bot 10=bot-a4cf12 for each bot, --desk 1.2x0.8
  scripts/position down              stop it
  scripts/position logs              follow its log: what it sees, frames a second, how long a frame takes
  scripts/position test              run its tests
  scripts/position options           list the OPTIONS up takes

scripts/broker up first, or use the cluster's broker with its position login:
  MQTT_HOST=192.0.2.10 MQTT_LOGIN=position scripts/position up --bot 10=bot-a4cf12
The guide: docs/guides/overhead-camera.md. Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to
pick one.

record

Record a fleet's messages, and play a recording back to watch it on the page or read it as text. Recordings go in
recordings/ (kept out of git), a file each.

  scripts/record start [--fleet desk]   start recording in the background: everything on the fleet, as heard
  scripts/record stop                   stop it; the file is complete as it stands
  scripts/record logs                   follow it
  scripts/record list                   the recordings: fleet, when, how long, how many messages, which bots
  scripts/record show FILE [--topic sim-1/*]   a recording's messages as text, a line each
  scripts/record play FILE [OPTIONS]    send it into fleet replay, as heard; watch it with the page's &fleet=replay
  scripts/record test                   run its tests
  scripts/record options                list play's OPTIONS: --into, --from 30, --until 90, --speed 2

Playback never goes into the fleet it was recorded on, nor into one with anything online or live, and leaves
nothing retained. FILE is a name from list. scripts/broker up first, or the cluster's broker with a login that may
read the fleet: MQTT_HOST=192.0.2.10 MQTT_LOGIN=recorder scripts/record start
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

scenario

Scenarios (scenarios/*.toml): bots, what they're told to do, and what must be true, played out on the real
simulator and station code.

  scripts/scenario list            the scenarios, and what each is
  scripts/scenario run [NAME ...]  run them (all by default), faster than real time, each scored; fails if any
                                   fails unexpectedly (--json: the results and scores as JSON instead)
  scripts/scenario stress [--layouts 200] [--seed 1]   many made-up layouts: fails on a collision, a bot at the
                                   desk's edge, or more than 5% of bots stuck
  scripts/scenario watch NAME      run one at real speed, for the page to show (scripts/broker up and
                                   scripts/viewer up first); it prints the address to open
  scripts/scenario test            the runner's own tests

TRANSPORT=zenoh in front of watch: on the development Zenoh router (scripts/zenoh up) in place of the broker.

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

security

Security checks, in containers: what they're for, and what's been looked at and accepted, is in SECURITY.md.

  scripts/security            all of them
  scripts/security secrets    no credentials in the code or anywhere in its history (gitleaks)
  scripts/security deps       no known vulnerabilities in the pinned Python packages (pip-audit)
  scripts/security python     the Python code (bandit)
  scripts/security firmware   the firmware's and the bench programs' C++ (cppcheck)
  scripts/security containers the Containerfiles, and the images the stack runs on (trivy)
  scripts/security vendored   the page's copy of mqtt.js is byte for byte the published one (npm)
  scripts/security identity   every commit not yet on main is made as gunkslab (git; security/identity.sh)

Each needs the network the first time (images, vulnerability databases). Accepted findings and why:
security/bandit.yaml, security/trivyignore.yaml.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

sim

The simulator: bots that speak protocol v0, in a container, connected to the broker (scripts/broker up first).

  scripts/sim up [N] [OPTIONS]   start N simulated gl_zero bots (default 1), sim-1 ... sim-N, fleet desk
  scripts/sim down               stop them; each says offline as it goes
  scripts/sim crash              kill them outright, with no goodbye: the broker sends their last wills
  scripts/sim logs               follow the simulator's log
  scripts/sim fault BOT battery low|empty|ok    act out a real bot's own stops (rule 10): its battery's state
  scripts/sim fault BOT stall L|R               or a motor stalling while its side is driven
                                 (--fleet lab after them for another fleet; the development broker only)
  scripts/sim test               run the simulator's tests
  scripts/sim build              rebuild its image (up and test do this themselves)

  scripts/sim options            list the OPTIONS up takes

OPTIONS go to the simulator: --desk 1.5x1.0, --fleet lab, --seed 7, ...
TRANSPORT=zenoh in front: on the development Zenoh router (scripts/zenoh up) in place of the broker.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

station

The station: runs the fleet. It tracks every bot, and drives them for the driving tool and the driving page.
scripts/broker up first, or use the cluster's broker with its station login:
  MQTT_HOST=192.0.2.10 MQTT_LOGIN=station scripts/station up      (scripts/login station first)

  scripts/station up [OPTIONS]   start it: fleet desk, no power cap
  scripts/station down           stop it; it stops any bot it was driving, then says offline
  scripts/station crash          kill it outright: the broker sends its last will
  scripts/station logs           follow its log
  scripts/station test           run its tests
  scripts/station options        list the OPTIONS: --cap 0.6, --fleet lab, ...

TRANSPORT=zenoh in front: on the development Zenoh router (scripts/zenoh up) in place of the broker.

Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

viewer

The browser viewer: a small web server in a container, serving viewer/ on http://127.0.0.1:8080. The page talks to
the broker itself, over WebSockets on 127.0.0.1:9001 (scripts/broker up first).

  scripts/viewer up      start it, and print the address to open
  scripts/viewer down    stop it

The page's settings go in the address: ?fleet=desk&desk=1.2x0.8&ws=ws://127.0.0.1:9001 (those are the defaults).
The broker's WebSocket takes only this page, at 127.0.0.1:8080 or localhost:8080: serve it anywhere else and add
its address to websockets_origin in broker/mosquitto.conf.
Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.

zenoh

The development Zenoh router, in a container: as the development broker is to MQTT (scripts/broker). Zenoh on tcp
127.0.0.1:7447, open to this machine's programs with no logins, and a store for every topic the protocol keeps.

  scripts/zenoh up         start it (builds the image the first time); one left stopped by a crash is cleared first
  scripts/zenoh up --lan [ADDRESS]   bench mode: as well, Zenoh over TLS on this machine's network address, port
                           7448, a certificate per client from this machine's own CA (the broker's, made the first
                           time), each held to the topics broker/acl gives its name, plus the station's own e-stop.
                           7447 stays on 127.0.0.1, with no logins. ADDRESS if the one it finds is wrong.
  scripts/zenoh revoke NAME          bench mode: every certificate NAME holds revoked, and the router started
                           again without rules for NAME (it reads no revocation list: a name with no certificate left
                           gets nothing)
  scripts/zenoh down       stop and remove it
  scripts/zenoh logs       follow its log
  scripts/zenoh build      rebuild its image

Then TRANSPORT=zenoh in front of scripts/sim, scripts/station, scripts/scenario or scripts/e2e puts them on it in
place of the broker. Uses Apple's container on macOS, docker or podman anywhere else; set RUNTIME to pick one.