6.1 KiB
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,
setHeadUpSwitch / setHeadUpAngle; dispatch to both lenses in
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
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:
- Leave preferences untouched and verify prior wake behavior remains unchanged.
- Disable Head-up wake; sleep the display, raise the head repeatedly, and confirm no wake. Check taps still wake normally.
- Enable it and compare 0°, 30° and 60° trigger angles. Confirm other wake gestures remain usable, including at the extreme values.
- Reconnect Bluetooth, then restart the phone app; repeat ON/OFF and angle checks.
- Toggle Glanceboard and “Show on head tilt” independently; disabled wake should stay disabled, enabled wake should show the selected UI.
- 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, 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.