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.