Design lab

Set up the project

Same circuit as Week 4, LED on GPIO17 (physical 11), button on GPIO27 (physical 13), wired with outputs off and traced aloud (the diagram). On the Pi, over SSH:

$ mkdir -p ~/iot/week5/docs && cd ~/iot/week5
$ python3 -m venv --system-site-packages .venv && source .venv/bin/activate
$ nano .gitignore        # .venv/ __pycache__/ *.pyc, as in Week 4

Then the week's characteristic move: the documents go in first. Put the requirements table in docs/requirements.md (Markdown tables from Week 1: pipes and dashes) and the pseudocode in docs/design.md, and commit them before any Python exists. The commit history should read like the method: spec, design, code, verification.

Translate: pseudocode to Python

With the construct map open, the translation is close to mechanical. reaction.py:

from gpiozero import LED, Button
from time import monotonic, sleep
from random import uniform

led = LED(17)
button = Button(27, bounce_time=0.05)

while True:                                   # R6
    led.off()                                 # R1
    print("Get ready...")                     # R1
    delay = uniform(2.0, 5.0)                 # R2
    waited = 0.0
    false_start = False
    while waited < delay:                     # the watchful wait
        if button.is_pressed:
            false_start = True
            break                             # EXIT WHILE
        sleep(0.01)
        waited = waited + 0.01
    if false_start:                           # R4
        print("FALSE START")
        button.wait_for_release()
        continue                              # next round
    led.on()                                  # R2 completed
    t0 = monotonic()
    button.wait_for_press()                   # R3
    reaction = (monotonic() - t0) * 1000
    led.off()
    print(f"Reaction: {reaction:.0f} ms")     # R3
    button.wait_for_release()

The new pieces, each earned by a design decision:

• uniform(2.0, 5.0), from the standard library's random module: a random float in the range, R2's literal translation. (Its sibling randint gives whole numbers; the docs page is worth ten minutes.)
• break and continue: Python's spellings of EXIT WHILE and "continue to next round". break leaves the innermost loop; continue jumps to that loop's next lap. Both are covered in the tutorial's control-flow chapter, this week's core language reading.
• button.wait_for_press() / wait_for_release(): gpiozero's blocking waits, the exact WAIT UNTIL of the design, documented with the rest of Button's API. Blocking (the program stands still) is precisely right here and precisely wrong in the watchful wait, which is why the design polls there instead: the wait must watch two things at once.

Background: measuring time honestly

And how accurate is the measurement, for R5? Budget the error like the instrumentation problem it is: the debounce window (50 ms) can delay press recognition; the OS may schedule the process a few ms late; the polling in the watchful wait quantizes only the delay, not the measurement. Total plausible error: a few tens of ms, so R5's 100 ms is honest, and "to the microsecond" never was. Software timing is a measurement chain, and you already know how to think about those.

Verify against the spec

Run the acceptance criterion for every row of the spec, both partners, and record the result in docs/requirements.md as a fourth column. This table is the week's real deliverable:

The design ladder

Now the roles flip: the spec is yours to write. For each rung, the cycle is fixed and the artifacts are committed at every step: requirements (3 to 5, with IDs and acceptance criteria) → pseudocode or flowchart → trace one path → Python → verification table. The navigator writes the spec, the driver codes it, and you swap each rung; a rung is done when its table says so, not when it "seems to work".

1. Patience light

   The LED lights only after the button has been held for a full 2 s; releasing early cancels. Spec question your requirements must answer: what happens during the hold? (Timing + one decision.)

2. Door chime

   Each press triggers exactly one double-flash (short-short), then the system is ready again. Spec question: what does a press during the flash do? Your R-line decides; your code obeys. (Events + edge case.)

3. Two-mode night light

   A press toggles between mode NORMAL (LED off, presses ignored for 1 s after switching) and mode NIGHT (LED on). Write the state diagram first; implement state as a variable. (Your first named state machine.)

4. Lockout

   Extend the reaction timer: three false starts in one session triggers LOCKED for 10 s, LED flashing, presses ignored, then normal play resumes. Spec, diagram, trace the third false start, build. (Counters + states + everything.)

5. Stretch: best of five

   The timer plays exactly five valid rounds, then reports the best and average times and exits cleanly. Needs a list or running totals; the control-flow chapter has what the design will ask for.

Checklist for this stage

• docs/requirements.md and docs/design.md committed before reaction.py existed
• reaction.py runs; false starts and valid rounds both behave per spec
• The verification table is filled in, R5's row honestly
• At least two ladder rungs completed with the full cycle, roles swapped between them
• Every artifact pushed; the log reads spec → design → code → verify

Check yourself