forked from Blendman974/faceclaw
# Conflicts: # app/g2/dashboard-controller.ts # app/g2/ios-preview-controller.ts
74 lines
6.7 KiB
Markdown
74 lines
6.7 KiB
Markdown
# 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.
|