Skip to content
gunkslab

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 boot event: it started from power-on. brownout there 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_stop event.
  • 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

  1. In what order does a bot connect, and why does the last will come first? (2. Connect the bot)
  2. Why does a bot wait for its marker to come back before it subscribes to cmd? (Stops before commands)
  3. The station sends "seq":7 and telemetry keeps saying "seq":5. What does that tell you? (4. Drive it)
  4. The station sends one command and then crashes. What does the bot do, and when? (The dead-man rule)
  5. Why is the e-stop retained, but cmd isn’t? (6. The e-stop, 7. What a station sees)
  6. 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 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.