robert/PedalPebble
Watch
1
0
Fork
You've already forked PedalPebble
 0
Code Issues 43 Pull requests Projects Releases 1 Packages Wiki Activity Actions

Field value store and page descriptor model #58

New issue
Closed
opened 2026-08-31 17:55:57 +02:00 by robert · 1 comment
robert commented 2026-08-31 17:55:57 +02:00 (Migrated from git.butzei.de)
Copy link

Goal

Make pages data rather than layout code. This is the foundation that lets the phone configure screens later without rewriting the views, and it must land before any view hard-codes a layout.

Acceptance criteria

  • FieldId enum covering every metric: speed, average and max speed; distance, elapsed, clock; HR, average HR, HR zone; power, 3 s power, average and normalised power; cadence and average cadence; ETA, remaining, distance to turn; lap number, distance, time and average speed
  • Value store keyed by FieldId, updated as messages arrive, each entry carrying its last-update timestamp
  • One formatter table per field: decimal places, unit string, and unavailable rendering
  • PageDescriptor { template, fields[6] } with descriptors held in persistent storage
  • A field with no source renders -- - never a stale value, never zero
  • A page whose every field is sourceless is skipped in the carousel
  • A value older than its expected update interval renders greyed
  • Default descriptors defined in code for the three shipped pages

Files

  • watchapp/src/c/fields.c
  • watchapp/src/c/fields.h
  • watchapp/src/c/page.h

Notes

See docs/DESIGN.md sections 1 and 2. Getting this in before #9 is the whole point - a hard-coded layout makes the later phone configuration a rewrite.

Update — 2026-09-01: every field needs a producer and a wire key

