Tutorial 04 · 20 min
The driving tool
In tutorial 03 you drove with scripts/broker stream, one fixed command at a time. The driving tool drives from the
keyboard. Keys change speed and turn, it asks the station ten times a second, and it shows what the bot does with it.
The tool never commands a bot itself. It asks the station, and the station drives the bot (see 05. The station for how). So the station has to be running.
Do 03. The simulator and the viewer first. 05. The station explains what the station does. Read it before or after this one. Use two terminal windows and a browser. Make Terminal A at least 100 characters wide and 34 lines tall, so the whole screen fits.
1. Start everything
Terminal B:
scripts/broker up
scripts/sim up 2
scripts/station up
scripts/viewer up
Open http://127.0.0.1:8080/. The header should say station online.
Terminal A:
scripts/drive
The first run builds the tool’s image, which takes a minute. Then the terminal turns into this:
gunkslab drive drive-0044 fleet desk broker 192.168.64.50:1883 connected station online
Bots
> 1 sim-1 gl-zero online
2 sim-2 gl-zero online
Driving sim-1
speed +0.0 turn +0.0 -> l +0.00 r +0.00 stopped
requests sent 0 station -> bot -> station echo -
bot applies l +0.00 r +0.00 stopped seq - wifi -53 dBm
at x 0.431 y 0.650 m heading +1.45 rad
Keys
w / up faster s / down slower, then reverse
a / left turn left d / right turn right
space stop i identify (wiggle)
tab / n next bot 1-9 pick a bot (the last one is let go)
e e-stop on / off for the whole fleet
q stop, let go of the bot, and quit
drive-0044is this tool’s name to the station, picked at random each time it starts.- The broker’s address is the container’s, not 127.0.0.1. The tool runs in its own container, where 127.0.0.1 would mean itself.
- It picked
sim-1, the first bot it heard from. The>marks the bot you’re driving.
2. Drive
Press w four times. Each press adds 0.1 to the speed, and the bots list now says sim-1 ... driven by you:
speed +0.4 turn +0.0 -> l +0.40 r +0.40 streaming every 100 ms
In the browser, sim-1 drives off. Press a twice to turn left:
speed +0.4 turn +0.2 -> l +0.20 r +0.60 streaming every 100 ms
Turn moves power from one side to the other: the left side loses 0.2 and the right gains 0.2, so the bot curves left. Press d to turn back. Hold s and the speed comes down through zero into reverse.
Press space to stop. The tool asks the station to stop the bot, and stops streaming. You still hold the bot until you switch away or quit.
Reading the screen while driving
speed +0.4 turn +0.2 -> l +0.20 r +0.60 streaming every 100 ms
requests sent 25 station -> bot -> station echo 66 ms
bot applies l +0.20 r +0.60 moving seq 64 wifi -50 dBm
at x 0.398 y 0.742 m heading +2.65 rad
- Line 1 is what you asked for: speed and turn, mixed into the two sides’ power,
landr. - Line 2 is how many requests the tool has sent the station, and the station’s echo time: the station numbers
every command it sends the bot (
seq), and times how long until the bot’s telemetry brings that number back. - Line 3 is the bot’s side, from its telemetry: the power it’s really applying, and the last
seqit obeyed. Theseqis the station’s numbering, not the tool’s. - Line 4 is where the position service sees it.
The echo time includes up to 100 ms waiting for the bot’s next telemetry, so 50 to 110 ms is normal here. Numbers jumping to hundreds of milliseconds would mean the Wi-Fi is struggling, which you’ll see on real bots and never on the simulator.
3. A gentler bot
Quit with q, then start again with a power cap:
scripts/drive --max 0.4
Now no side ever gets more than 40% power, however many times you press w. Press it six times:
speed +0.6 turn +0.0 -> l +0.40 r +0.40 streaming every 100 ms
The speed says 0.6, and each side gets 0.40. When a turn would push one side past
the cap, both sides are scaled down together, so the curve keeps its shape. scripts/drive options lists the rest:
--bot sim-2 to start with a particular bot, --fleet for another fleet.
4. Two bots
Drive sim-1 forward, then press tab. The tool tells the station to stop sim-1 and let go of it, then selects
sim-2. Nothing moves until you press a key. Switching never hands your speed to a different bot. Letting go matters,
because while you hold a bot, nobody else can drive it.
Press 1 and 2 to pick bots by their number in the list. Press i to make the selected one wiggle, so you can tell which bot on the desk it is.
5. The e-stop
Press e. The tool sets its own e-stop, a retained message on estop/<its name> (the e-stop never goes through the
station), and stops the bot you were driving as well. The whole fleet stops while anyone’s e-stop is on. The screen
shows, with the tool’s own name:
E-STOP ON, set by drive-4821: e clears yours, E everyone's (an admin)
The browser shows the red banner, and every bot reports estop_on. Press w. Nothing happens, and the tool says
e-stop is on: e clears yours, E everyone's (an admin). Press e again to clear yours.
Anyone’s e-stop stops the fleet, not only the tool’s. Set one as someone else, from Terminal B, while you’re driving:
scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/other -m '{"stop":true}'
The tool sees it, shows set by other, and drops your speed and turn to zero. e now sets yours rather than
clearing theirs. Theirs is theirs to clear. E clears every one that’s on. On this machine’s broker that works for
anyone. On the cluster’s, only an admin’s login can clear someone else’s. Clear it from Terminal B:
scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/other -n
After it’s cleared you start from a standstill, which is what the bots require anyway (protocol rule 3).
6. If the tool dies
Drive a bot forward, then press Ctrl-C instead of q:
drive: interrupted, nothing sent. The station stops the bot within 0.5 s.
q stops the bot and lets go of it before quitting. Ctrl-C deliberately says nothing, to show what happens if the computer driving a bot crashes or loses its network. Its requests stop arriving. Half a second later the station notices and stops the bot itself. The power bars in the browser drop to zero. A second after that it lets go of the bot, so someone else can drive it.
If the station were gone too, the bot would still stop. With no commands coming, it stops itself after 500 ms, as you saw in tutorial 03.
7. Tidy up
Quit the tool if it’s still running, then Terminal B:
scripts/viewer down
scripts/station down
scripts/sim down
scripts/broker down
How it’s built: the codebase.
Check yourself
- You press w five times and a five times. What do
landrcome out as, with no cap? (2. Drive) - Why can line 3’s
seqbe a little behind line 2’s? (Reading the screen) - You’re driving
sim-1at full speed and press tab. What happens tosim-1? (4. Two bots) - What’s the difference between quitting with q and with Ctrl-C, for the bot? (6. If the tool dies)
Stuck?
- Run
./gunkslab doctor. It checks the container runtime and the ports, and printsFIXwith 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.