roro9stack/docs/milestones/M0.md

M0 — Skeleton: Launcher, Status Bar, Settings, battery

Status: done on 2026-10-02, tagged v0.1.0.

Outcome

Every "Done when" item below works on the device, apart from the gaps listed here. Changes made along the way:

• Not done, carried over:
  • Charging indicator: the battery voltage alone can't tell charging apart reliably. Revisit if the hardware exposes a charger status.
  • Waking from power-off with a keyboard key: G0 only for now.
  • Status Bar placeholders for GNSS, mesh, Wi-Fi and unread count are left out until those Services exist (M1, M2, M4).
• Added:
  • SD card erase, in Settings → Storage.
  • A Notification wakes an Off screen (dimmed) while its Toast shows.
  • Navigation arrows without Fn outside Text Entry.
  • Serial dev commands and scripts/serial_log.sh.
• Measured on the device:
  • About 225 KB free heap with the 64 KB frame buffer.
  • About 15 ms per frame.
  • 19% of the app flash used.

Goal: a firmware you can flash and hold. It boots to a Launcher, shows a live Status Bar, navigates with the keyboard and saves Settings. It proves the App/Service architecture that every later milestone plugs into.

Done when

• Building, testing and flashing each work with one command, run inside a local Docker container (no toolchain on the host).
• First boot runs the setup wizard (names, Region, timezone), and later boots skip it.
• The Launcher lists Apps. Enter starts one, ` goes back, and Fn+` returns home from anywhere.
• The Status Bar shows battery %, a charging indicator and the clock (relative until set), with placeholders for GNSS, mesh, Wi-Fi and unread count.
• The Settings App edits and persists: long and short name, Region, timezone, brightness, dim and off timeouts, sound on/off, and probe-request MAC handling (raw by default).
• An About screen shows the version, free heap, battery voltage, SD status and usage, and uptime.
• The screen dims at 30 s and turns off at 60 s. Any key wakes it without the key also acting on the App.
• A long press of G0 powers off (deep sleep). G0 or a key wakes the device.
• The Compose Key types accented characters in the line editor (opt ' e → é).
• Toast Notifications work. A demo App can raise one, with a beep and LED flash.
• SD usage is watched: a Storage Warning appears once per boot above 80%. The Log-write cutoff flag is set at 90%, with no Log writers yet.

Out of scope for M0

Storage Clean-up screen (M1, once IRC Logs exist), any radio, GNSS, Wi-Fi.

Work breakdown

1. Project scaffold
   • PlatformIO project with the pioarduino platform (Arduino-ESP32 3.x on ESP-IDF 5.x). Board m5stack-stamps3, 8 MB partitions, USB-CDC on boot.
   • Dependencies: M5Cardputer (pulls in M5Unified and M5GFX).
   • LICENSE (GPL-3.0), README.md with build and flash steps, a version string injected from git at build time (semver tags).
   • A native environment for host-side unit tests (Unity).
   • Local CI in a Docker image with PlatformIO. One script builds the firmware and runs the native tests, and the same container flashes over USB. The repo is hosted on self-hosted Gitea, and a Gitea Actions workflow can reuse this image later.
2. Hardware bring-up checks (manual, on the device)
   • Display, keyboard (TCA8418) and speaker through M5Cardputer.
   • Confirm there's no PSRAM, and record the heap at boot.
   • Investigate the G38 backlight/LED power-rail coupling, then decide how dimming works without killing the LED.
   • Battery ADC on G10 (×2 divider): calibrate the voltage-to-% curve.
   • SD card mount on the shared SPI bus (CS=12), behind a bus lock ready for the LoRa radio in M3.
3. Core runtime
   • Event bus: Services publish events (battery changed, notification, storage threshold), and the UI consumes them on the UI task.
   • Service interface: start, stop, periodic tick, state snapshot for the Status Bar.
   • App interface: enter, exit, key event, draw. Plus a registry, so adding an App means one file and one registration line.
   • App lifecycle: one foreground App; Home and Back handling.
4. Services for M0
   • Settings store: typed keys in NVS (internal flash), with defaults and change events.
   • Battery Service: sampled voltage, smoothed %, charging detection if the hardware allows it.
   • Clock Service: no time source yet. API for "set from source X", plus relative-time formatting and Europe/Brussels conversion.
   • Storage Service: SD present/absent, usage %, 80% and 90% thresholds raising events, Log-write permission flag.
   • Power Service: dim and off timers, wake-key swallowing, G0 long-press → deep sleep.
5. Widget kit (ADR 0002): an off-screen buffer pushed to the display.
   • Status Bar, list, text view, line editor (with the Compose Key), dialog and Toast.
   • A Latin-1 font set.
6. Input layer
   • Map key events to logical keys: arrows (Fn + ; . , /), Back, Home, Select.
   • Compose Key dead-key state machine. This is pure logic, unit-tested on the host.
7. Apps: Launcher, Settings (including About), first-boot wizard, and a hidden Demo App for exercising Toasts and widgets.
8. Docs: a short walkthrough for a first-time setup: install PlatformIO, USB permissions on Linux, flash, recover via download mode.

Host-tested logic (TDD candidates)

• Compose Key state machine
• Battery voltage → % curve and smoothing
• Storage threshold and once-per-boot warning logic
• Relative-time formatting and timezone conversion
• Settings defaults and validation (e.g. Region must be confirmed before any transmit flag)

Risks to resolve early

• G38 shared rail: if the backlight and LED really share power, "screen off" may also need to turn the LED off.
• RAM headroom: the off-screen buffer is 240×135×2 ≈ 64 KB at 16-bit, or about 32 KB at 8-bit. Measure the free heap now, because Wi-Fi + TLS (M1) is the tightest point.
• Keyboard library maturity for the ADV's TCA8418 in M5Cardputer. Fall back to Adafruit_TCA8418 directly if needed.