Skip to content
TESA Open Knowledge

Hands-on: running lights, a button, and the broker

Module 2 — From Screen to Hardware · Slides: slides.md · Module overview · Course page

Fill six blanks to get an LED chase over every LED with an adjustable tempo and a button that counts ten presses as exactly ten, then carry one press to a web page through a broker while coding around the firmware’s real limits.

Objectives

Section titled “Objectives”

By the end of this lesson you will be able to:

  1. Fill the six blanks in practice/s03_led_button.py until it passes the MVP: a chase over every LED gpio.num_leds() reports, a tempo that changes with at least two STEP_MS values, ten presses of the user button showing exactly ten, and every LED off with a green summary line at the end
  2. Match the common symptoms (count jumps by 3-5, by 2, not at all, chase stuck on one LED, two LEDs lit) to their causes and fixes, and explain to the instructor what happens without the debounce code and why
  3. Run 07_button_to_broker.py with your own team name until my_first_reader.html shows telemetry every 2 seconds and an event on each press, and explain how always-false retain, the one-slot inbox, OSError on a dropped link and unique client_id shape the code
  4. Explain why the class reaction game times each press on the board rather than by arrival order, and why it records the time when the pin first changes rather than when debounce confirms

Before you start

Section titled “Before you start”

You must have finished lesson 2.2, because this lesson assembles the five moves of that lesson’s solution file, walked through there piece by piece, into your team’s own program. The broker uses the same setup from lessons 1.4–1.6: your team’s phone hotspot (name and password) and the same unique TEAM code, such as nok4821 (if learning in a group, use the team number your organiser hands out). On the board’s screen, keep the BENTO Playground card open, and have your phone camera ready to photograph the lights and screen for your learning log.

  • Equipment: an Eva Kit or TESAIoT Dev Kit board with the BENTO MicroPython firmware installed, or the BENTO Emulator in BENTO IDE (07_button_to_broker.py on the Emulator can now reach the real broker — it appends -emu to its client_id so it never kicks your team’s board off; 08_class_race.py has not yet been tried on the Emulator and does not hear commands from the front of the room)
  • Before this: Lesson 2.2 — Behind LEDs and buttons: active-low, debouncing and the endless loop

Concepts

Section titled “Concepts”

The MVP for lessons 2.1–2.3 is a chase running over every LED the board has, with an adjustable tempo, plus a user button (referred to by the name from .name()) that counts presses on screen. The hardest part is not making it work, but being able to explain what happens if the debounce code is removed — and notice that the first three traps in the slides’ table are matters of timing logic, not syntax, which is a defining trait of embedded work.

The solution file puts the four values you adjust most often at the top, as the program’s dashboard (STEP_MS, DEBOUNCE_MS, POLL_MS, RUN_MS), so the “adjustable tempo” requirement comes down to editing just STEP_MS. Inside the loop there are four unequal beats: the button is polled every 5 ms, the light advances every 150 ms, the screen refreshes every UI_MS = 100 ms (calling ui.poll() every loop round fires IPC across the cores 200 times a second, waiting for a finger that arrives maybe once a second), and the number a person has to read is rewritten no more than once a second. All of this uses a single now = time.ticks_ms() value per round, and time.sleep_ms(POLL_MS) at the end of the loop is the only point where the program agrees to rest. The panel on screen is built once before entering the loop; the “run” and “stop” buttons for the chase are deliberately separate, and the confirmation box is created and hidden from the very start.

The five moves are ordered as layer-by-layer bring-up: ask the board → turn everything off → run the chase (work that depends on no input from anyone; if it runs, the loop structure and clock are correct) → the button (if something breaks here, you know for certain it broke at the button or the debounce) → wrap-up. Filling the blanks follows this same order.

