Blink an LED Code Tracer¶
Specification¶
The full specification below is extracted from Chapter 4: Digital I/O, PWM, and the MicroPython Workflow.
Type: microsim
**sim-id:** blink-led-code-tracer<br/>
**Library:** p5.js<br/>
**Template:** https://github.com/dmccreary/learning-micropython/tree/main/docs/sims/pico-pinout-explorer<br/>
**Status:** Specified
Learning objective: Students will *apply* (Bloom L3: Apply) knowledge of MicroPython syntax to trace the blink-an-LED program line by line and predict the resulting GPIO pin state and LED behavior at each step.
Canvas: 700x440px, responsive — recompute the two-panel split (code panel and circuit panel) from `windowWidth` inside `windowResized()`, stacking vertically below 550px.
Data Visibility Requirements:
Stage 1: Show the full blink-an-LED code listing in the left panel with line numbers, and a simplified Pico-plus-LED circuit diagram in the right panel with pin 15 labeled.
Stage 2: As the student steps forward, highlight the currently executing line in the code panel and simultaneously update the right panel showing the LED as lit (yellow glow) or unlit, plus a text readout "Pin 15: HIGH" or "Pin 15: LOW."
Stage 3: Show an elapsed-time counter that increments only when a `sleep()` line executes, so students connect the `sleep(0.5)` argument to actual visible pause duration.
Controls: a `createButton()` labeled "Step Forward" advancing execution by one line (looping back to the `while True:` line after the last one); a `createButton()` labeled "Run Continuously" that auto-steps on a timer matching the real `sleep()` durations; a `createButton()` labeled "Reset."
Interaction: stepping onto a `led.value(1)` or `led.value(0)` line immediately updates the LED's lit state and the pin-state readout in the right panel. Stepping onto a `sleep()` line animates the elapsed-time counter counting up to that line's argument value before allowing the next step. Hovering any line of code shows a one-sentence tooltip explaining that line, matching the plain-language explanation given in the surrounding chapter text.
Instructional Rationale: A step-through code tracer with explicit pin-state and timing visibility is appropriate for this Apply-level objective because it lets students connect each line of MicroPython syntax directly to an observable hardware effect, rather than treating the program as a black box that "just blinks."
Implementation: p5.js. Represent the program as an ordered array of line objects with a `type` field (`assign`, `pinwrite`, `sleep`, `loop`) driving what the step handler does; maintain a `currentLine` index and an `elapsedMs` counter in the sketch's state. Use `createButton()` for all three controls per project convention, and redraw both panels every frame from state rather than mutating previously drawn pixels.