Skip to content
gunkslab

Tutorial 05 · 30 min

The station

The station is the program that runs the fleet. It keeps track of every bot, and it’s the only thing that sends a bot commands. Anything that wants to drive (the driving tool, the driving page) asks the station, and the station drives. Talk to it by hand, the way those clients do, and see each of its rules at work.

Do 03. The simulator and the viewer first. Have the protocol reference open at The station. Use two terminal windows and a browser.

Why there’s a station at all is in Concepts: the architecture.

1. Start everything

Terminal B:

scripts/broker up
scripts/sim up 2
scripts/station up
scripts/viewer up
station: up. scripts/station logs to follow it.

Open http://127.0.0.1:8080/. The header says station online. Then look at the station’s log:

scripts/station logs
20:36:32 station online: fleet desk, power cap 1.00

Press Ctrl-C to stop following it. The station keeps running.

2. What the station knows

The station publishes a summary of the fleet, retained. Ask for it:

scripts/broker sub -v -t gunkslab/v0/desk/station/fleet -C 1

-C 1 stops after one message. Because it’s retained, it arrives at once:

gunkslab/v0/desk/station/fleet {"estop":false,"bots":[{"id":"sim-1","state":"online","quiet":false,"type":"gl-zero"},{"id":"sim-2","state":"online","quiet":false,"type":"gl-zero"}]}

Each bot’s row says what it is, whether it’s online, and whether it’s quiet: online but with no telemetry for over a second, which on a real bot would mean it’s struggling. Once a bot is driven, its row also shows who’s driving it (driver) and its echo time (echo_ms). The viewer’s cards show both.

3. Drive through the station

Terminal A, watch every command the bots get, and every notice the station sends:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/cmd' -t 'gunkslab/v0/desk/station/notice'

Terminal B, ask the station to drive sim-1 for a second. You’re a client called me, the last part of the topic:

scripts/broker stream 1 gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","l":0.6,"r":0.6}'

Terminal A:

gunkslab/v0/desk/sim-1/cmd {"l":0.6,"r":0.6,"seq":1}
gunkslab/v0/desk/sim-1/cmd {"l":0.6,"r":0.6,"seq":2}
...
gunkslab/v0/desk/sim-1/cmd {"l":0.6,"r":0.6,"seq":12}
gunkslab/v0/desk/sim-1/cmd {"stop":true,"seq":13}
  • The station numbered every command (seq 1, 2, 3 …). Your requests had no numbers.
  • It sent about 12, though you asked for one second (10). After your last request, it kept the bot going for half a second, then sent a stop.

The station’s dead-man

Send one request, not a stream:

scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","l":0.6,"r":0.6}'
gunkslab/v0/desk/sim-1/cmd {"l":0.6,"r":0.6,"seq":14}
...
gunkslab/v0/desk/sim-1/cmd {"l":0.6,"r":0.6,"seq":18}
gunkslab/v0/desk/sim-1/cmd {"stop":true,"seq":19}

The station streamed for half a second, heard nothing more, and stopped the bot itself. Compare tutorial 03, where a single command made the bot stop itself with a timeout_stop. Now there are two dead-men: the station watches the client, and the bot watches the station.

4. One driver per bot

Drive sim-1 for two seconds in the background, and while that’s going, have a second client, other, try to take it. Terminal B:

scripts/broker stream 2 gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","l":0.3,"r":0.3}' &
scripts/broker send gunkslab/v0/desk/station/drive/other '{"bot":"sim-1","l":-1,"r":-1}'

Terminal A shows the commands carrying on at 0.3, and the station turning other away:

gunkslab/v0/desk/station/notice {"client":"other","bot":"sim-1","kind":"held","by":"me"}

And the station’s log says so too (scripts/station logs):

20:36:40 station refused sim-1 for other: held

me holds sim-1 until it lets go, or goes quiet for a second. Let go now:

scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","release":true}'

The station stops the bot as it lets go. Now other can have it:

scripts/broker send gunkslab/v0/desk/station/drive/other '{"bot":"sim-1","stop":true}'

A stop from other is accepted, and other now holds sim-1. A second later, quiet, it lets go by itself.

5. What the station refuses

The e-stop. Set it, then ask to drive:

scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/me -m '{"stop":true}'
scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-2","l":0.5,"r":0.5}'
gunkslab/v0/desk/station/notice {"client":"me","bot":"sim-2","kind":"estop"}

The e-stop never goes through the station. You set yours on its own topic, and the bots obey it directly, so stopping never depends on the station being up. The station only refuses to drive while anyone’s is on. Clear yours:

scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/me -n

A bot it’s never heard of:

scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-9","l":0.5,"r":0.5}'
gunkslab/v0/desk/station/notice {"client":"me","bot":"sim-9","kind":"unknown"}

The other refusals are offline (the bot is known but not online), no_identify (the bot’s hello doesn’t list identify), no_pose (a go-to, with no recent position for the bot: tutorial 07), and battery_empty (the bot says its battery is empty: tutorial 03, section 7).

6. A power cap for the whole fleet

Restart the station with a cap of 50%:

scripts/station down
scripts/station up --cap 0.5
scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","l":1,"r":0.5}'
gunkslab/v0/desk/sim-1/cmd {"l":0.5,"r":0.25,"seq":1}

You asked for 1 and 0.5. The station scaled both sides by half, so the curve keeps its shape at a gentler speed. Every client gets the same cap, whatever it asks for. seq started again at 1. A restarted station counts from zero, and the bot accepts that because it had stopped (protocol rule 5).

7. If the station crashes

scripts/station crash
  • The browser shows station offline. The broker published the station’s last will.
  • The bots don’t need the station to be safe. Any bot it was driving stops itself within half a second, and sends a timeout_stop (crash it while a stream is running to see one).
  • The driving tool, if it’s running, says the station is offline and won’t drive.

Start it again with scripts/station up. It rebuilds its picture of the fleet from the bots’ retained hello and status straight away.

8. Tidy up

Stop Terminal A with Ctrl-C, then Terminal B:

scripts/viewer down
scripts/station down
scripts/sim down
scripts/broker down

How it’s built: the codebase.

Check yourself

  1. Why does every command come from the station, rather than from whoever wants to drive? (Concepts: the architecture)
  2. A client sends one request and dies. Who stops the bot, and roughly when? (The station’s dead-man)
  3. The driving tool holds sim-1. You open a second driving tool and try sim-1. What do you see? (4. One driver per bot)
  4. Why doesn’t the e-stop go through the station? (5. What the station refuses)
  5. With --cap 0.6, what does a request for l 1, r -1 become? (6. A power cap)

Stuck?

  • Run ./gunkslab doctor. It checks the container runtime and the ports, and prints FIX with what to do.
  • Troubleshooting has the common problems and their fixes.
  • Known issues says what’s untested or doesn’t work yet.
  • Still stuck? Open an issue in desk-issues with what you typed, what you saw, and the output of ./gunkslab doctor.