Reaching the broker takes just three additions to the same loop: two send() calls and one get_message() call. Each team gets three topics: bento-aiot/<team>/event (the instant a debounced press happens), …/telemetry (every 2 seconds), and …/cmd (the web page commanding the board). Every message carries a running n; the other side seeing the number jump knows a message went missing. Four firmware limits are design facts, not flaws to blame: publish() always sends with retain = false, so telemetry must be resent every 2 seconds · get_message() is a one-slot inbox, a new message overwrites the old, so it must be picked up every loop round · publish() raises OSError when the link drops, which send() catches and turns into returning False, so the loop can stop politely · it never reconnects on its own and clean_session is always true, so is_connected() must be asked every round, and client_id cannot collide — whoever connects later kicks the earlier one off — so file 07 can only run on one board per team.

Worked example

Section titled “Worked example”
  1. 07_button_to_broker.py — edit the top four lines (WIFI_SSID, WIFI_PASS, BROKER, TEAM); never edit ROOT or DEVICE_ID. If TEAM is not changed from teamXX, the program refuses to run. Open my_first_reader.html using the link in the slides with ?team= appended, followed by the same code as TEAM. Wait for the status line to say connected, then run it on the board. Predict first what will change on the web page after one press of the button. The public broker is unencrypted; anyone can subscribe and read it — never send anything secret — and listen only to bento-aiot/<team>/#, never subscribe to #.
  2. 08_class_race.py — use this when several teams are learning at once and the educator projects class_game.html. Before the first round, write your guess in your learning log: is the team whose result appears first on the front-of-room screen actually the fastest, and why or why not? Then try item 2 in the “your turn” block at the end of the file to measure the effect of the 40 ms debounce for yourself. During a round, try to find which line in the file rejects an led or beep command another team sends in to interfere.
File What this file teaches
examples/07_button_to_broker.py A button and a light on our desk end up on the broker, for a web page to read
examples/08_class_race.py A class-wide reaction game; the educator starts the round, and every team’s board times itself

The slides for this lesson also refer to files that live in other lessons:

Screens from the BENTO Emulator for this lesson’s examples (click a file name to open the code)

examples/07_button_to_broker.py running in the BENTO Emulator: A button and a light on our desk end up on the broker, for a web page to read
07_button_to_broker.py A button and a light on our desk end up on the broker, for a web page to read
examples/08_class_race.py running in the BENTO Emulator: A class-wide reaction game; the educator starts the round, and every team's board times itself
08_class_race.py A class-wide reaction game; the educator starts the round, and every team's board times itself

Practice

Section titled “Practice”

The practice file has six # เติม: (fill in) blanks. Watch your indentation carefully — the middle three sit at different nesting levels, and getting the indentation wrong makes Python put the code under the wrong condition.

  • Blank 1: gpio.led(i).off() in the loop that turns off the lights before starting
  • Blank 2: led_index = (led_index + 1) % NUM_LEDS between turning off the current LED and lighting the new one
  • Blank 3: raw = btn.is_pressed() at the start of move 4
  • Blank 4: last_change = now in the branch where the raw value has just moved
  • Blank 5: count += 1 under if stable:
  • Blank 6: the green summary lcd.print line after the loop

Fill in blanks 1–2 and run it first — the chase must run over every LED (pressing the button does nothing yet at this point, because raw is preset to False so the file can still run). Then fill in blanks 3–5 and press ten times — you must get exactly ten. Finally fill in blank 6. Once the chase works but the button is broken, you know right away the problem is not the lights. If you get stuck, open the files from lesson 2.2: for a light stuck on or left lit at the end, see 02_led_blink.py; for an inverted button, see 04_button_active_low.py; for an inflated count, see 05_debounce_count.py; and for not remembering which LED is lit, see 06_button_picks_led.py.

Practice file Topic
practice/s03_led_button.py An LED chase over every LED plus a debounced button counter (fill-in version)

Solution

Section titled “Solution”

Open the solution after trying on your own at least once, and read how to use the solutions first.

Solution Goes with
solution/s03_led_button.py practice/s03_led_button.py

Check your understanding

Section titled “Check your understanding”

