CueSheetEnricher interface and canonical direction enum #26

New issue

Open

opened 2026-08-31 17:14:44 +02:00 by robert · 0 comments

robert commented

2026-08-31 17:14:44 +02:00

(Migrated from git.butzei.de)

Goal

One vocabulary for turns, so every backend and the watch icon set agree.

Acceptance criteria

Canonical direction enum adopted from the komoot BLE Connect spec: straight, forks, turns, roundabout exits, start, finish, off-route
CueSheetEnricher interface: takes a polyline, returns an ordered cue sheet
Cue = (polyline index, direction enum, street name, distance along route)
Backends tried in order with graceful fallback; which one succeeded is recorded
Mapping from each backend's vocabulary lives in exactly one place

Files

companion/.../route/enrich/CueSheetEnricher.kt
companion/.../route/enrich/Direction.kt

Notes

Spec: https://github.com/palto42/BLEConnect - the enum is well designed and publicly documented, which is why it is worth adopting even though we never talk to komoot.

Update — 2026-09-01: four tiers, and cue confidence

The chain gains a tier 0 and loses GraphHopper (D26):

Tier	Backend	Needs	Quality
0	`GpxCueEnricher` (#63) — cues already in the file	nothing	exact where present
1	`BRouterEnricher` (#27) via AIDL	BRouter + segments	good, subject to D25
2	`MatchingEnricher` (#28) — Valhalla only	network, consent	good
3	`GeometryEnricher` (#29) — heading delta	nothing	crude, no street names

Interface admits four implementations tried in order, with tier 0 first
Each cue carries which tier produced it, surfaced to the watch as NAV_CUE_CONFIDENCE so a
geometric guess is not presented with the authority of a matched turn
The canonical enum mapping layer covers the GPX vocabularies from #63 too, in the same place

## Goal One vocabulary for turns, so every backend and the watch icon set agree. ## Acceptance criteria - [ ] Canonical direction enum adopted from the komoot BLE Connect spec: straight, forks, turns, roundabout exits, start, finish, off-route - [ ] `CueSheetEnricher` interface: takes a polyline, returns an ordered cue sheet - [ ] Cue = (polyline index, direction enum, street name, distance along route) - [ ] Backends tried in order with graceful fallback; which one succeeded is recorded - [ ] Mapping from each backend's vocabulary lives in exactly one place ## Files - `companion/.../route/enrich/CueSheetEnricher.kt` - `companion/.../route/enrich/Direction.kt` ## Notes Spec: https://github.com/palto42/BLEConnect - the enum is well designed and publicly documented, which is why it is worth adopting even though we never talk to komoot. ## Update — 2026-09-01: four tiers, and cue confidence The chain gains a tier 0 and loses GraphHopper (D26): | Tier | Backend | Needs | Quality | |---|---|---|---| | 0 | `GpxCueEnricher` (#63) — cues already in the file | nothing | exact where present | | 1 | `BRouterEnricher` (#27) via AIDL | BRouter + segments | good, subject to D25 | | 2 | `MatchingEnricher` (#28) — **Valhalla only** | network, consent | good | | 3 | `GeometryEnricher` (#29) — heading delta | nothing | crude, no street names | - [ ] Interface admits four implementations tried in order, with tier 0 first - [ ] **Each cue carries which tier produced it**, surfaced to the watch as `NAV_CUE_CONFIDENCE` so a geometric guess is not presented with the authority of a matched turn - [ ] The canonical enum mapping layer covers the GPX vocabularies from #63 too, in the same place