The enum defined MAX_SPEED, AVG_HR, HR_ZONE, AVG_CADENCE and NORM_POWER with nothing
anywhere in the plan computing them — fields that could only ever render --. #65 now produces them
and docs/PROTOCOL.md gives them wire keys (D28).

  • Every FieldId maps to a key in docs/PROTOCOL.md, or is documented as watch-local (HR,
    CLOCK)
  • The unavailable sentinel is distinguishable from a real zero — zero is a legitimate speed,
    cadence and power
  • Keep the store and formatters free of SDK calls so they are host-testable (#68)

Update — 2026-09-02: stale and unavailable are two states

The store already carries a last-update timestamp per entry, and the criteria above ask for both
-- and greying. Those are different states and were being conflated (D44).

  • -- means there is no source. It is signalled by the phone with the type's sentinel,
    never inferred from silence
  • Grey means the producer or the link went quiet. The number was true and may still be
  • Staleness is measured against the field's group heartbeat (PROTOCOL §4) and link liveness,
    not against that key's own last arrival. Under changed-keys-only updates a constant value —
    speed of zero at a traffic light, distance while paused — stops being sent and would otherwise
    grey out while perfectly fresh
  • The 10 s full refresh is not the staleness mechanism; relying on it forces a threshold above
    10 s, far too coarse to catch a 3 s gap
## Goal Make pages data rather than layout code. This is the foundation that lets the phone configure screens later without rewriting the views, and it must land before any view hard-codes a layout. ## Acceptance criteria - [ ] `FieldId` enum covering every metric: speed, average and max speed; distance, elapsed, clock; HR, average HR, HR zone; power, 3 s power, average and normalised power; cadence and average cadence; ETA, remaining, distance to turn; lap number, distance, time and average speed - [ ] Value store keyed by `FieldId`, updated as messages arrive, each entry carrying its last-update timestamp - [ ] One formatter table per field: decimal places, unit string, and unavailable rendering - [ ] `PageDescriptor { template, fields[6] }` with descriptors held in persistent storage - [ ] **A field with no source renders `--`** - never a stale value, never zero - [ ] **A page whose every field is sourceless is skipped in the carousel** - [ ] A value older than its expected update interval renders greyed - [ ] Default descriptors defined in code for the three shipped pages ## Files - `watchapp/src/c/fields.c` - `watchapp/src/c/fields.h` - `watchapp/src/c/page.h` ## Notes See docs/DESIGN.md sections 1 and 2. Getting this in before #9 is the whole point - a hard-coded layout makes the later phone configuration a rewrite. ## Update — 2026-09-01: every field needs a producer and a wire key The enum defined `MAX_SPEED`, `AVG_HR`, `HR_ZONE`, `AVG_CADENCE` and `NORM_POWER` with nothing anywhere in the plan computing them — fields that could only ever render `--`. #65 now produces them and `docs/PROTOCOL.md` gives them wire keys (D28). - [ ] Every `FieldId` maps to a key in docs/PROTOCOL.md, or is documented as watch-local (`HR`, `CLOCK`) - [ ] The unavailable sentinel is distinguishable from a real zero — zero is a legitimate speed, cadence and power - [ ] Keep the store and formatters **free of SDK calls** so they are host-testable (#68) ## Update — 2026-09-02: stale and unavailable are two states The store already carries a last-update timestamp per entry, and the criteria above ask for both `--` and greying. Those are different states and were being conflated (D44). - [ ] **`--`** means there is no source. It is **signalled** by the phone with the type's sentinel, never inferred from silence - [ ] **Grey** means the producer or the link went quiet. The number was true and may still be - [ ] Staleness is measured against the field's **group heartbeat** (PROTOCOL §4) and link liveness, **not** against that key's own last arrival. Under changed-keys-only updates a constant value — speed of zero at a traffic light, distance while paused — stops being sent and would otherwise grey out while perfectly fresh - [ ] The 10 s full refresh is not the staleness mechanism; relying on it forces a threshold above 10 s, far too coarse to catch a 3 s gap
robert commented 2026-09-04 00:49:48 +02:00
Owner
Copy link

Closed by PR #81 (merged): FieldId enum, group-heartbeat value store (D44: unavailable vs stale are separate states), per-field formatter table (units live in the label per DESIGN.md rule 5, never appended by field_format), PageDescriptor + page_has_live_field() (the primitive #60 needs), wire/persisted packing matching PROTOCOL.md 2.6 byte-for-byte, and the three default pages (Ride/Effort/Progress) from DESIGN.md section 4. pebble build run clean for emery/gabbro/basalt; fields.c/.h additionally compiled and smoke-tested standalone with host gcc. Staleness thresholds, ETA-as-duration, and the single-blob persist layout are design calls flagged in the PR body for review. #68's host-test harness intentionally left unbuilt — fields.c/.h are proven host-compilable but page.c mixes in persist_* calls, so a clean split/stub is #68's own call to make.

Closed by PR #81 (merged): FieldId enum, group-heartbeat value store (D44: unavailable vs stale are separate states), per-field formatter table (units live in the label per DESIGN.md rule 5, never appended by field_format), PageDescriptor + page_has_live_field() (the primitive #60 needs), wire/persisted packing matching PROTOCOL.md 2.6 byte-for-byte, and the three default pages (Ride/Effort/Progress) from DESIGN.md section 4. `pebble build` run clean for emery/gabbro/basalt; fields.c/.h additionally compiled and smoke-tested standalone with host gcc. Staleness thresholds, ETA-as-duration, and the single-blob persist layout are design calls flagged in the PR body for review. #68's host-test harness intentionally left unbuilt — fields.c/.h are proven host-compilable but page.c mixes in persist_* calls, so a clean split/stub is #68's own call to make.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
area/gpx-cue-enricher-d59
area/round-display-support
area/rejoin-point-selection
area/digit-height-content-aware
area/geometry-enricher
area/page-template-hero1-grid6
area/nav-engine
area/cue-sheet-review
area/map-viewport-geometry
area/navigation-snapping-test-audit
area/lap-function
area/navigation-snapping
area/ble-power-meter
area/gpx-export
area/gpx-recording
area/pkjs-speed-feed
tooling/watchapp-distribution
area/csc-cadence
area/about-screen
area/backlight-policy
tooling/gpx-replay
area/derived-metrics
area/speed-pipeline-coverage-audit
area/speed-source-arbitration
area/speed-pipeline
area/stop-detector
area/ble-csc-sensor
area/persist-ride-state
area/foreground-location-service
area/protocol-version-handshake
area/real-komoot-fixture
tooling/message-keys-codegen
tooling/fix-android-platform-doc
area/settings-screen
tooling/first-real-android-build
tooling/fix-runner-label
area/cue-sheet-cache
area/route-library
area/page-template-renderer
area/colour-palette
area/page-carousel
area/ride-state-machine
area/watchapp-skeleton
tooling/host-test-harness
area/field-store-page-descriptors
tooling/ci-pipeline
area/cue-sheet-enricher-interface
area/gpx-share-import
process/security-persona
area/android-companion-skeleton
tooling/pebble-sdk-emulators
process/team-and-pipeline
dev-latest
v0.5.0
Labels
Clear labels   
area:companion
Android companion app

  
area:docs
Documentation

  
area:shared
Message contract shared by both sides

  
area:tooling
Build tooling, SDK, dev scripts

  
area:watchapp
Pebble C watchapp

  
blocker
Blocks a large part of the project until resolved

  
kind:chore
Setup, scaffolding, maintenance

  
kind:feature
New functionality

  
kind:spike
Time-boxed investigation to de-risk a decision

  
kind:test
Tests and fixtures

No labels
area:companion
area:docs
area:shared
area:tooling
area:watchapp
blocker
kind:chore
kind:feature
kind:spike
kind:test
Milestone
Clear milestone
No items
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#9 Default page definitions: Ride, Effort, Progress
robert/PedalPebble
#10 HRM integration with sample-period lifecycle
robert/PedalPebble
#46 Lap function
robert/PedalPebble
#59 Page template renderer: HERO1, HERO2, QUAD, GRID6
robert/PedalPebble
#60 Page carousel navigation with long-press jumps
robert/PedalPebble
#61 Configure watch pages from the phone
robert/PedalPebble
#68 Host-side unit tests for the watchapp logic
robert/PedalPebble
Depends on
#2 Install Pebble SDK toolchain, build and run on the emery and gabbro emulators
robert/PedalPebble
Reference
robert/PedalPebble#58
No description provided.