The same questions are in quiz.yaml for automatic marking.

  1. A team fills in only blanks 1–2 in the practice file and presses Program to Device. What do they see? (choose one · objective 1)

    • A) The chase runs over every LED, but pressing the button does not move the counter, because raw is still the False it was preset to
    • B) The program stops immediately with NameError, because the line raw = btn.is_pressed() does not exist yet
    • C) The chase does not run, because the loop must wait for a press before it moves the light
    • D) The chase runs and the button counts, but it overcounts, because the debounce part has not been filled in yet
    Solution

    A — The chase is work that depends on no input from anyone, so it runs right away after blanks 1–2. raw is preset to False so the file does not crash, but the button is not yet read at all. Filling in group by group like this lets you know that if the button breaks later, the problem is not the lights.

  2. Which symptom-to-cause pairs are correct? Choose every correct one. (choose all that apply · objective 2)

    • A) One press, the count jumps by 3-5 ← not debounced yet, or DEBOUNCE_MS is too low
    • B) Pressing does the count nothing at all ← a long sleep_ms in the loop; the press is missed during the sleep
    • C) Two LEDs light at once ← lighting the new one before turning off the current one
    • D) The screen shows no number but the chase runs fine ← DEBOUNCE_MS is too high
    • E) The chase does not run, stuck on one LED ← forgot if stable
    Solution

    A, B, C — the first three match the traps table. The screen showing no number while the chase runs fine is really caused by not keeping the Playground page open, and the chase stuck on one LED is caused by last_step = now sitting outside the if. Forgetting if stable makes the count jump by two instead.

  3. Why does 07_button_to_broker.py resend telemetry every 2 seconds, even when the state may not have changed at all? (choose one · objective 3)

    • A) Because this firmware’s publish() always sends with retain = false; the broker keeps no last message, so a web page opened later must wait for the next one
    • B) Because the public broker disconnects if no data arrives within 2 seconds
    • C) Because the board’s inbox has only one slot, and must send before it can receive
    • D) Because an event might be sent twice, so telemetry is needed to remove the duplicate
    Solution

    A — publish() always sends with retain = false, even though the docstring appears to accept a retain= argument. If it only sent on a change, a web page opened later would see a blank screen. Resending every 2 seconds means even the slowest web page to open catches up within 2 seconds.

  4. Which statements are correct about writing 07_button_to_broker.py around the firmware’s limits? Choose every correct one. (choose all that apply · objective 3)

    • A) You must debounce before publishing, or one press becomes several messages on the broker, and a reader on the other side cannot tell which message is the real press
    • B) Send the LED status from the leds variable that handle() records, not from gpio.led(i).value()
    • C) Pick up get_message() every loop round, because the inbox has only one slot and a new message overwrites the old
    • D) Two people on a team can run file 07 with the same TEAM on two boards at once, because the broker separates them automatically
    • E) If the link drops, publish() already returns False on its own, so nothing needs to be caught
    Solution

    A, B, C — client_id cannot collide; whoever connects later kicks the earlier one off. File 07 uses bento-aiot- followed by the team name, so it can only run on one board per team, and publish() raises OSError when the link drops rather than returning False, so send() must catch it.

  5. Which statements about timing in the class-wide reaction game (08_class_race.py) are correct? Choose every correct one. (choose all that apply · objective 4)

    • A) The team whose result appears first on the front-of-room screen may not be the fastest, because each board picks its own random wait and messages travel for different amounts of time
    • B) The board records the time when the pin first changes, then uses that time once debounce confirms it was a real press
    • C) If timed at the moment debounce confirms it, every team would get a time 40 ms faster than reality
    • D) Pressing faster than 100 ms after the light turns on counts as the best result of the round
    Solution

    A, B — We measure on the board, between its own LED and its own button, so the message’s travel time is not part of the number. The 40 ms debounce makes the board believe a press later than the finger did; timing at the moment of belief would make every team’s time slower than reality, not faster, and a press faster than 100 ms counts as a false start.

Lab

Section titled “Lab”

