diff --git a/backlog/milestones/m-2 - phase-0-prototype.md b/backlog/milestones/m-2 - phase-0-prototype.md new file mode 100644 index 0000000..3ddc0d4 --- /dev/null +++ b/backlog/milestones/m-2 - phase-0-prototype.md @@ -0,0 +1,8 @@ +--- +id: m-2 +title: "Phase 0 Prototype" +--- + +## Description + +Initial working prototype: Pico firmware, PWA with CV pipeline, demo guide, slide deck, and first user tests diff --git a/backlog/tasks/task-126 - Repo-structure-setup.md b/backlog/tasks/task-126 - Repo-structure-setup.md new file mode 100644 index 0000000..1e074b2 --- /dev/null +++ b/backlog/tasks/task-126 - Repo-structure-setup.md @@ -0,0 +1,32 @@ +--- +id: TASK-126 +title: Repo structure setup +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - setup + - repo +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Create directory structure (docs/, firmware/, app/js/, app/css/, app/guides/), move existing spec docs to docs/, write README.md + + +## Acceptance Criteria + +- [ ] #1 Directory structure matches plan +- [ ] #2 Existing docs moved to docs/ +- [ ] #3 README.md with project overview, quick start, and structure + + +## Final Summary + + +Repo structured, docs moved, README written with full project overview, hardware setup, command protocol, and licence info. + diff --git a/backlog/tasks/task-127 - Guide-JSON-format-bicycle-brake-pad-guide.md b/backlog/tasks/task-127 - Guide-JSON-format-bicycle-brake-pad-guide.md new file mode 100644 index 0000000..860bb5a --- /dev/null +++ b/backlog/tasks/task-127 - Guide-JSON-format-bicycle-brake-pad-guide.md @@ -0,0 +1,33 @@ +--- +id: TASK-127 +title: Guide JSON format + bicycle brake pad guide +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - content + - guide +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Define the guide JSON schema and create the demo guide (bicycle-brake-pads.json) with 10 steps including detection labels, fallback strategies, completion conditions, and timed hints. + + +## Acceptance Criteria + +- [ ] #1 Guide JSON validates against schema +- [ ] #2 10 steps with audio_text, pointer_target, completion_condition +- [ ] #3 Fallback strategies for non-COCO parts +- [ ] #4 Timed hints on each step + + +## Final Summary + + +bicycle-brake-pads.json created with 10 realistic steps, COCO anchor + relative_to fallbacks, dwell/manual completion, and 2 hints per step. + diff --git a/backlog/tasks/task-128 - Pico-firmware-—-servo-LED-drivers.md b/backlog/tasks/task-128 - Pico-firmware-—-servo-LED-drivers.md new file mode 100644 index 0000000..df2562a --- /dev/null +++ b/backlog/tasks/task-128 - Pico-firmware-—-servo-LED-drivers.md @@ -0,0 +1,33 @@ +--- +id: TASK-128 +title: Pico firmware — servo + LED drivers +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - firmware + - hardware +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write config.py, servo_driver.py (PCA9685 I2C, smooth interpolation), and led_driver.py (GPIO PWM brightness) for Raspberry Pi Pico. + + +## Acceptance Criteria + +- [ ] #1 PCA9685 init at 50Hz, set_angle with 500-2500us mapping +- [ ] #2 Smooth interpolation in configurable degree steps +- [ ] #3 LED PWM 0-255, blink helper, deinit cleanup +- [ ] #4 Config centralises all pin/calibration constants + + +## Final Summary + + +Three firmware files: config.py (constants), servo_driver.py (PCA9685 two-class design with smooth interp), led_driver.py (hardware PWM on GP15). + diff --git a/backlog/tasks/task-129 - Pico-firmware-—-command-parser-USB-serial.md b/backlog/tasks/task-129 - Pico-firmware-—-command-parser-USB-serial.md new file mode 100644 index 0000000..e7cdae0 --- /dev/null +++ b/backlog/tasks/task-129 - Pico-firmware-—-command-parser-USB-serial.md @@ -0,0 +1,32 @@ +--- +id: TASK-129 +title: Pico firmware — command parser + USB serial +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - firmware +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write command_parser.py (JSON line parser, validates & dispatches to servo/LED) and transport_usb.py (non-blocking USB serial listener at 115200 baud). + + +## Acceptance Criteria + +- [ ] #1 Parses all command types: pan/tilt, led, led_pwm, home, ping +- [ ] #2 Returns JSON ack with current position +- [ ] #3 Graceful error handling for malformed JSON +- [ ] #4 Non-blocking stdin poll with buffer overflow guard + + +## Final Summary + + +command_parser.py: stateless dispatcher with strict validation, defined processing order. transport_usb.py: select.poll non-blocking with 512-char overflow guard. + diff --git a/backlog/tasks/task-130 - Pico-firmware-—-BLE-transport-Pico-W.md b/backlog/tasks/task-130 - Pico-firmware-—-BLE-transport-Pico-W.md new file mode 100644 index 0000000..f3cc3f7 --- /dev/null +++ b/backlog/tasks/task-130 - Pico-firmware-—-BLE-transport-Pico-W.md @@ -0,0 +1,34 @@ +--- +id: TASK-130 +title: Pico firmware — BLE transport (Pico W) +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - firmware + - ble +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write transport_ble.py (BLE GATT Nordic UART Service) and main.py (auto-detect transport, cooperative poll loop). BLE advertises as 'GaiaAR', chunks notifications to 20-byte MTU. + + +## Acceptance Criteria + +- [ ] #1 NUS service with correct UUIDs registered +- [ ] #2 IRQ handler queues to pending list, no heavy work in interrupt +- [ ] #3 MTU chunking for notifications +- [ ] #4 Auto-reconnect advertising on disconnect +- [ ] #5 main.py soft-imports bluetooth for Pico/Pico W compat + + +## Final Summary + + +transport_ble.py: GATT NUS with chunked notify, per-connection line buffers, auto-readvertise. main.py: soft BLE import, cooperative dual-transport loop, error-resilient. + diff --git a/backlog/tasks/task-131 - PWA-—-camera-feed-shell.md b/backlog/tasks/task-131 - PWA-—-camera-feed-shell.md new file mode 100644 index 0000000..b553f3e --- /dev/null +++ b/backlog/tasks/task-131 - PWA-—-camera-feed-shell.md @@ -0,0 +1,33 @@ +--- +id: TASK-131 +title: PWA — camera feed + shell +status: Done +assignee: [] +created_date: '2026-03-29 20:51' +labels: + - pwa + - frontend +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write index.html (three views: setup/guide/complete), main.css (dark workshop theme, mobile-first), and camera.js (rear camera getUserMedia wrapper). + + +## Acceptance Criteria + +- [ ] #1 Three-view HTML shell with hidden attr toggling +- [ ] #2 Dark theme with amber/green accents, 48px+ touch targets +- [ ] #3 Camera feed fills viewport with environment-facing preference +- [ ] #4 Graceful fallback for desktop webcams + + +## Final Summary + + +index.html (183 lines), main.css (732 lines dark workshop theme), camera.js (environment-facing, desktop fallback). + diff --git a/backlog/tasks/task-132 - PWA-—-transport-abstraction-simulator-serial-BLE.md b/backlog/tasks/task-132 - PWA-—-transport-abstraction-simulator-serial-BLE.md new file mode 100644 index 0000000..da72b2b --- /dev/null +++ b/backlog/tasks/task-132 - PWA-—-transport-abstraction-simulator-serial-BLE.md @@ -0,0 +1,34 @@ +--- +id: TASK-132 +title: PWA — transport abstraction (simulator + serial + BLE) +status: Done +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - pwa + - transport +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write transport.js (GaiaTransport base class, SerialTransport via Web Serial, BLETransport via Web Bluetooth NUS, SimulatorTransport) and simulator.js (virtual pan/tilt panel with crosshair + LED indicator). + + +## Acceptance Criteria + +- [ ] #1 Base class with connect/disconnect/send/onMessage/isConnected +- [ ] #2 SerialTransport: Web Serial 115200 baud, JSON lines +- [ ] #3 BLETransport: NUS UUIDs, TX notify subscription, 20-byte MTU chunking +- [ ] #4 SimulatorTransport: passes to Simulator.update() +- [ ] #5 Simulator: floating panel with crosshair dot + LED circle + readout + + +## Final Summary + + +transport.js: 3 implementations + factory. simulator.js: DOM panel with crosshair grid, LED indicator, angle readout. ?transport=simulator URL param works. + diff --git a/backlog/tasks/task-133 - PWA-—-guide-engine-step-sequencing-audio.md b/backlog/tasks/task-133 - PWA-—-guide-engine-step-sequencing-audio.md new file mode 100644 index 0000000..872b43b --- /dev/null +++ b/backlog/tasks/task-133 - PWA-—-guide-engine-step-sequencing-audio.md @@ -0,0 +1,33 @@ +--- +id: TASK-133 +title: PWA — guide engine (step sequencing + audio) +status: Done +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - pwa + - guide +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write guide-engine.js (load/sequence/advance steps, dwell timer completion detection, onStepChange/onGuideComplete callbacks), audio-engine.js (Web Speech TTS wrapper), and guide-store.js (IndexedDB offline cache). + + +## Acceptance Criteria + +- [ ] #1 Guide engine normalises both canonical and on-disk JSON schemas +- [ ] #2 Dwell timer tracks continuous detection, resets on break +- [ ] #3 TTS with English voice preference and queue support +- [ ] #4 IndexedDB store with save/get/list/delete/importFromUrl + + +## Final Summary + + +guide-engine.js: dual schema normalisation, dwell timer. audio-engine.js: SpeechSynthesis with voice selection. guide-store.js: IndexedDB gaia-guides store. + diff --git a/backlog/tasks/task-134 - PWA-—-MediaPipe-CV-pipeline-pointer-mapper.md b/backlog/tasks/task-134 - PWA-—-MediaPipe-CV-pipeline-pointer-mapper.md new file mode 100644 index 0000000..22f9084 --- /dev/null +++ b/backlog/tasks/task-134 - PWA-—-MediaPipe-CV-pipeline-pointer-mapper.md @@ -0,0 +1,35 @@ +--- +id: TASK-134 +title: PWA — MediaPipe CV pipeline + pointer mapper +status: Done +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - pwa + - cv +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Write cv-pipeline.js (MediaPipe ObjectDetector from CDN, EfficientDet Lite 0 float16, VIDEO mode, detection overlay drawing) and pointer-mapper.js (FOV-based bbox→pan/tilt angle conversion with exponential smoothing). + + +## Acceptance Criteria + +- [ ] #1 Dynamic import from MediaPipe CDN with GPU delegate + CPU fallback +- [ ] #2 detectForVideo returns normalised bboxes with centerX/centerY +- [ ] #3 drawDetections: green for target, amber dashed for others, HiDPI aware +- [ ] #4 pixelToAngles: mirrored X axis, 80/60 FOV default +- [ ] #5 relativeTarget for fallback anchor offsets +- [ ] #6 Exponential smoothing factor 0.3 + + +## Final Summary + + +cv-pipeline.js: MediaPipe Tasks Vision CDN, EfficientDet Lite 0, normalised detections, styled overlay. pointer-mapper.js: FOV mapping, EMA smoothing, relative fallback. + diff --git a/backlog/tasks/task-135 - PWA-—-offline-support-SW-IndexedDB.md b/backlog/tasks/task-135 - PWA-—-offline-support-SW-IndexedDB.md new file mode 100644 index 0000000..304f00c --- /dev/null +++ b/backlog/tasks/task-135 - PWA-—-offline-support-SW-IndexedDB.md @@ -0,0 +1,34 @@ +--- +id: TASK-135 +title: PWA — offline support (SW + IndexedDB) +status: Done +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - pwa + - offline +milestone: m-2 +dependencies: [] +priority: medium +--- + +## Description + + +Write sw.js (service worker with 3 cache buckets: shell/guides/mediapipe, cache-first for shell+CDN, network-first for guides, offline fallback) and manifest.json (PWA install metadata). + + +## Acceptance Criteria + +- [ ] #1 Three versioned cache buckets +- [ ] #2 Shell pre-cached on install, old caches cleaned on activate +- [ ] #3 CACHE_GUIDE_URL message handler for dynamic guide caching +- [ ] #4 Offline fallback: cached index.html for nav, error JSON for guides +- [ ] #5 PWA manifest with standalone display and portrait orientation + + +## Final Summary + + +sw.js (210 lines): 3 cache buckets, pre-cache on install, clients.claim(), offline fallback. manifest.json with simulator shortcut. + diff --git a/backlog/tasks/task-136 - End-to-end-hardware-test.md b/backlog/tasks/task-136 - End-to-end-hardware-test.md new file mode 100644 index 0000000..a2bd90f --- /dev/null +++ b/backlog/tasks/task-136 - End-to-end-hardware-test.md @@ -0,0 +1,28 @@ +--- +id: TASK-136 +title: End-to-end hardware test +status: To Do +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - testing + - hardware +milestone: m-2 +dependencies: [] +priority: high +--- + +## Description + + +Test full pipeline with physical hardware: Pico + PCA9685 + servos + LED. Verify USB serial command/ack, BLE connect from nRF Connect, servo movement, LED control. Test PWA↔Pico over both transports. + + +## Acceptance Criteria + +- [ ] #1 USB: echo JSON to /dev/ttyACM0, servo moves, LED on, ack received +- [ ] #2 BLE: nRF Connect write to NUS RX, verify TX response +- [ ] #3 PWA serial mode: connect, guide step sends pan/tilt, servo tracks +- [ ] #4 PWA BLE mode: same as serial but wireless +- [ ] #5 No firmware crash on malformed input + diff --git a/backlog/tasks/task-137 - Fill-slide-deck-gaps-slides-8-9-13-14-A3-A4.md b/backlog/tasks/task-137 - Fill-slide-deck-gaps-slides-8-9-13-14-A3-A4.md new file mode 100644 index 0000000..211080e --- /dev/null +++ b/backlog/tasks/task-137 - Fill-slide-deck-gaps-slides-8-9-13-14-A3-A4.md @@ -0,0 +1,35 @@ +--- +id: TASK-137 +title: 'Fill slide deck gaps (slides 8, 9, 13, 14, A3, A4)' +status: Done +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - docs + - slides +milestone: m-2 +dependencies: [] +priority: medium +--- + +## Description + + +Write missing content for 4 slides in SLIDE_DECK_PROMPT.md (BT communication, single earbud, manufacturing, IP/Commons) and 2 slides in ANNEX_PROMPT.md (healthcare/first aid, closing platform statement). + + +## Acceptance Criteria + +- [ ] #1 Slide 8: BT 5.0 dual connection, NUS, <20ms latency, USB-C fallback +- [ ] #2 Slide 9: single earbud spec — IPX4, 4h+, physical button, TTS-driven +- [ ] #3 Slide 13: Phase 1 CEM 500 units, Phase 2 local 3D-print + kit +- [ ] #4 Slide 14: triple licence stack (CERN-OHL-S, AGPL, CC BY-SA) +- [ ] #5 A3: healthcare/first aid — wound care, CPR, tourniquet +- [ ] #6 A4: closing — platform not product, Commons logic + + +## Final Summary + + +All 6 GAP placeholders replaced with full slide content matching deck tone and format. BT, earbud, manufacturing, IP, healthcare, closing slides complete. + diff --git a/backlog/tasks/task-138 - Document-headlamp-mounting-interface.md b/backlog/tasks/task-138 - Document-headlamp-mounting-interface.md new file mode 100644 index 0000000..000fb91 --- /dev/null +++ b/backlog/tasks/task-138 - Document-headlamp-mounting-interface.md @@ -0,0 +1,27 @@ +--- +id: TASK-138 +title: Document headlamp mounting interface +status: To Do +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - hardware + - docs +milestone: m-2 +dependencies: [] +priority: medium +--- + +## Description + + +Measure and document the slide-and-lock interface on the Decathlon Forclaz headlamp. Create a technical drawing or dimensioned sketch for the custom module housing design. Include tolerances for 3D printing. + + +## Acceptance Criteria + +- [ ] #1 Physical measurements of headlamp mounting interface +- [ ] #2 Dimensioned sketch or CAD file in docs/ +- [ ] #3 Print tolerances documented for FDM PETG/ASA +- [ ] #4 Photos of reference headlamp for comparison + diff --git a/backlog/tasks/task-139 - First-user-test-5-users.md b/backlog/tasks/task-139 - First-user-test-5-users.md new file mode 100644 index 0000000..51a8f1e --- /dev/null +++ b/backlog/tasks/task-139 - First-user-test-5-users.md @@ -0,0 +1,28 @@ +--- +id: TASK-139 +title: First user test (5 users) +status: To Do +assignee: [] +created_date: '2026-03-29 20:52' +labels: + - testing + - ux +milestone: m-2 +dependencies: [] +priority: medium +--- + +## Description + + +Recruit 5 users with no prior bicycle repair experience. Test full end-to-end flow: put on headset, connect phone, follow brake pad guide to completion. Document usability issues, completion rate, time, and qualitative feedback. + + +## Acceptance Criteria + +- [ ] #1 5 users complete the test session +- [ ] #2 Completion rate and time recorded per user +- [ ] #3 Usability issues documented with severity ratings +- [ ] #4 Post-test interview notes captured +- [ ] #5 Summary report with top 3 improvement priorities +