Pi IoT Academy
Phase 7 · Your First Module

Phase 07

Your first module.

The platform’s ready. The dashboard is polished. Claude is listening. Time to give it real, classroom-grown data: connect a BBC Micro:bit (or ESP32 if you’re feeling fancy), watch your sensor appear on the screen, and take snapshots through the lesson to compare. By the end of this phase you have a complete, teachable IoT lab.

~60–90 min Difficulty: 3 / 3 Real hardware! Final phase

What a module is

Read this first.

Up to now you’ve only had fake data — the test publisher script. A module is a real, packaged classroom project: hardware + code + a lesson plan + a place on the dashboard. The platform is designed to host many of them; this is the first.

The Classroom Sensor Hub module includes:

module.yaml
A small manifest file with the module’s name, version, and which MQTT topics it owns.
microbit/
A MicroPython program for the Micro:bit V2, plus a tiny serial-to-MQTT bridge that runs on the Pi.
esp32/
An Arduino sketch for any ESP32 dev board, paired with a DHT22 sensor.
README.md
Lesson plan, troubleshooting guide, ideas for extension.

Phase 7 also adds one new platform feature: snapshots. Tap a button on the Sensors page and the platform freezes the current state of every sensor into a row in the database. Useful for “before” / “during” / “after” comparisons during a lesson.

Why two boards?

The Micro:bit is great for Year 7 — it’s familiar, easy, and has a built-in temperature sensor. It connects via USB so your teacher just needs the cable.

The ESP32 is a bigger jump but more grown-up: it has Wi-Fi, so each pair can run their own board independently across the room. We provide both so the lesson can scale up later.

Pull and rebuild

~5 minutes · on the Pi

The platform code has new bits: a snapshots table, an API to capture them, a button on the Sensors page, and the module folder.

terminal · on the Pi
cd /opt/iot-platform
git pull
docker compose build api frontend
docker compose up -d

Watch the API logs:

terminal · on the Pi
docker compose logs -f api

You should see Alembic apply the new migration:

expected
INFO  alembic.runtime.migration  Running upgrade 0001 -> 0002, snapshots
Checkpoint

See the module tile

~3 minutes

Open the dashboard. Click the ▦ Modules icon in the sidebar.

The Classroom Sensor Hub tile should no longer be greyed out. It now has a green LIVE badge instead of Phase 7. Tap it — you’ll be taken back to the Sensors page (because the module’s data lives there).

Also notice on the Sensors page: when you have at least one sensor reading, a Take snapshot button appears in the top-right.

Checkpoint

Pick your hardware

~2 minutes

Pick the path that matches your kit:

Path A — Micro:bit V2
USB cable + Mu Editor on a laptop. The Pi runs a tiny bridge to forward serial data to MQTT. Built-in temperature + light sensors.
Path B — ESP32 + DHT22
Arduino IDE + Wi-Fi. Each board talks MQTT directly. Real temperature + humidity from the DHT22.

Don’t do both at the same time on your first try — pick one, get it working, then come back for the other if you have time.

Your teacher will choose

Year 7s usually start with Path A (Micro:bit). Year 8–9s with Path B (ESP32). They’ll tell the class which kit you’re using today.

Checkpoint

Path A: Micro:bit

~25 minutes · in pairs

The Micro:bit prints sensor readings over USB. The Pi listens on that USB and forwards each one as MQTT.

4a. Flash the program

  1. Plug the Micro:bit into the laptop with the USB cable. A new drive called MICROBIT appears.
  2. Open Mu Editor. Set Mode to “BBC micro:bit”.
  3. Open modules/classroom-sensor-hub/microbit/main.py from the platform repo.
  4. Change DEVICE_ID at the top to a unique name, like microbit-03 for pair 3.
  5. Click Flash. The yellow LED on the back flickers; a heart briefly appears on the front. Done.

4b. Plug into the Pi and run the bridge

Move the Micro:bit’s USB cable from the laptop to the Pi. The Pi will recognise it as /dev/ttyACM0. Then on the Pi:

terminal · on the Pi (one-off install)
pip install pyserial paho-mqtt
terminal · on the Pi
cd /opt/iot-platform/modules/classroom-sensor-hub/microbit
export MQTT_PASSWORD="<your MQTT password from .env>"
python3 serial-bridge.py /dev/ttyACM0

You should see lines tick by:

