Skip to content
gunkslab

Tutorial 01 · 30 min

The MQTT broker

Every part of the fleet talks through one broker, Mosquitto. Here you’ll run it, send and watch messages, and try the four broker features the protocol depends on: topic wildcards, retained messages, QoS and last wills.

Do Install first. Use two terminal windows, both in the repo’s top folder.

1. Start the broker

Terminal A:

scripts/broker up
broker: up on 127.0.0.1:1883, WebSockets on 127.0.0.1:9001 (container, docker.io/library/eclipse-mosquitto:2.1.2-alpine)

The broker is running in a container and listening on port 1883, the standard MQTT port, on this machine only. Port 9001 is for web pages (MQTT over WebSockets). Tutorial 03 uses it. scripts/broker logs shows its log. Ctrl-C leaves it.

2. Watch, then send

Terminal A, start watching everything under gunkslab/:

scripts/broker watch

It sits there, printing nothing yet. Leave it running.

Terminal B, send one message:

scripts/broker send gunkslab/v0/desk/bot-1/telemetry '{"up_ms":1000,"rssi":-55,"l":0,"r":0}'

Terminal A prints it, topic first, then the message:

gunkslab/v0/desk/bot-1/telemetry {"up_ms":1000,"rssi":-55,"l":0,"r":0}

What just happened

  • Two clients, one broker. Terminal B connected to the broker, published one message on a topic, and disconnected. Terminal A had subscribed to gunkslab/#, so the broker passed the message on.
  • Neither knew about the other. Bots, the station and the page only ever talk to the broker.
  • The message is the protocol’s telemetry. What bot-1 would send ten times a second.

3. Topics and wildcards

A topic is a path, with levels separated by /. Subscribers pick topics with two wildcards:

  • + matches exactly one level.
  • # matches everything from there down. It can only go at the end.

Terminal A, stop the watch with Ctrl-C, then subscribe to every bot’s status and nothing else:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/status'

-t is the topic to subscribe to, and -v prints the topic with each message. Keep the quotes: without them the shell may try to expand + or #.

Terminal B, send three messages:

scripts/broker send gunkslab/v0/desk/bot-1/status '{"state":"online"}'
scripts/broker send gunkslab/v0/desk/bot-1/telemetry '{"up_ms":2000,"rssi":-55,"l":0,"r":0}'
scripts/broker send gunkslab/v0/desk/bot-2/status '{"state":"online"}'

Terminal A shows only the two statuses. The telemetry didn’t match:

gunkslab/v0/desk/bot-1/status {"state":"online"}
gunkslab/v0/desk/bot-2/status {"state":"online"}

The station will subscribe like this: gunkslab/v0/desk/+/status to see every bot come and go, gunkslab/v0/desk/+/telemetry for every bot’s telemetry.

Stop Terminal A with Ctrl-C.

4. Retained messages

A normal message goes to whoever is subscribed at that moment, and then it’s gone. A retained message is also kept by the broker, one per topic, and handed to anyone who subscribes later.

Terminal B, subscribe after the status messages from step 3 were sent. -W 2 gives up after 2 seconds:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/status' -W 2
Timed out

Nothing. Those messages went out in step 3 and weren’t kept. Now send a status as retained, with -r. pub takes mosquitto_pub’s own flags: -t is the topic and -m the message:

scripts/broker pub -r -t gunkslab/v0/desk/bot-1/status -m '{"state":"online"}'

And subscribe again, late:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/status' -W 2
gunkslab/v0/desk/bot-1/status {"state":"online"}
Timed out

The broker handed over the kept message straight away. That’s how a page opened at any moment knows which bots are online, and how a bot that boots during an e-stop learns about it. The protocol retains hello, status and each person’s estop.

To remove a retained message, publish an empty one, retained, on the same topic (-n sends an empty message):

scripts/broker pub -r -n -t gunkslab/v0/desk/bot-1/status
scripts/broker sub -v -t 'gunkslab/v0/desk/+/status' -W 2
Timed out

5. QoS: how hard the broker tries

QoS is set per message:

  • QoS 0: sent once. If it’s lost on the way, it’s lost.
  • QoS 1: sent until the receiver confirms it, so it arrives at least once (possibly twice).

-d prints what the client and broker say to each other. Terminal B:

