[Accessories] 3 - Calibrate live ground clearance

[KacperKozak]

Parent

#475

What to build

Open the ground-clearance configuration screen by tapping its accessory row in the Board selector's Accessories section. Keep live readings and automatic calibration saving on that detail screen. Settings → Sensors is spike prior art, not the intended navigation.

Deliver the ToF-only reading path with explicit status, accepted rates, live display, measurement standby, and automatically saved calibration. No tilt actuation in this slice. Firmware actually stops continuous measurement when demand expires; opening/closing the screen changes preview demand through native configuration.

Type: AFK. Complexity: high. Blocked by: 2. Stories: 7–10, 13–14, 19, 26.

Likely files

• vescape-accessories: src/main.cpp — sensor driver, measurements, and command application.
• vescape-accessories: platformio.ini — existing firmware build/library configuration.
• modules/vescape-core/android/src/main/java/expo/modules/vescapecore/hardware/SensorLog.kt — PR Vescape Sensors: BLE link to the ESP32 sensor module #441 numeric buffering prior art.
• modules/vescape-core/android/src/main/java/expo/modules/vescapecore/hardware/SensorReadings.kt — PR Vescape Sensors: BLE link to the ESP32 sensor module #441 missing-value behavior to replace.
• modules/vescape-core/ios/VescapeCoreModule.swift — peer native bridge for new reading/settings contract.
• src/modules/hardware/hooks/useSensors.ts — PR Vescape Sensors: BLE link to the ESP32 sensor module #441 reading presentation starting point.
• src/app/settings/sensors.tsx — PR Vescape Sensors: BLE link to the ESP32 sensor module #441 screen starting point.
• docs/accessories.md — calibration/standby behavior.

Implementation hints

• The parent PRD includes the complete protocol and product-design snapshots. Local docs may not yet exist on the implementation branch; materialize them from the parent when needed.
• PR Vescape Sensors: BLE link to the ESP32 sensor module #441 is prior art at commit 91ebeaf0fdf3daa8a8151314048de9e663b9149c; paths marked PR Vescape Sensors: BLE link to the ESP32 sensor module #441 are absent from the planning checkout.
• Paths prefixed vescape-accessories: belong to vescape-app/vescape-accessories. Coordinate both repositories for firmware/app protocol changes.
• Keep native Android/iOS contracts aligned with parity links. Reuse native lifecycle and storage contracts; JS renders state and sends intents.

Acceptance criteria

• Open the ground-clearance configuration screen by tapping its accessory row in the Board selector's Accessories section. Keep live readings and automatic calibration saving on that detail screen. Settings → Sensors is spike prior art, not the intended navigation.

• readings show centimetres.

• invalid data never becomes maximum distance.

• near/far/direction/strength save when complete and valid.

• settings survive restart.

• unconfigured state is explained.

• leaving the screen while not riding stops measurements but preserves BLE.

• ultrasonic code is removed.

• fresh-session sampling is covered.

Blocked by

• [Accessories] 2 - Save and reconnect accessories #477

Related

• [Accessories] 1 - Discover compatible accessories #476
• [Accessories] 2 - Save and reconnect accessories #477
• [Accessories] 4 - Apply ground-clearance tilt #479
• [Accessories] 5 - Drive brake-light states #480
• [Accessories] 6 - Validate connected riding #481

[KacperKozak]

Implemented in 41cbdbd and f0525a5 on accessories, with firmware in vescape-app/vescape-hardware@c9d1fc0.

Not verified on hardware: no VL53L0X or ESP32 was attached, so the live reading path, measurement standby actually stopping the sensor, and the rate the firmware sustains are all reasoned from the protocol fixtures rather than observed.
Not verified on a device build: no Android or iOS build was installed, so the ground-clearance screen has not been seen running.
Deviation: the screen opens from the Board selector's accessory row via that accessory's detail screen, whose capability rows are now tappable — #477 built the detail screen explicitly as the place per-capability setup hangs off, and one accessory may declare several capabilities.