The MVP for lessons 2.1–2.3. Do this on a real board or the Emulator, and record the results in your learning log.

  • The chase runs in a full loop over every LED gpio.num_leds() reports, with no LED stuck on or skipped (Dev Kit: if you cannot see LED1/LED2 on the module, watch mainly the three RGB LEDs, and note how many you can see)
  • Edit STEP_MS and rerun — the tempo really changes, for at least two values
  • Press the user button (gpio.button(0)) ten times — the number on screen shows exactly ten. On the Dev Kit, never flip any switch on the base, since several of them are power-cutoff switches
  • Explain to the instructor or a teammate what happens, and why, if the debounce code is removed
  • When the program ends, every LED is off, with a green summary line on screen
  • Attach a photo or a short clip to your learning log
  • (Eva Kit) Run it again with the Controls card open instead of Playground, and watch the circle on screen turn on and off following the chase, even though the code never commands the screen at all

Reaching the broker (following on from the MVP)

  • The my_first_reader.html page shows “connected (bento-aiot/)”, and within 2 seconds of running 07 you see the presses, btn, leds boxes
  • Press the button on the board — the “last event” field changes immediately
  • Press “turn on LED 0” on the web page, and leds in the next message changes to match (on the Dev Kit, LED 0 is on the module and may not be visible, but leds still changes visibly)
  • If it cannot connect, switch both sides to the backup broker test.mosquitto.org (board: 1883, web: wss://test.mosquitto.org:8081/mqtt), and note which side worked

Going further

Section titled “Going further”

Team homework: pick one extension from the slides (a button that cycles speed through 400/200/100 ms · a back-and-forth pattern built from gpio.num_leds() · telling a short press apart from a long press at 800 ms · trying DEBOUNCE_MS at 0, 5, 40, 200 and making a table) or build an application that publishes a value your team chooses as telemetry and edits my_first_reader.html to respond to it. Lesson 2.4 moves from one real button to a button you build yourself on the touch screen.

Next lesson: Lesson 2.4 — The touch screen and your first widgets

Reflect

Section titled “Reflect”
  • While filling in the blanks, which time did filling them in group by group help you find a break faster? If you filled all six in and ran it only once, where would you start looking?
  • If you changed from “read the button” to “read acceleration from the IMU”, how many lines of this loop would need to change, and where is debouncing similar to filtering a sensor signal?
  • On a public broker, anyone can publish to any team’s topic. What data of your team’s should never end up there?

Review questions

Answer on your own first, then open the answer.

  1. A team fills only blanks 1-2 in the practice file and presses Program to Device. What will they see? (Objective 1)

    1. ไฟวิ่งครบทุกดวง แต่กดปุ่มแล้วตัวนับไม่ขยับ เพราะ raw ยังเป็น False ที่ตั้งไว้ให้ไฟล์รันได้
    2. โปรแกรมหยุดทันทีด้วย NameError เพราะยังไม่มีบรรทัด raw = btn.is_pressed()
    3. ไฟไม่วิ่ง เพราะลูปต้องรอให้กดปุ่มก่อนจึงจะขยับไฟ
    4. ไฟวิ่งและนับปุ่มได้ แต่นับเกินจริง เพราะยังไม่ได้เติมส่วนกันเด้ง
    Show answer

    Answer: A. ไฟวิ่งครบทุกดวง แต่กดปุ่มแล้วตัวนับไม่ขยับ เพราะ raw ยังเป็น False ที่ตั้งไว้ให้ไฟล์รันได้

    ไฟวิ่งเป็นงานที่ไม่พึ่งอินพุตจากใคร จึงทำงานได้ทันทีหลังจุด 1–2 ส่วน raw ถูกตั้งเป็น False ไว้ก่อน ไฟล์จึงไม่พัง แต่ปุ่มยังไม่ถูกอ่าน การเติมทีละกลุ่มแบบนี้ทำให้รู้ว่าถ้าปุ่มพังตอนหลัง ปัญหาไม่ได้อยู่ที่ไฟ

  2. Which symptom-cause pairs are correct? Choose all that apply. (Objective 2)

    1. กดหนึ่งครั้ง เลขขึ้น 3–5 ← ยังไม่ได้กันเด้ง หรือ DEBOUNCE_MS น้อยเกิน
    2. กดแล้วเลขไม่ขึ้นเลย ← มี sleep_ms ยาวในลูป ปุ่มหลุดตอนหลับ
    3. ไฟติดพร้อมกันสองดวง ← จุดดวงใหม่ก่อนดับดวงเดิม
    4. จอไม่ขึ้นตัวเลขแต่ไฟวิ่งปกติ ← DEBOUNCE_MS สูงเกินไป
    5. ไฟไม่วิ่ง ค้างดวงเดียว ← ลืม if stable
    Show answer

    Answer: A. กดหนึ่งครั้ง เลขขึ้น 3–5 ← ยังไม่ได้กันเด้ง หรือ DEBOUNCE_MS น้อยเกิน · B. กดแล้วเลขไม่ขึ้นเลย ← มี sleep_ms ยาวในลูป ปุ่มหลุดตอนหลับ · C. ไฟติดพร้อมกันสองดวง ← จุดดวงใหม่ก่อนดับดวงเดิม

    สามข้อแรกตรงกับตารางกับดัก ส่วนจอไม่ขึ้นตัวเลขทั้งที่ไฟวิ่งเกิดจากไม่ได้เปิดหน้า Playground ไว้ และไฟค้างดวงเดียวเกิดจาก last_step = now อยู่นอก if ส่วนการลืม if stable ทำให้เลขขึ้นทีละสอง

  3. Why does 07_button_to_broker.py resend telemetry every 2 seconds even when nothing has changed? (Objective 3)

    1. เพราะ publish() ของเฟิร์มแวร์นี้ส่ง retain = false เสมอ broker ไม่เก็บใบล่าสุดไว้ หน้าเว็บที่เปิดทีหลังจึงต้องรอใบถัดไป
    2. เพราะ broker สาธารณะตัดการเชื่อมต่อถ้าไม่มีข้อมูลเข้าภายใน 2 วินาที
    3. เพราะกล่องรับของบอร์ดมีช่องเดียว ต้องส่งออกก่อนจึงจะรับได้
    4. เพราะ event อาจส่งซ้ำ จึงต้องมี telemetry ไว้ลบใบที่ซ้ำ
    Show answer

    Answer: A. เพราะ publish() ของเฟิร์มแวร์นี้ส่ง retain = false เสมอ broker ไม่เก็บใบล่าสุดไว้ หน้าเว็บที่เปิดทีหลังจึงต้องรอใบถัดไป

    publish() ส่ง retain = false เสมอแม้ docstring จะเขียนว่ารับ retain= ถ้าส่งเฉพาะตอนเปลี่ยน หน้าเว็บที่เปิดทีหลังจะจอว่าง การส่งซ้ำทุก 2 วินาทีทำให้หน้าเว็บที่เปิดช้าที่สุดก็ตามทันภายใน 2 วินาที

  4. Which statements about how 07_button_to_broker.py works around the firmware's limits are true? Choose all that apply. (Objective 3)

    1. ต้องกันเด้งก่อน publish ไม่งั้นกดหนึ่งครั้งกลายเป็นหลายใบบน broker และคนที่อ่านอีกฝั่งแยกไม่ออกว่าใบไหนคือการกดจริง
    2. ส่งสถานะไฟจากตัวแปร leds ที่ handle() จดไว้ ไม่ใช่จาก gpio.led(i).value()
    3. หยิบ get_message() ทุกรอบลูป เพราะกล่องรับมีช่องเดียว ใบใหม่ทับใบเก่า
    4. สองคนในทีมรันไฟล์ 07 ด้วย TEAM เดียวกันบนสองบอร์ดพร้อมกันได้ เพราะ broker แยกให้เอง
    5. ถ้าสายหลุด publish() คืน False ให้เองอยู่แล้ว ไม่ต้องดักอะไร
    Show answer

    Answer: A. ต้องกันเด้งก่อน publish ไม่งั้นกดหนึ่งครั้งกลายเป็นหลายใบบน broker และคนที่อ่านอีกฝั่งแยกไม่ออกว่าใบไหนคือการกดจริง · B. ส่งสถานะไฟจากตัวแปร leds ที่ handle() จดไว้ ไม่ใช่จาก gpio.led(i).value() · C. หยิบ get_message() ทุกรอบลูป เพราะกล่องรับมีช่องเดียว ใบใหม่ทับใบเก่า

    client_id ซ้ำกันไม่ได้ ใครต่อทีหลังจะเตะคนก่อนหลุด ไฟล์ 07 ใช้ bento-aiot- ต่อด้วยชื่อทีม จึงรันได้บอร์ดเดียวต่อทีม และ publish() ตอนสายหลุดโยน OSError ไม่ได้คืน False จึงต้องให้ send() ดักไว้

  5. Which statements about timing in the class reaction game (08_class_race.py) are true? Choose all that apply. (Objective 4)

    1. ทีมที่ผลขึ้นจอหน้าห้องก่อนอาจไม่ใช่ทีมที่เร็วที่สุด เพราะแต่ละบอร์ดสุ่มเวลารอเอง และข้อความเดินทางใช้เวลาไม่เท่ากัน
    2. บอร์ดจดเวลาตอนขาเริ่มเปลี่ยน แล้วค่อยใช้เวลานั้นเมื่อกันเด้งยืนยันว่าเป็นการกดจริง
    3. ถ้าจับเวลาตอนที่กันเด้งยืนยัน ทุกทีมจะได้เวลาเร็วกว่าจริง 40 ms
    4. กดเร็วกว่า 100 ms หลังไฟติดถือเป็นสถิติที่ดีที่สุดของรอบ
    Show answer

    Answer: A. ทีมที่ผลขึ้นจอหน้าห้องก่อนอาจไม่ใช่ทีมที่เร็วที่สุด เพราะแต่ละบอร์ดสุ่มเวลารอเอง และข้อความเดินทางใช้เวลาไม่เท่ากัน · B. บอร์ดจดเวลาตอนขาเริ่มเปลี่ยน แล้วค่อยใช้เวลานั้นเมื่อกันเด้งยืนยันว่าเป็นการกดจริง

    เราวัดบนบอร์ดระหว่างหลอดของมันเองกับปุ่มของมันเอง ทางเดินของข้อความจึงไม่อยู่ในตัวเลข กันเด้ง 40 ms ทำให้บอร์ดเชื่อช้ากว่านิ้ว ถ้าจับเวลาตอนเชื่อทุกทีมจะช้าเกินจริง และเร็วกว่า 100 ms นับเป็นออกตัวก่อน

Cite this lesson

If you teach from this lesson or reuse it in slides or documents, credit it with the text below. If you changed it, add (adapted) after the title.

"Hands-on: running lights, a button, and the broker" from TESA Open Knowledge by the Thai Embedded Systems Association (TESA), https://github.com/tesaiot/tesa-qualification-program, licensed under CC BY-NC 4.0

Thai attribution: "ลงมือทำ: ไฟวิ่งกับปุ่ม แล้วส่งขึ้น broker" จาก TESA Open Knowledge โดยสมาคมสมองกลฝังตัวไทย (Thai Embedded Systems Association: TESA) https://github.com/tesaiot/tesa-qualification-program สัญญาอนุญาต CC BY-NC 4.0

Lesson link: https://tesaiot.github.io/tesa-qualification-program/en/courses/aiot-micropython/m02-ui-to-hardware/l03-led-button-lab/

This lesson adapts the source below; keep its credit too.
https://github.com/Advance-Innovation-Centre-AIC/embedded-systems-for-aiot-developer/blob/a80bbe88a34bcb9bb8d991f42f9252b77cdab079/session-03.html (slides 28–52)

Full guide: how to cite TESA

TESA Open Knowledge · © 2026 สมาคมสมองกลฝังตัวไทย (TESA) · CC BY-NC 4.0

Content is licensed CC BY-NC 4.0. Reuse it non-commercially and credit the Thai Embedded Systems Association (TESA) every time. · How to cite TESA