From e5649e9782bfa3a06b90e62d8b5f5abd5158791c Mon Sep 17 00:00:00 2001 From: James Babcock Date: Thu, 23 Jul 2026 18:40:48 -0700 Subject: [PATCH] Add experimental option to end EvenHub session when the screen is off for power saving --- .../faceclaw/app/FaceclawBleCommunicator.java | 110 ++++++++++++++- .../faceclaw/app/g2protocol/BleProtocol.java | 28 ++++ app/g2/dashboard-controller.ts | 133 ++++++++++++++++-- app/native/faceclaw-communicator.ts | 28 ++++ app/ui/dashboard-settings.ts | 7 + app/ui/dashboard/settings-menus.ts | 2 + app/ui/layers.ts | 5 + app/ui/shell/shell.ts | 14 ++ 8 files changed, 315 insertions(+), 12 deletions(-) diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java index 01a265a0..833e3f1f 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java @@ -501,6 +501,79 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { } public boolean sendShutdown(int exitMode) { + return sendShutdownInternal(exitMode, true); + } + + /** + * End the EvenHub page while retaining both arm GATT connections and all + * notification subscriptions. A missed ACK is intentionally non-fatal: + * reconnecting Bluetooth here would defeat the power-saving mode. + */ + public boolean suspendEvenHubSession() { + if (sendShutdownInternal(0, false)) { + return true; + } + synchronized (lock) { + // A shutdown ACK can be lost even though the command took effect. + // If the transport remains intentionally quiesced, callers still + // need to remember to run the resume path on the next wake. + return running && sessionReady && shutdownRequested; + } + } + + /** + * Start a fresh EvenHub plugin task on the existing BLE transport, then let + * the session driver create the layout, warm up the image path, and send + * desiredBmp. + */ + public boolean resumeEvenHubSession() { + synchronized (lock) { + if (!running || !sessionReady || chargingMode) { + logLine("skip EvenHub resume; transport not ready"); + return false; + } + if (!shutdownRequested) { + return true; + } + logLine("replaying session prelude for EvenHub resume"); + } + + try { + // Empty-name Cmd=9 tears down the whole plugin task, not just its + // image container. Re-run the launch prelude before Cmd=0 CREATE. + sendPrelude(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + handleTransportFailure("EvenHub resume prelude interrupted"); + return false; + } catch (Throwable t) { + logLine("EvenHub resume prelude failed: " + safeMessage(t)); + handleTransportFailure("EvenHub resume prelude failed"); + return false; + } + + synchronized (lock) { + if (!running || !sessionReady || chargingMode) { + return false; + } + shutdownRequested = false; + fixedLayoutCreated = false; + warmedUp = false; + startupProbePending = false; + audioCaptureActive = false; + clearAllMessagesLocked("EvenHub resume"); + displayedFingerprint = ""; + displayedBmp = new byte[0]; + imageRetryAfterMs = 0; + lastHeartbeatSentAtMs = 0; + lastHeartbeatAckedAtMs = 0; + logLine("EvenHub session resume requested"); + } + interruptibleSleep.interrupt(); + return true; + } + + private boolean sendShutdownInternal(int exitMode, boolean reconnectOnTimeout) { int magic; long startedAtMs = SystemClock.elapsedRealtime(); synchronized (lock) { @@ -508,7 +581,13 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { logLine("skip shutdown; session not ready"); return false; } + if (shutdownRequested) { + return true; + } shutdownRequested = true; + // Magic values wrap, so an ACK from a much older suspend must not + // satisfy this request after enough sleep/wake cycles. + lastShutdownAckMagic = 0; clearPendingMessagesLocked("shutdown requested"); OutboundMessage message = messageBuilder.shutdown(exitMode); magic = message.magic; @@ -520,7 +599,11 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { displayedBmp = new byte[0]; }; message.onTimeout = () -> { - handleTransportFailure("shutdown ack timeout"); + if (reconnectOnTimeout) { + handleTransportFailure("shutdown ack timeout"); + } else { + logLine("EvenHub shutdown ack timeout; keeping BLE connected"); + } }; pendingMessages.addFirst(message); logLine("queue shutdown"); @@ -650,6 +733,21 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { G2Event event = null; synchronized (lock) { lastIncomingAtMs = SystemClock.elapsedRealtime(); + if (shutdownRequested + && address.equalsIgnoreCase(rightAddress) + && BleProtocol.isDisplayWakeStateChange(frame)) { + // With no EvenHub page, ring/arm double-taps are handled by the + // stock display lifecycle and surface only as this state ping. + // Translate it back into an input event so TS can wake the shell + // and recreate the page. + event = new G2Event( + "display-wake", + "", + BleProtocol.EVENT_DOUBLE_CLICK, + 0, + 0 + ); + } if (frame.ok && frame.sid == BleProtocol.SID_UI_SETTING) { // Device-initiated settings push. It carries a magic the glasses // chose, so it would otherwise fall through to resolveAckLocked, @@ -664,7 +762,10 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { lastAckAtMs = lastIncomingAtMs; resolveAckLocked(frame.sid, frame.msgSeq, frame.pb); } - if (frame.ok && address.equalsIgnoreCase(rightAddress) && (frame.flag == BleProtocol.FLAG_NOTIFY || frame.flag == BleProtocol.FLAG_NOTIFY_ALT)) { + if (event == null + && frame.ok + && address.equalsIgnoreCase(rightAddress) + && (frame.flag == BleProtocol.FLAG_NOTIFY || frame.flag == BleProtocol.FLAG_NOTIFY_ALT)) { event = G2Event.decode(frame); if (event != null) { // Pure IMU samples arrive continuously; don't let them count @@ -807,6 +908,10 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { synchronized (lock) { sessionReady = true; + // A fresh transport prelude always starts an active EvenHub + // lifecycle, even if the previous connection dropped while + // its page was intentionally suspended. + shutdownRequested = false; fixedLayoutCreated = false; warmedUp = false; clearAllMessagesLocked("session ready"); @@ -1966,6 +2071,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private void resetSessionStateLocked() { sessionReady = false; + shutdownRequested = false; fixedLayoutCreated = false; warmedUp = false; chargingMode = false; diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java index 663062c3..6d3e734e 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java @@ -31,6 +31,7 @@ public class BleProtocol { public static final int SID_APP_LAUNCH = 0x01; public static final int SID_EVENHUB = 0xe0; public static final int SID_UI_SETTING = 0x09; + public static final int SID_STATE_CHANGE = 0x0d; /** G2SettingPackage.commandId for device-initiated pushes (vs. 2 = app read). */ public static final int SETTINGS_CMD_DEVICE_SEND_TO_APP = 3; // UI_FOREGROUND_EVEN_AI_ID: the stock "Even AI" assistant app. It is a @@ -514,6 +515,33 @@ public class BleProtocol { return Arrays.copyOf(pb, pb.length - 2); } + /** + * Display wake notification observed after a ring or right-arm double tap + * while no EvenHub page is running: + * + * sid=0x0d, flag=notify, payload f1=1, f3={f1=1} + * + * Other state-change shapes (wear, charging, head-up, etc.) are deliberately + * excluded. The caller additionally gates this on an intentional EvenHub + * suspension, so normal state traffic cannot become application input. + */ + public static boolean isDisplayWakeStateChange(ParsedFrame frame) { + if (frame == null + || !frame.ok + || frame.sid != SID_STATE_CHANGE + || (frame.flag != FLAG_NOTIFY && frame.flag != FLAG_NOTIFY_ALT)) { + return false; + } + byte[] root = stripTrailingCrc(frame.pb); + if (readVarintFieldValue(root, 1, -1) != 1) { + return false; + } + byte[] state = readFieldBytes(root, 3); + return state != null + && state.length == 2 + && readVarintFieldValue(state, 1, -1) == 1; + } + public static byte[] readFieldBytes(byte[] pb, int fieldNumber) { int offset = 0; while (offset < pb.length) { diff --git a/app/g2/dashboard-controller.ts b/app/g2/dashboard-controller.ts index 4403b173..cfa01137 100644 --- a/app/g2/dashboard-controller.ts +++ b/app/g2/dashboard-controller.ts @@ -79,6 +79,7 @@ import { saveVoiceRecordingsSetting, screenTimeoutSetting, screenTimeoutSettingToMs, + suspendEvenHubWhenScreenOffSetting, systemCardNameSetting, voiceProviderSetting, type ConfigSettingString, @@ -119,6 +120,7 @@ const SHELL_SURFACE_ID = "shell"; const SHELL_REFRESH_INTERVAL_MS = 60_000; const PREVIEW_INTERVAL_MS = 1_000; const SCREEN_TIMEOUT_CHECK_MS = 1_000; +const EVENHUB_SCREEN_OFF_SUSPEND_DELAY_MS = 5_000; const FOREGROUND_NOTIFICATION_MIN_UPDATE_MS = 30_000; const FRAME_TRANSMIT_BACKPRESSURE_TIMEOUT_MS = 6_000; const CONNECTED_PREVIEW_MIN_UPDATE_MS = 1_000; @@ -180,6 +182,8 @@ class DashboardController { private shellRefreshTimer: ReturnType | null = null; private previewTimer: ReturnType | null = null; private screenTimeoutTimer: ReturnType | null = null; + private evenHubSuspendTimer: ReturnType | null = null; + private evenHubSessionSuspended = false; private offState: (() => void) | null = null; private offLog: (() => void) | null = null; private offRing: (() => void) | null = null; @@ -230,16 +234,7 @@ class DashboardController { getScreenTimeoutMs: () => screenTimeoutSettingToMs(screenTimeoutSetting.get()), requestShellRender: () => this.requestShellRender(), onScreenStateChanged: (on) => { - const communicator = this.communicator; - if (!communicator) return; - void (async () => { - // Blanking is a compositor-level flag so worker-window surfaces go - // dark too; retained state survives for instant wake. - await communicator.setScreenBlanked(!on); - await communicator.setG2ScreenOn(on); - })().catch((error) => { - this.appendLog(`screen state change failed: ${this.formatError(error)}`); - }); + this.handleScreenStateChanged(on); if (on) this.requestShellRender(); }, }); @@ -283,9 +278,115 @@ class DashboardController { // Apply a firmware-debug-flags toggle live while connected (Java dedups). this.pushFirmwareDebugFlags(); this.pushBrightness(); + this.syncEvenHubScreenOffSetting(); }); } + private handleScreenStateChanged(on: boolean): void { + const communicator = this.communicator; + if (!communicator) return; + + if (on) { + this.cancelEvenHubSuspendTimer(); + const shouldResumeEvenHub = this.evenHubSessionSuspended; + this.evenHubSessionSuspended = false; + void (async () => { + await communicator.setG2ScreenOn(true); + // Restore the retained frame before allowing Java's session driver to + // recreate the layout, so its first real image is the current screen + // rather than the black sleep frame. + await communicator.setScreenBlanked(false); + if (shouldResumeEvenHub) { + await communicator.resumeEvenHubSession(); + } + })().catch((error) => { + this.appendLog(`screen wake failed: ${this.formatError(error)}`); + }); + return; + } + + // Blanking is a compositor-level flag so worker-window surfaces go dark + // too; retained state survives while the EvenHub page is absent. + void (async () => { + await communicator.setScreenBlanked(true); + await communicator.setG2ScreenOn(false); + })().catch((error) => { + this.appendLog(`screen sleep failed: ${this.formatError(error)}`); + }); + this.scheduleEvenHubSuspend(); + } + + private syncEvenHubScreenOffSetting(): void { + if (suspendEvenHubWhenScreenOffSetting.get() && !shell.isScreenOn()) { + this.scheduleEvenHubSuspend(); + return; + } + + this.cancelEvenHubSuspendTimer(); + if (!this.evenHubSessionSuspended) return; + + // Turning the experiment off restores the legacy all-black page even if + // the screen remains asleep. + const communicator = this.communicator; + this.evenHubSessionSuspended = false; + if (!communicator) return; + void communicator.resumeEvenHubSession().catch((error) => { + this.appendLog(`EvenHub resume failed: ${this.formatError(error)}`); + }); + } + + private scheduleEvenHubSuspend(): void { + this.cancelEvenHubSuspendTimer(); + if ( + !suspendEvenHubWhenScreenOffSetting.get() || + shell.isScreenOn() || + this.phase !== "connected" || + !this.communicator || + this.evenHubSessionSuspended + ) { + return; + } + + const communicator = this.communicator; + this.evenHubSuspendTimer = setTimeout(() => { + this.evenHubSuspendTimer = null; + if ( + !suspendEvenHubWhenScreenOffSetting.get() || + shell.isScreenOn() || + this.phase !== "connected" || + this.communicator !== communicator + ) { + return; + } + + this.evenHubSessionSuspended = true; + void communicator + .suspendEvenHubSession() + .then((suspended) => { + if (suspended) { + this.appendLog("EvenHub session suspended while screen is off"); + return; + } + if (this.communicator !== communicator || shell.isScreenOn()) return; + this.evenHubSessionSuspended = false; + this.scheduleEvenHubSuspend(); + }) + .catch((error) => { + if (this.communicator === communicator) { + this.evenHubSessionSuspended = false; + this.appendLog(`EvenHub suspend failed: ${this.formatError(error)}`); + this.scheduleEvenHubSuspend(); + } + }); + }, EVENHUB_SCREEN_OFF_SUSPEND_DELAY_MS); + } + + private cancelEvenHubSuspendTimer(): void { + if (this.evenHubSuspendTimer === null) return; + clearTimeout(this.evenHubSuspendTimer); + this.evenHubSuspendTimer = null; + } + private pushFirmwareDebugFlags(): void { if (!this.communicator) return; void this.communicator @@ -487,6 +588,9 @@ class DashboardController { void this.communicator?.setG2ScreenOn(false).catch(() => {}); } if (mappedPhase === "connected" && this.phase !== "connected") { + // A transport reconnect starts with a live EvenHub lifecycle again; + // if the shell is asleep, begin a fresh five-second grace period. + this.evenHubSessionSuspended = false; // Push the CFW firmware-debug-flags overlay preference; Java emits the // mode-7 control message once the dashboard container is warmed up. this.pushFirmwareDebugFlags(); @@ -494,6 +598,12 @@ class DashboardController { } this.setPhase(mappedPhase); this.setStatus(state.status); + if (mappedPhase === "connected") { + this.syncEvenHubScreenOffSetting(); + } else if (mappedPhase !== "charging") { + this.cancelEvenHubSuspendTimer(); + this.evenHubSessionSuspended = false; + } }); this.offRing = communicator.onRingEvent((event) => { void this.handleInputEvent(event).catch((error) => { @@ -582,6 +692,7 @@ class DashboardController { await this.configureWindowSurface(window.surfaceId, window.windowId === foregroundWindowId); } await communicator.start(); + this.syncEvenHubScreenOffSetting(); shell.foregroundWindow()?.requestRender(); this.requestShellRender(); // Refresh the top-bar clock and the phone-side preview once a minute, @@ -665,6 +776,7 @@ class DashboardController { const communicator = this.communicator; this.communicator = null; + this.evenHubSessionSuspended = false; try { const shutdownAcked = await communicator?.sendShutdown(0).catch((error) => { @@ -1203,6 +1315,7 @@ class DashboardController { } private clearDashboardTimer(): void { + this.cancelEvenHubSuspendTimer(); if (this.shellRefreshTimer) { clearInterval(this.shellRefreshTimer); this.shellRefreshTimer = null; diff --git a/app/native/faceclaw-communicator.ts b/app/native/faceclaw-communicator.ts index 09c23b28..80641181 100644 --- a/app/native/faceclaw-communicator.ts +++ b/app/native/faceclaw-communicator.ts @@ -88,6 +88,18 @@ export type RawInputEvent = eventSource: number; systemExitReasonCode: number; frameId: number; + } + | { + /** + * Stock display-lifecycle wake observed after a ring or arm double tap + * while Faceclaw's EvenHub page is suspended. + */ + kind: "display-wake"; + containerName: string; + eventType: number; + eventSource: number; + systemExitReasonCode: number; + frameId: number; }; function nonNegativeNumber(value: number): number { @@ -467,6 +479,22 @@ export class FaceclawCommunicatorBridge { return this.enqueueJavaCall(() => Boolean(this.communicator.sendShutdown(exitMode))); } + /** + * End only the EvenHub page/session, leaving both arm BLE connections and + * their async notification subscriptions alive. + */ + async suspendEvenHubSession(): Promise { + return this.enqueueJavaCall(() => Boolean(this.communicator.suspendEvenHubSession())); + } + + /** + * Re-enable the EvenHub page lifecycle. The retained compositor frame is + * sent after the layout and image path have been recreated. + */ + async resumeEvenHubSession(): Promise { + return this.enqueueJavaCall(() => Boolean(this.communicator.resumeEvenHubSession())); + } + /** Play a CFW mode-5 kind-4 tone sequence (complete wire payload). */ async playBuzzerSequence(payload: Uint8Array): Promise { const snapshot = new Uint8Array(payload); diff --git a/app/ui/dashboard-settings.ts b/app/ui/dashboard-settings.ts index b8306c0e..490592b1 100644 --- a/app/ui/dashboard-settings.ts +++ b/app/ui/dashboard-settings.ts @@ -248,6 +248,13 @@ export const firmwareDebugFlagsSetting = new ConfigSettingBoolean({ defaultValue: false, }); +export const suspendEvenHubWhenScreenOffSetting = new ConfigSettingBoolean({ + id: "suspend-evenhub-screen-off", + label: "Suspend EvenHub when screen off", + storageKey: "developer.suspendEvenHubWhenScreenOff", + defaultValue: false, +}); + export type VoiceProvider = "onboard" | "elevenlabs" | "whisper"; const voiceProviderLabels: Record = { diff --git a/app/ui/dashboard/settings-menus.ts b/app/ui/dashboard/settings-menus.ts index b66d0871..162edd46 100644 --- a/app/ui/dashboard/settings-menus.ts +++ b/app/ui/dashboard/settings-menus.ts @@ -11,6 +11,7 @@ import { firmwareDebugFlagsSetting, rawScreenshotsEnabledSetting, saveVoiceRecordingsSetting, + suspendEvenHubWhenScreenOffSetting, terminalAuthTokenSetting, terminalHostSetting, terminalPortSetting, @@ -79,6 +80,7 @@ function settingsSections(): SettingsSection[] { toggleSettingMenuItem(rawScreenshotsEnabledSetting), toggleSettingMenuItem(saveVoiceRecordingsSetting), toggleSettingMenuItem(firmwareDebugFlagsSetting), + toggleSettingMenuItem(suspendEvenHubWhenScreenOffSetting), ], }, { diff --git a/app/ui/layers.ts b/app/ui/layers.ts index c5c2cbaa..6a3e7aac 100644 --- a/app/ui/layers.ts +++ b/app/ui/layers.ts @@ -10,6 +10,11 @@ export type DashboardInputEvent = | { type: "scroll-down" } | { type: "long-press"; source: "ring" | "left-arm" | "right-arm" } | { type: "long-press-release"; source: "ring" | "left-arm" | "right-arm" } + /** + * The stock display lifecycle woke while no EvenHub page was running. This + * is wake-only, unlike a normal double-click (which turns an on screen off). + */ + | { type: "display-wake" } /** * The on-glasses "Hey Even" wakeword fired. Delivered on sid 0x07 by the * stock firmware regardless of CFW; the CFW additionally suppresses the stock diff --git a/app/ui/shell/shell.ts b/app/ui/shell/shell.ts index db4bad6f..f2507d1e 100644 --- a/app/ui/shell/shell.ts +++ b/app/ui/shell/shell.ts @@ -337,6 +337,14 @@ class Shell { } async receiveInput(event: DashboardInputEvent, frameId = 0): Promise { + // The stock lifecycle has already interpreted the physical double tap as + // "wake". Keep that directionality if delivery is delayed or duplicated. + if (event.type === "display-wake") { + this.lastInputAtMs = Date.now(); + const wokeScreen = !this.screenOn && this.wake("sidebar"); + return { shell: wokeScreen, window: false }; + } + // The wakeword is handled before the screen-off short-circuit so its // configured action can work from a dark screen. With the CFW the stock // Even AI app never launches, so the firmware does not power the display @@ -609,6 +617,10 @@ export function rawInputEventToInputEvent(event: RawInputEvent): DashboardInputE if (event.eventType === EvenAIStatus.EVEN_AI_WAKE_UP) { return { type: "wakeword" }; } + } else if (event.kind === "display-wake") { + // Outside an EvenHub page the firmware consumes the physical double tap + // itself and reports only that the stock display lifecycle woke. + return { type: "display-wake" }; } else if (event.kind === "text-click") { if (event.eventType === OsEventTypeList.SCROLL_BOTTOM_EVENT) { return { type: "scroll-down" }; @@ -649,6 +661,8 @@ export function inputEventToString(event: DashboardInputEvent): string { return `Long press from ${event.source}`; case "long-press-release": return `Long press release from ${event.source}`; + case "display-wake": + return `Display wake`; case "wakeword": return `Wakeword`; default: