MQTT messaging lab: how devices talk to a broker, in the browser

This lab gives each student an MQTT broker of their own and a few pretend sensors that publish to it. A house sends a reading every second: the temperature and humidity of the living room, the temperature of the kitchen and whether the door is open or closed. Students listen to them from the terminal and write one message of their own.

It is not an attack lab. Every copy has no route to the internet and none to any other student, so nothing can be downloaded into it and nothing in it can reach anybody else. It is also not how a real installation looks: real devices connect over a network with a sign-in and an encrypted connection, and this lab leaves both out, so that the first thing learned is the messaging itself.

What students learn

How devices and the things that use them are kept apart by a broker: a sensor publishes a message with a topic, the broker passes it to everybody who has subscribed to that topic, and neither side knows the other. Students read every topic under home with the # wildcard, only the temperatures with the + wildcard, and see that a retained message, the door state, is given at once to a new subscriber while the humidity, which is not retained, has to wait for the next reading. Then they publish a retained message of their own and read it back. It suits introductions to the internet of things, networks and distributed systems; check your own awarding body’s unit for the exact wording, none is quoted here.

Run it in your browser

The lab starts two services from the same stock public image: broker, which is the MQTT broker, and sensors, a loop that publishes four readings every second once the broker is ready. There is no web page, so the lab bar has no link under In your browser, and the terminal is how you listen. It reaches the broker’s own tools with docker exec broker, followed by the command, and each listening command is ended with the options -C, how many messages, and -W, how many seconds, so it always finishes. The readings come from a fixed cycle of whole numbers, but where in the cycle you are depends on the moment you press Run, so two students see different numbers.

  1. Open the Container page. Open Build on the bar and choose Run a container. Anybody may open it, and the Git lab and the SQL lab start with no account. Every other lab needs a free account: create one, sign in, then press Start.
  2. Find the lab. The Sample labs card lists every sample. Find MQTT: how devices talk to a broker.
  3. Press Start. Start runs it as it is, in one press. Edit the file first opens the compose file so you can change it before you start.
  4. Open it. There is no web page to open. On the lab’s page press Open terminal and type docker exec broker mosquitto_sub -t 'home/#' -v -C 8 -W 10 to hear eight messages: each line is a topic, a space and a value.

What to ask students to hand in

The commands they ran and what each printed: one that reads every topic under home, one that reads only the temperatures with a wildcard, one that reads the retained door state, and one message of their own published with -r and read back. Then a sentence or two in their own words on what a retained message is for and why the door answered at once while the humidity did not. Nothing is marked automatically: the sentence shows whether it was understood. For stronger work ask what a real device would need that this lab leaves out.

A basic lesson on this lab

IoT Messaging Basics is a small lesson worked in this lab. In it a student listens to every topic with a wildcard, narrows it to the temperatures, compares a retained message with one that is not, and publishes a message of their own and reads it back.

Free personal accounts have it in the Basics module, which is on Home, and every college can copy it from the Library’s Basics folder. It is deliberately small: it shows a teacher what a lesson worked in a lab is, and the lab does the rest. Copy it into a module of your own to change it.

The code on GitHub

The compose file has no Dockerfile: it runs one stock public image, the Eclipse Mosquitto broker, pinned to a major version, twice, as an unprivileged account with 64 MB of memory each. The image is licensed under the Eclipse Public License and the Eclipse Distribution License and is not distributed by us. The file writes the broker’s small configuration when it starts, with a listener on port 1883 and anonymous access allowed, and the sensors are a shell loop with fixed values, so nothing is downloaded. The limits are honest ones: there is no sign-in and no encryption, nothing is kept when the lab stops, and the sensors are pretend, so a real device’s behaviour, such as losing its connection, is not shown.

Set it as work

Say in the task what to hand in.

  1. Make the lab. In your module add a task and choose the Container lab card, then In a GitHub repository. Give https://github.com/mitsurutech/lab-iot-mqtt with the branch main. The compose file is the default, compose.yaml. Fork the repository first if you want to change it, for example to add more sensors.
  2. Publish and try it. Publish pins the commit you were shown, so a later change in the repository does not alter a lab you have already set. Start your own copy first.
  3. Hand it out. Assign it like any task, with a due date if you want one, and say in the task what to do and what to hand in.
  4. Mark what is handed in. Open a student’s copy and the work they handed in, mark it, and send it back with a reason if it needs more.

Try this lab, and what it costs

A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.

Questions people ask

Why does the broker let anybody in without a password?
The lab’s broker is reachable only from inside your own copy, and the copy has no way out to the internet, so nobody else can connect to it. That is the only reason it is safe. A real broker needs a sign-in and an encrypted connection, and you should never set one up the way this lab does.
Why do the numbers I see differ from the lesson’s?
The sensors follow a fixed cycle that never stops, so the same few values come round again and again, but where the cycle has reached when you press Run depends on the moment. The shape of each answer is always the same: the same topics, whole numbers, and a door that is open or closed. The one exact line is your own message read back.
Can students add their own sensors or devices?
Yes: from the terminal, docker exec broker mosquitto_pub publishes a message to any topic they like. To change the sensors themselves, fork the repository, change the shell loop in the compose file, and set the fork as the lab.