Skip to content
gunkslab

Tutorials

A course in gunkslab, from the broker up. You type every command yourself. Each tutorial says what to type, what you’ll see and what just happened, then ends with a few questions.

Do them in order. Each one builds on the one before. Do Install first. Install takes about 15 minutes, and 01 to 03 about 30 each, so the end of tutorial 03 is about an hour and 45 minutes from a fresh start.

If the quickstart is still running, stop it first with ./gunkslab down. The tutorials start each piece themselves.

After these, two guides go further: a real bot on the bench and the overhead camera.

  1. 01The MQTT broker30 minRun the broker, then send and watch messages. Topics, wildcards, retained messages, QoS and last wills
  2. 02Protocol v0 by hand30 minBe a bot and a station yourself, with nothing but the broker: hello, status, commands, telemetry, events, the e-stop
  3. 03The simulator and the viewer30 minSimulated bots on a desk in your browser: drive them, find one, e-stop them, crash them
  4. 04The driving tool20 minDrive from the keyboard: speed and turn, reading the echo, a power cap, switching bots, the e-stop, a client that dies
  5. 05The station30 minTalk to the station by hand: driving through it, its dead-man, one driver per bot, refusals, a fleet power cap, a crash
  6. 06The driving page20 minDrive from the browser with the keys, the on-screen pad or a gamepad. Two drivers at once, and the e-stop from the page
  7. 07Send a bot somewhere20 minClick the desk and the station drives the bot there: how it steers, taking over, and every way a trip can end
  8. 08Scenarios25 minSet up a situation and say what must happen: run them, watch one in the page, write your own, the stress test, and how CI treats them
  9. 09Keeping out of the way20 minHow the station keeps bots from running into each other on a go-to: the rules, watching them, the desk's edges, and where they stop
  10. 10The distance sensor20 minThe bot's own front sensor and its reflex: put a box on the desk, drive into it, back off, and a go-to it can't finish

How they’re written

  • Commands run from the repo’s top folder (gunkslab/), unless a step says otherwise.
  • Some steps need two terminal windows. One watches messages while the other sends them. The steps say which is which: Terminal A and Terminal B.
  • Nothing gets installed on your machine except a container runtime. Everything else runs in containers, through the scripts in scripts/. They use Apple’s container on macOS, and docker or podman on Linux and Windows.
  • The output shown is real, from running the step. Times, IDs and numbers will differ on yours.
  • Check yourself ends each tutorial. Answer the questions without looking back. Each one names the section it comes from.