Files
faceclaw/docs/validation-head-up.md
T
Blendman974 fe0cf5b777 Merge shared tilt-down hide and angle measurement
# Conflicts:
#	app/g2/dashboard-controller.ts
#	app/g2/ios-preview-controller.ts
2026-11-06 22:10:41 +01:00

74 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Head-up wake: software and hardware validation
The Android Display settings now contain “Head-up wake” and “Head-up angle”.
Glanceboard's “Show on head tilt” still only chooses which UI appears on wake.
Protocol reference: [OpenG2 Companion G2Protocol.swift](https://github.com/mmirman/open-g2-companion/blob/1400d1006ba045379a3ff34d0832add6fa10ced4/modules/ffs-ble/ios/G2Protocol.swift),
`setHeadUpSwitch` / `setHeadUpAngle`; dispatch to both lenses in
[`G2Central.swift`](https://github.com/mmirman/open-g2-companion/blob/1400d1006ba045379a3ff34d0832add6fa10ced4/modules/ffs-ble/ios/G2Central.swift).
Wire format uses Faceclaw's UI-settings sid 0x09, request flag, command 1, transaction
magic, device-receive-info field 3 / head-up field 4. Switch (field 1) and
angle (field 2) are sent in separate messages, including explicit zero values.
Angles are clamped to the reference's 0–60 degree range. No firmware patch,
firmware download or flash is needed by this implementation.
Untouched installations send neither field. The UI describes this inherited
state; its displayed ON/30 degree fallback is not a read-back of device state.
Changing just one control preserves the other device field. Explicit choices
are persisted in the existing settings store and resent on every connection.
The native session also retains them through transport reconnects and retries
after setting ACK timeouts. ACK reception confirms transport, not physical wake.
Software checks:
- `tests/head-up-wake.test.cjs`: persistence, untouched fields, angle bounds,
independence from Glanceboard, deduplication, reconnect and error recovery.
- `HeadUpProtocolTest`: byte-for-byte settings messages, including OFF and 0°.
- `GlassesSessionCoreTest`: both lenses, separate writes, pre-existing device
settings preserved, angle clamp and automatic transport reconnection.
Hardware validation: **pending**. Implementation was requested without device
access; protocol compatibility and physical effect on the target Faceclaw CFW
are not established by these software tests. The reference targets stock
2.2.6.10, while this repository normally uses newer Faceclaw firmware.
Source inspection of [Faceclaw's gesture forwarding](https://github.com/jimrandomh/g2flash/blob/845f665e0dfdcfd06b7d3a294388de6f17a5bd59/patches/gesture_fwd.c)
confirms that head-up/down forwarding while a page owns the screen checks the
stock `head_up_switch`. This supports using the existing setting rather than a
firmware patch, but does not establish the physical angle or wake behavior.
On the target glasses, record both lens firmware versions and test:
1. Leave preferences untouched and verify prior wake behavior remains unchanged.
2. Disable Head-up wake; sleep the display, raise the head repeatedly, and confirm
no wake. Check taps still wake normally.
3. Enable it and compare 0°, 30° and 60° trigger angles. Confirm other wake
gestures remain usable, including at the extreme values.
4. Reconnect Bluetooth, then restart the phone app; repeat ON/OFF and angle checks.
5. Toggle Glanceboard and “Show on head tilt” independently; disabled wake should
stay disabled, enabled wake should show the selected UI.
6. Check both lenses remain synchronized, including reconnecting only one arm.
Do not change firmware to run these checks without explicit permission.
## Shared tilt-down hide and current-angle estimate
Inspired by [Faceclaw PR #64](https://github.com/jimrandomh/faceclaw/pull/64), Display settings now include one Tilt down to hide toggle (off by default), used by both the regular glasses UI and Glanceboard. HEAD_DOWN is forwarded by the existing firmware (event 15, Faceclaw/38), consumed before input filtering/activity tracking, and never wakes the screen. With the option enabled it dismisses Glanceboard and sleeps the regular UI, including after a manual wake. The action is an explicit sleep gesture, like manually turning the display off. With the option disabled, it is ignored, preserving prior behavior.
A Glanceboard shown by head-up uses a 60-second safety limit when Tilt down to hide is enabled; otherwise the existing tap timeout is retained. Show on head tilt still selects what appears on wake. There are no separate Glanceboard angle/hide preferences. iOS consumes the shared HEAD_DOWN event so it cannot become spurious input; current-angle measurement remains Android-only.
Set to current head angle performs a short experimental IMU measurement, then stores the result in the existing shared Head-up angle preference. It reads the glasses' restored calibration (settings request field 9) and subtracts it before saving the raw firmware angle. Existing raw-angle preferences and untouched fields keep their original meaning. A temporary native IMU lease restores the latest application request, including changes made during measurement. Sampling uses one temple only; ring readings, non-finite/zero vectors, unstable samples and unsupported offsets are rejected. Failures leave the saved angle unchanged. Existing synchronization sends the result to both lenses and restores it on reconnect.
Important measurement limitation: PR #64's dominant-axis inclination estimate is approximate, includes side tilt, and cannot disambiguate a dominant-axis swap beyond 45 degrees. The menu explicitly marks it experimental and asks for a moderate angle below 45 degrees with the head level sideways. It does not claim hardware-calibrated pitch; the manual 0–60 degree control remains available. Firmware calibration is not rewritten. Do not rely on software tests alone for physical angle accuracy.
Additional software coverage: shared preference persistence; controller routing with the display awake/asleep and the option on/off; Glanceboard safety timeout; measurement success/failure, concurrent calls, missing/moving sensors, ring exclusion and cleanup; calibration protocol zero/signed/missing fields; native IMU lease restoration; native HEAD_DOWN forwarding without user activity.
Extended independent validation: 1070 JavaScript tests passed, 2 skipped; 272 Kotlin Android host tests passed; TypeScript and changed-source lint passed. Physical wake, hide and angle accuracy remain unverified on glasses.
Combined validation: 1135 JavaScript tests passed, 2 skipped; all 276 Kotlin Android host tests passed. TypeScript and changed-source lint passed. Hardware validation remains pending.
HEAD_DOWN delivery still depends on the glasses’ firmware head-up switch: enable Head-up wake when using Tilt down to hide. Enabling hide does not silently override an explicit head-up OFF preference.
The combined Android release APK builds successfully; signature, non-debug manifest, ELF 16 KiB alignment and ZIP alignment checks passed. It was not installed during this task.