expected
→ opening serial /dev/ttyACM0 @ 115200
→ connecting to MQTT 127.0.0.1:1883 as platform
✓ bridge running. Ctrl-C to stop.

  → classroom/sensor/microbit-03/temperature: 23 celsius
  → classroom/sensor/microbit-03/light: 145 lux

4c. Watch the dashboard

Switch to the dashboard. Within a second you’ll see two new cards: microbit-03 / temperature and microbit-03 / light. Cover the Micro:bit with your hand — the light value should drop sharply.

The temperature is high

The Micro:bit’s “temperature sensor” is actually reading the chip itself, which runs hot. You’ll see numbers like 25–30 °C in a 20 °C room. That’s a teaching moment: real-world sensors have quirks — the data isn’t lying, it just isn’t measuring what you expect.

Tap the temperature card. The chart updates in real time. Tap Explain this reading — Claude will write a sensible-sounding explanation. (Claude doesn’t know about the chip-warmth quirk; it might claim the room is warm. Discuss this in class!)

Checkpoint

Path B: ESP32

~25 minutes · in pairs

An ESP32 has Wi-Fi built in. It connects directly to the platform’s MQTT broker over the school network — no Pi-side bridge.

5a. Wire the DHT22

Three jumper wires:

wiring
DHT22 pin     ESP32 pin
---------     ---------
VCC      ->   3V3
DATA     ->   GPIO 4
GND      ->   GND

5b. Flash the sketch

  1. Open the Arduino IDE.
  2. If you don’t have ESP32 board support yet, follow the README in modules/classroom-sensor-hub/esp32/ — it’s a one-time install.
  3. Open modules/classroom-sensor-hub/esp32/sensor-hub.ino.
  4. Edit the configuration block at the top:
    • WIFI_SSID, WIFI_PASS — school Wi-Fi.
    • MQTT_HOST — your Pi’s hostname (e.g. pi-iot-01.local).
    • MQTT_PASS — the MQTT password from .env.
    • DEVICE_ID — unique per board.
  5. Plug the ESP32 in. Tools → Board → ESP32 Dev Module; Tools → Port → the new device.
  6. Click Upload.
  7. Open Tools → Serial Monitor (115200 baud) and watch it boot.

5c. Watch the dashboard

Once the serial monitor shows MQTT: connecting… ok, two new cards appear on the dashboard: esp32-XX / temperature and esp32-XX / humidity. Breathe near the DHT22 — the humidity should jump.

If MQTT connect fails

The most common causes: wrong password (re-check .env on the Pi), school Wi-Fi blocking port 1883 (try a phone hotspot), or the ESP32 can’t resolve .local (use the Pi’s IP address instead).

Checkpoint

Snapshots through the lesson

~10 minutes

Once the room has at least one sensor publishing, take three snapshots through the lesson:

  1. Start of class — before anyone’s warmed the room up.
  2. Middle — mid-experiment.
  3. End — after the lesson’s activity.

Each tap of Take snapshot writes a row to the snapshots table with every sensor’s current value. You’ll see a confirmation like “Saved snapshot #1 (4 sensors)” appear next to the button.

To browse them, go to Settings → Recent snapshots. They’re listed newest first with their ID, label, timestamp, and sensor count.

You can also pull a specific snapshot via the API:

terminal · anywhere
curl -s http://pi-iot-XX.local/api/snapshots/1 | python3 -m json.tool

You’ll get the full set of readings as they were at that moment — perfect for class discussion or a science write-up.

Lab notebook moment

Real scientists save their measurements with timestamps so they can prove what they did. Snapshots are exactly that. Phase 4’s database stores every individual reading; snapshots are just marker pins that say “the room looked like this at this moment”.

Checkpoint

Final verification

5 minutes

The class should be able to do everything below. Tick each one before declaring Phase 7 (and the whole course!) done.

Phase 7 sign-off — the Year 7 user journey

You did it.

You’ve built a portable IoT and AI teaching terminal — from a blank Pi, through MQTT and a real database, a touchscreen UI, an LLM in the loop, and your own classroom hardware module. Real software engineers do this for a living. Real Year 7s now have a tool to ask “what does this sensor mean?” and get an answer.

What’s next is up to you:

  • Build a second module — a weather station for the playground, a greenhouse monitor.
  • Add more sensors to the Sensor Hub: a soil-moisture probe, a CO₂ sensor.
  • Tweak the prompt template in services/ai/app/prompts/ to give explanations a different audience or tone.
  • Show off the kit at a school open day.
Back to all phases  →