Tutorial 02 · 30 min
Protocol v0 by hand
Speak the protocol yourself, before any program does. Be a bot announcing itself, be the station driving it, then set and clear the e-stop. Last, break a message on purpose and watch the checker catch it.
Do 01. The MQTT broker first. Use three terminal windows, all in the repo’s top folder:
- Terminal A watches everything.
- Terminal B is the bot’s ears: what the bot receives.
- Terminal C is your hands: you publish as the bot and as the station.
Keep the protocol reference open beside it. This tutorial follows its topics table and rules.
1. Start the broker and watch
Terminal A:
scripts/broker up
scripts/broker watch
up prints broker: up on 127.0.0.1:1883, and the rest of the line, or broker: already up if it’s still running
from tutorial 01. watch prints nothing yet. It waits, and prints each message on a gunkslab/ topic as it arrives.
Leave it running.
2. Connect the bot
A real bot does three things on connect (rule 1 in the protocol): it sets its last will, announces itself, and subscribes to the fleet’s e-stop and then its commands, in that order. You’ll do the subscribing and the will in Terminal B, and the announcing from Terminal C.
To save typing, set the bot’s topic prefix in both Terminal B and Terminal C:
T=gunkslab/v0/desk/bot-1
Terminal B, connect as bot-1, with its will, listening on three topics (-t three times: everyone’s e-stop,
estop/+, its own sync, and its cmd):
scripts/broker sub -v -q 1 -i bot-1 -k 5 -t 'gunkslab/v0/desk/estop/+' -t $T/sync -t $T/cmd --will-topic $T/status --will-payload '{"state":"offline"}' --will-retain --will-qos 1
Stops before commands
A bot must have every e-stop in force before it takes a single command. The e-stops are retained, so the broker
sends them to a bot as soon as it subscribes, but a command can still get there first (the protocol’s “Stops before
commands” says how). So a real bot doesn’t subscribe to cmd straight away. It subscribes to estop/+ and its own
sync, then sends itself a marker on sync. The broker queues the kept e-stops ahead of the marker, so when the
marker comes back, every e-stop has arrived. Only then does the bot subscribe to cmd.
scripts/broker sub can’t add a topic once it’s connected, so Terminal B listens on all three from the start. That’s
safe here only because nothing sends bot-1 a command until section 4. Send the marker from Terminal C, 16 hex
digits of your own:
scripts/broker pub -q 1 -t $T/sync -m '{"marker":"0123456789abcdef"}'
Terminal B shows it come back:
gunkslab/v0/desk/bot-1/sync {"marker":"0123456789abcdef"}
If an e-stop had been kept, it would show above the marker. A real bot picks a new marker each time it connects, and ignores one it didn’t just send.
Terminal C, announce it: first hello, then status. Both retained (-r) and QoS 1 (-q 1), as the topics
table says:
scripts/broker pub -r -q 1 -t $T/hello -m '{"type":"gl-zero","fw":"0.2.0","drive":"skid","encoders":false,"sensors":["imu"],"commands":["wheels","stop","identify"]}'
scripts/broker pub -r -q 1 -t $T/status -m '{"state":"online"}'
And the boot event, with why it last restarted:
scripts/broker pub -q 1 -t $T/event -m '{"up_ms":812,"kind":"boot","reset_reason":"power_on"}'
Terminal A:
gunkslab/v0/desk/bot-1/hello {"type":"gl-zero","fw":"0.2.0","drive":"skid","encoders":false,"sensors":["imu"],"commands":["wheels","stop","identify"]}
gunkslab/v0/desk/bot-1/status {"state":"online"}
gunkslab/v0/desk/bot-1/event {"up_ms":812,"kind":"boot","reset_reason":"power_on"}
What the station learns from this
- From
hello: a gl_zero, firmware 0.2.0, skid steer, no encoders (so it can’t drive a set distance by itself), an IMU, and three commands it understands. - From the
bootevent: it started from power-on.brownoutthere instead would mean its battery sagged.
3. Report telemetry
A real bot sends this ten times a second. Send one, Terminal C:
scripts/broker send $T/telemetry '{"up_ms":1000,"rssi":-55,"l":0,"r":0,"stopped":true}'
It says: up for 1 second, Wi-Fi at -55 dBm (a good signal), wheels at 0, stopped.
4. Drive it, as the station
Now you’re the station. Terminal C, drive forward at half power, as command number 1:
scripts/broker send $T/cmd '{"l":0.5,"r":0.5,"seq":1}'
Terminal B, the bot’s ears, receives it:
gunkslab/v0/desk/bot-1/cmd {"l":0.5,"r":0.5,"seq":1}
A real bot would start driving, and its next telemetry would show the power applied and echo seq. Send that for
it:
scripts/broker send $T/telemetry '{"up_ms":1100,"rssi":-55,"l":0.5,"r":0.5,"seq":1,"stopped":false}'
When the station sees "seq":1 come back, it knows the bot obeyed, and how long that took.
The dead-man rule
- A real bot would stop 500 ms later. You sent one command, then nothing (rule 2). It would send a
timeout_stopevent. - That’s why the station repeats commands while driving, at least every 250 ms, even when nothing changes.
- Typing can’t keep up with that. The driving tool and the simulator, coming next, will.
5. Which bot is which?
Terminal C:
scripts/broker send $T/cmd '{"identify":true,"seq":2}'
Terminal B:
gunkslab/v0/desk/bot-1/cmd {"identify":true,"seq":2}
A real bot wiggles or blinks for under 2 seconds (rule 7), so you can see which of four identical bots is bot-1.
6. The e-stop
Everyone has an e-stop of their own, a retained message on estop/<their name>, and the whole fleet stops while any
of them is on. You’re me. Terminal C:
scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/me -m '{"stop":true}'
Terminal B gets it:
gunkslab/v0/desk/estop/me {"stop":true}
The bot would stop, ignore every cmd, and report it:
scripts/broker pub -q 1 -t $T/event -m '{"up_ms":5200,"kind":"estop_on"}'
Because the e-stop is retained, a bot that connects during it is stopped straight away. Pretend to be a second bot connecting now, Terminal C:
scripts/broker sub -v -t 'gunkslab/v0/desk/estop/+' -W 2
gunkslab/v0/desk/estop/me {"stop":true}
Timed out
It knew at once. Clear yours: an empty retained message (-n) takes the retained one away.
scripts/broker pub -r -q 1 -t gunkslab/v0/desk/estop/me -n
A real bot would drive again only after a fresh cmd, not by picking up where it was (rule 3). If someone
else’s e-stop were on too, it would stay stopped. On the cluster’s broker you clear only your own. Theirs is theirs
to clear, or an admin’s.
7. What a station sees when it starts
A station that starts now has missed everything above. Subscribe the way it would, Terminal C:
scripts/broker sub -v -t 'gunkslab/v0/desk/+/hello' -t 'gunkslab/v0/desk/+/status' -t 'gunkslab/v0/desk/estop/+' -W 2
gunkslab/v0/desk/bot-1/hello {"type":"gl-zero","fw":"0.2.0","drive":"skid","encoders":false,"sensors":["imu"],"commands":["wheels","stop","identify"]}
gunkslab/v0/desk/bot-1/status {"state":"online"}
Timed out
From the retained messages alone it knows which bots exist, what they are, which are online, and whether any e-stop is on. None is, since you cleared yours. Telemetry, events and commands weren’t retained, so they’re gone.
8. Pull the bot’s plug
Terminal C:
scripts/broker unplug bot-1
Terminal B’s subscription ends, and Terminal A shows the will:
gunkslab/v0/desk/bot-1/status {"state":"offline"}
9. Break a message on purpose
The protocol’s message layouts are in protocol/schemas/, one file per message. Each one says exactly which fields
are allowed and what values they can take. protocol/examples/ holds sample messages: everything in good/ must
pass and everything in bad/ must fail.
Make a command with the left side at power 2, outside the allowed -1 to 1, and file it as good:
echo '{"l":2,"r":0}' > protocol/examples/good/cmd.mine.json
scripts/check-protocol
FAIL good/cmd.mine.json: {'l': 2, 'r': 0} is not valid under any of the given schemas
15 schemas, 1 failures
The checker caught it. The message is “not valid under any of the given schemas” because a cmd can take three
forms (wheels, stop and identify), and it fits none of them. Look at protocol/schemas/cmd.schema.json to see the
three.
Try a few of your own, then remove the file:
{"l":0.5}, a missing side.{"l":0.5,"r":0.5,"speed":3}, an unknown field.{"stop":true,"l":0.5,"r":0.5}, stop and drive at once.
rm protocol/examples/good/cmd.mine.json
10. Tidy up
Stop Terminal A with Ctrl-C, then:
scripts/broker down
Check yourself
- In what order does a bot connect, and why does the last will come first? (2. Connect the bot)
- Why does a bot wait for its marker to come back before it subscribes to
cmd? (Stops before commands) - The station sends
"seq":7and telemetry keeps saying"seq":5. What does that tell you? (4. Drive it) - The station sends one command and then crashes. What does the bot do, and when? (The dead-man rule)
- Why is the e-stop retained, but
cmdisn’t? (6. The e-stop, 7. What a station sees) - Is
{"identify":true,"l":0.5,"r":0.5}a valid command? Check it with the checker. (9. Break a message)
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.