Summary
Add a safe, persistent operating-mode system opened by pressing and continuously holding the touchscreen for five seconds. The menu must offer the existing timer, a new graphical live G meter, and device settings.
This issue brings together and implements the relevant parts of #31 (brightness), #44 (restore defaults), and #48 (live/peak acceleration) within one coherent on-device mode interface. It belongs under roadmap epic #23.
Entry gesture and safety
- Detect a continuous five-second physical touch, measured from the CST816S touch-count state; do not treat the controller's generic long-press gesture as proof of a five-second hold.
- Reset progress immediately when the finger is released before five seconds.
- Make the threshold a named system configuration value, defaulting to
5 seconds. - Allow entry from the Timer Ready screen and from G Mode.
- Do not enter configuration during an active track/rest session or while waiting for Launch Mode; this prevents accidental interruption of timing.
- Clear any pending swipe/gesture when the hold completes so the same touch cannot operate the menu.
- Show a concise Ready/G-screen hint explaining how to open the mode menu.
Operating-mode menu
Display a round-screen-safe menu with three choices:
- Timer Mode — existing track/rest/Launch Mode functionality.
- G Mode — new graphical live accelerometer view.
- Settings — brightness and restore-default controls.
Interaction:
- Swipe left/right to move between choices.
- Swipe up to select.
- Swipe down to cancel and return to the previously active operating mode.
- Selecting Timer Mode or G Mode persists the choice in
user.json and immediately enters that mode. - Settings is an action/menu, not a persistent operating mode. Leaving Settings returns to the mode menu; cancelling the menu returns to the previously selected operating mode.
- The saved default operating mode is Timer Mode. Existing
user.json files must migrate automatically.
G Mode visual design
G Mode must be graphical rather than a numeric telemetry page.
- Use a circular G-meter illustration drawn in the native framebuffer:
- central crosshair and concentric reference rings;
- a filled live marker showing the current filtered acceleration vector;
- a contrasting hollow/ghost marker showing the maximum vector reached since entry/reset;
- a short fading trail so motion direction and intensity are visually understandable;
- a perimeter peak arc or equivalent graphical cue showing maximum magnitude relative to the supported display scale.
- Calibrate a stationary baseline on entry and subtract it so gravity and mounting orientation do not dominate the live display.
- Low-pass filter live X/Y acceleration to reduce jitter.
- Clamp drawing to the circular display and the configured visual scale (the QMI8658 is currently configured for ±8 g).
- Preserve the peak marker until reset. Double-tap resets the peak/trail without leaving G Mode.
- A five-second hold opens the operating-mode menu.
- Target a bounded refresh rate around 10 Hz so touch polling remains responsive and unnecessary LCD transfers are avoided.
- If the QMI8658 is unavailable or fails during sampling, show an actionable message and return safely to the mode menu/Timer Mode; Timer Mode must remain usable.
Settings
Brightness
- Offer clear percentage choices: 25%, 50%, 75%, and 100%.
- Preview brightness immediately while editing.
- Swipe up saves the selection to
user.json; swipe down cancels and restores the previous level. - Apply saved brightness during startup before normal operating screens.
Restore defaults
- Require a confirmation screen before changing data.
- Restore all user-owned settings to built-in defaults: Timer Mode, 100% brightness, track/rest durations, and Launch sensitivity.
- Persist the complete canonical default dictionary atomically.
- Return to Timer Mode after confirmation.
- Cancelling must leave all settings unchanged.
Configuration and compatibility
- Add
MODE_MENU_HOLD_SEC (default 5) to system configuration in params.json. - Add canonical
OPERATING_MODE and BRIGHTNESS_PERCENT keys to user.json/built-in defaults. - Validate supported modes and brightness values, migrate existing files, and preserve safe atomic write/recovery behavior.
- Avoid allocating optional mode/G-meter modules before the RP2040's 115,200-byte LCD framebuffer.
User interface and exit behavior
- Every selection/edit screen must include visible gesture prompts.
- Text and graphics must fit within the 240×240 round display and use high-contrast colours.
- Timer Mode returns to its existing Ready screen.
- G Mode remains active until a five-second hold opens the menu.
- Settings always provides Back/cancel routes and ultimately returns to the selected operating mode.
Acceptance criteria
- A continuous touch enters the mode menu at five seconds; a release at any earlier point does not.
- The menu cannot interrupt a running track/rest/launch session.
- Timer Mode preserves all existing behavior.
- G Mode displays live and maximum acceleration graphically, including a live marker and distinguishable peak marker, without relying on current/max numeric readouts.
- Double-tap clears G Mode peak history.
- Mode and brightness persist across restart.
- Brightness preview/save/cancel behavior works at all supported levels.
- Restore defaults requires confirmation and restores the complete canonical default set.
- Missing IMU operation degrades safely without blocking Timer Mode.
- Existing user/system configuration files migrate safely.
- Host tests cover hold timing/reset, menu navigation/cancel, settings persistence/default reset, G-vector filtering/peak/reset/clamping, display bounds, and IMU failure behavior.
- The full host suite passes and the mode menu/G meter are exercised on the supported Waveshare RP2040-Touch-LCD-1.28.
Documentation
Update the README, User Guide, installation file list, configuration-key documentation, operating-mode gestures, G-meter legend, brightness behavior, default reset warning, and degraded-IMU behavior.
Summary
Add a safe, persistent operating-mode system opened by pressing and continuously holding the touchscreen for five seconds. The menu must offer the existing timer, a new graphical live G meter, and device settings.
This issue brings together and implements the relevant parts of #31 (brightness), #44 (restore defaults), and #48 (live/peak acceleration) within one coherent on-device mode interface. It belongs under roadmap epic #23.
Entry gesture and safety
5seconds.Operating-mode menu
Display a round-screen-safe menu with three choices:
Interaction:
user.jsonand immediately enters that mode.user.jsonfiles must migrate automatically.G Mode visual design
G Mode must be graphical rather than a numeric telemetry page.
Settings
Brightness
user.json; swipe down cancels and restores the previous level.Restore defaults
Configuration and compatibility
MODE_MENU_HOLD_SEC(default5) to system configuration inparams.json.OPERATING_MODEandBRIGHTNESS_PERCENTkeys touser.json/built-in defaults.User interface and exit behavior
Acceptance criteria
Documentation
Update the README, User Guide, installation file list, configuration-key documentation, operating-mode gestures, G-meter legend, brightness behavior, default reset warning, and degraded-IMU behavior.