Roadmap and Risks
Build Order
The Study Buddy has its own lab numbers, starting at 01. The code is in
src/kits/study-buddy. Each lab ends with something that works on its
own, so the kit is useful after any of them.
"The template" below means the five-mode program from the smartwatch kit's Lab 12. It is copied into the Study Buddy folder in Lab 04, when the first mode needs it.
| Lab | Status | Builds | Needs | Result |
|---|---|---|---|---|
| 01: Blink the Onboard LED | Done | 01-blink-onboard-led.py |
The Pico | The board and firmware work. |
| 02: Kit Checkup (Probe) | Done | 02-probe.py: the watch kit's checkup plus a speaker section (pin rule, gain pin, three beeps). |
Lab 01 | A report on the board, files, WiFi, buttons, SPI, speaker, and display. |
| 03: Speaker Test | Next | sound.py with tones, named sounds, and non-blocking playback. Gives the timer a real alarm. |
The amplifier and speaker | Beeps and melodies without freezing the screen. |
| 04: Study Timer | mode_study.py: focus and break phases, with chimes and a daily minutes ring. Copies in the template and mode_timer.py. |
Lab 03 | A Pomodoro timer. The first useful study feature, and almost free. | |
| 05: Quote of the Day | mode_quote.py, packs.py, and the circle-aware word-wrap. |
Lab 04 | Quotes that fit the round screen. | |
| 06: Flash Quiz | mode_quiz.py and mode_mathfacts.py, with the choice builder, the three-box memory, and progress.json. |
Labs 03 and 05 | A working drill, with generated math facts. | |
| 07: A Deck of Your Own | The pairs deck format, and a CSV-to-deck script. Students make a US Capitals deck and one of their own. | Lab 06 | Students author content. | |
| 08: Next Quiz | mode_reminder.py, reminders.py, and the wall-clock check in the main loop. |
Labs 03 and 04 | Chimes for a quiz that is days away. | |
| 09: The Library | mode_library.py with Browse and Installed tabs, free-space display, remove, and pinning. The manifest, hashing, modes.json replacing the MODES tuple, and the teacher's tools/make_manifest.py. |
Labs 04 and 06 | Students and teachers can add and remove modes and decks without a computer. | |
| 10: Add Events From Your Phone | A small web server on the Pico and a form. Later, the calendar feed. | Lab 08 | No computer needed to add a quiz. |
Lab 03 and Lab 04 come first. Between them they prove the audio rules and the study-mode button conventions, and everything else builds on those.
What the first kit run showed
Labs 01 and 02 were run on a real Pico 2 W with the Study Buddy wiring on 2026-10-04:
| Check | Result |
|---|---|
| Board | Pico 2 W (RP2350), MicroPython 1.29.0, 150 MHz |
| Heap free after the probe loaded | 419 KB |
| Flash | 4 MB chip, 2.5 MB filesystem, 2.4 MB free with the kit's files on it |
| I2S pin rule | LRC on GP21 is one more than BCLK on GP20, so I2S() accepts it |
| I2S timing | 0.76 s of audio accepted in 0.63 s, which is what the 16 kHz clock should give |
| Sound | Heard (three rising beeps) |
| Display | Four color bars shown, full fill 130 ms, same as the watch kit |
| WiFi | The home network is visible but weak, about -72 dBm, and a single scan sometimes misses it, so the probe rescans twice before it warns |
Changes still to make to the copied files
The Study Buddy folder started as a copy of the watch kit's shared files.
Already done: config.py has the I2S pins, the gain pin, GAIN_DB,
VOLUME, and set_gain(), and 02-probe.py has the speaker section.
| File | Change |
|---|---|
12-main-template.py (copied in Lab 04) |
Read modes.json. Pin up to 8 modes. Import sound and reminders before the module snapshot. Add the wall-clock reminder check. Wait for a mode's busy flag before switching for a reminder. |
config.py |
Add QUIET_START_HOUR and QUIET_END_HOUR, and the LIBRARIES list (each with a name, a url, and a modes flag). |
mode_timer.py (copied in Lab 04) |
Use sound.play("done") instead of the optional piezo buzzer. |
upload-code.sh |
Copy the new modules and create the packs/, user/, and audio/ folders. |
secrets-template.py |
Add CALENDAR_URL for the calendar feed. |
Risks
| Risk | Why it matters | What to do |
|---|---|---|
| Downloaded modes are unsandboxed code | A bad mode could read the WiFi password or break the device. | Teacher-controlled HTTPS address only, hash check, confirm screen, and a modes.json fallback so a broken mode cannot stop the watch from starting. Packs carry no code. |
| Audio dropouts during drawing | The display blocks the Pico for up to 232 ms. | 16 KB ring buffer, no full fills while playing, and measure early in Lab 03. |
| Tick counter wraps | A reminder days away cannot use ticks_ms(). |
Use the wall clock for reminders. |
| The RTC resets on power loss | A device with no battery loses the time. | It resyncs over WiFi at power-up. With no WiFi, reminders stay quiet and the screen says "Clock not set". |
| Flash wear | Flash typically survives about 100,000 erases per block. | Write progress at the end of a round, not each question. |
| Flash space for audio | The 2.5 MB filesystem holds about 1.5 minutes of speech. | 11 kHz clips first, then a 16 MB board or an SD card. |
| A private calendar address leaks | It gives read access to a student's calendar. | Keep it in secrets.py and never print or display it. |
| Wrong attributions on quotes | Students learn a false fact. | A required source note on every shipped quote. |
| Students' schedules and scores | Quiz dates and results are about a child. | Everything stays on the device. Nothing is sent anywhere except the calendar fetch the student sets up. |
| Students install code themselves | Students use the Library, so they can add a mode that has a bug and hangs the device. | Students only see what the teacher published, a mode can never stop the device from starting (modes.json falls back to the built-in modes), and the Installed tab lets a student remove a mode without a computer. Mode installs also need a confirm screen. |
| A student runs out of flash | Many decks and modes, plus audio, fill the filesystem. | The Installed tab shows free space, the Library refuses an install that would leave under 200 KB free, and it says so in plain words. |
| TLS to the Library host | Some hosts are hard for a small board to reach over HTTPS. | Test GitHub Pages on a real Pico in Lab 09. Fall back to a school server. |
Open Questions
- Where will the class Library live? The book's GitHub Pages site is the simplest home, but only if the Pico's TLS works with it.
- How do student-made decks reach other students? In version 1 a
student hands the deck to the teacher, who reviews it and adds it to the
class Library. A second, decks-only "Friends" library that students
can post to directly (
"modes": false) would be faster, but it needs a place to post and someone to watch it. - Is flash enough, or do we want a 16 MB board in the kit? This depends on how much recorded speech we want. Level 1 and level 2 fit on the current board.
- Is a fourth button worth it? A dedicated SELECT button would remove the "MODE confirms inside a quiz" rule. It would also make the Study Buddy different from the smartwatch wiring.
- Should reminders speak, or chime and show text? Level 1 is the cheapest, and level 2 needs recording a vocabulary.
- Do younger students get decks only? The
modessetting on each library can hide code downloads. Is that the default for the youngest classes, with the teacher installing modes ahead of time?
Decisions
| Decision | Date |
|---|---|
| The speaker is on GP18 to GP21, not GP10 to GP12 as first drafted: LRC on GP21, BCLK on GP20, DIN on GP19, and the amplifier's GAIN pin on GP18, so software can pick 6, 9, or 12 dB. The I2S pin rule (LRC is BCLK plus one) holds. This leaves GP8 to GP12 free for a micro-SD card on hardware SPI1. | 2026-10-04 |
| The Study Buddy has its own lab numbers: 01 is Blink the Onboard LED and 02 is the Probe. The speaker test and everything after move to 03 and up. | 2026-10-04 |
The code goes in a new folder, src/kits/study-buddy, not in src/kits/sw-gc9b72. Like the other kits it is self-contained, so it holds its own copy of lib/, config.py, and wifi_time.py. If the copies drift apart, a shared lib is a later cleanup. |
2026-10-03 |
| Both students and instructors use the Library. The Library screens are written for a student to use alone, and the teacher gets a manifest script and a curation workflow. See the Library. | 2026-10-03 |