scripts/broker pub -d -q 0 -t gunkslab/test -m hello
Client null sending CONNECT
Client (null) received CONNACK (0)
Client null sending PUBLISH (d0, q0, r0, m1, 'gunkslab/test', ... (5 bytes))
Client null sending DISCONNECT
scripts/broker pub -d -q 1 -t gunkslab/test -m hello
Client null sending CONNECT
Client (null) received CONNACK (0)
Client null sending PUBLISH (d0, q1, r0, m1, 'gunkslab/test', ... (5 bytes))
Client null received PUBACK (Mid: 1, RC:0)
Client null sending DISCONNECT

With QoS 1 the broker answers with a PUBACK: “got it”. Without that answer, the client would send it again.

The protocol uses QoS 0 for what repeats many times a second: cmd, telemetry and pose. A lost one is replaced by the next one within 100 ms, and resending an old command would be worse than losing it. QoS 1 is for what must arrive: hello, status, event and estop.

6. Last will: when a bot vanishes

When a client connects, it can leave a last will with the broker: a message for the broker to publish if the client disappears without saying goodbye. A bot’s will is {"state":"offline"} on its status topic, retained.

Terminal A, watch statuses again:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/status'

Terminal B, start a pretend bot-1. It’s mosquitto_sub, connected with a client ID (-i bot-1), a 5-second keep-alive (-k 5) and a will. It listens on its cmd topic. The & at the end runs it in the background, so you keep the prompt:

scripts/broker sub -i bot-1 -k 5 -t gunkslab/v0/desk/bot-1/cmd --will-topic gunkslab/v0/desk/bot-1/status --will-payload '{"state":"offline"}' --will-retain --will-qos 1 &

A real bot announces itself once connected, so do that for it:

scripts/broker pub -r -q 1 -t gunkslab/v0/desk/bot-1/status -m '{"state":"online"}'

Terminal A:

gunkslab/v0/desk/bot-1/status {"state":"online"}

First, a clean exit. %1 is the background job you started:

kill %1

Terminal A shows nothing new. The pretend bot said goodbye properly, so the broker threw its will away.

Now start it again, and this time pull the plug:

scripts/broker sub -i bot-1 -k 5 -t gunkslab/v0/desk/bot-1/cmd --will-topic gunkslab/v0/desk/bot-1/status --will-payload '{"state":"offline"}' --will-retain --will-qos 1 &
scripts/broker unplug bot-1
broker: unplugged bot-1
[1]+  Exit 137    scripts/broker sub -i bot-1 ...

Terminal A:

gunkslab/v0/desk/bot-1/status {"state":"offline"}

unplug killed the pretend bot outright, with no goodbye, and the broker published its will for it. Because the will is retained, anyone who looks later sees it too:

scripts/broker sub -v -t 'gunkslab/v0/desk/+/status' -W 2
gunkslab/v0/desk/bot-1/status {"state":"offline"}
Timed out

Why the keep-alive matters

  • Here the will came at once. Killing the process closed its network connection, and the broker saw that straight away.
  • A real power cut doesn’t close anything. The bot goes silent. The broker only notices when the keep-alive runs out: no message or ping for one and a half times the keep-alive. With -k 5, that’s 7.5 seconds.
  • The firmware’s keep-alive is a setting to choose. Shorter means a dead bot is noticed sooner, at the cost of more pings.

7. Tidy up

Stop Terminal A with Ctrl-C. Clear the retained status, then stop the broker:

scripts/broker pub -r -n -t gunkslab/v0/desk/bot-1/status
scripts/broker down
broker: down

The broker keeps nothing between runs (persistence false in broker/mosquitto.conf), so the next up starts clean even if you skip clearing.

Next: 02. Protocol v0 by hand.

Check yourself

  1. Which of these does gunkslab/v0/+/+/status match: gunkslab/v0/desk/bot-1/status, gunkslab/v0/desk/status, gunkslab/v0/lab/sim-3/status? (3. Topics and wildcards)
  2. The page opens five minutes after the bots connected. How does it know which are online? (4. Retained messages)
  3. Why is cmd sent with QoS 0, when losing a command sounds bad? (5. QoS)
  4. A bot’s battery dies. How long until its status says offline, with a 5-second keep-alive? (6. Last will)

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.