Add experimental option to end EvenHub session when the screen is off for power saving

This commit is contained in:
James Babcock committed 2026-07-23 18:40:48 -07:00
1 parent 7455775390
commit e5649e9782
8 files changed
+315 -12

No files matched your search

@@ -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;
@@ -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) {
+123 -10
View File
@@ -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<typeof setInterval> | null = null;
private previewTimer: ReturnType<typeof setInterval> | null = null;
private screenTimeoutTimer: ReturnType<typeof setInterval> | null = null;
private evenHubSuspendTimer: ReturnType<typeof setTimeout> | 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;
+28
View File
@@ -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<boolean> {
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<boolean> {
return this.enqueueJavaCall(() => Boolean(this.communicator.resumeEvenHubSession()));
}
/** Play a CFW mode-5 kind-4 tone sequence (complete wire payload). */
async playBuzzerSequence(payload: Uint8Array): Promise<void> {
const snapshot = new Uint8Array(payload);
+7
View File
@@ -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<VoiceProvider, string> = {
+2
View File
@@ -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),
],
},
{
+5
View File
@@ -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
+14
View File
@@ -337,6 +337,14 @@ class Shell {
}
async receiveInput(event: DashboardInputEvent, frameId = 0): Promise<ShellInputOutcome> {
// 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: