Add bluetooth keyboard support

G2 only: You can pair the glasses with a bluetooth keyboard. It will
relay key events, and you can use it to type in some apps and to
navigate the UI.
This commit is contained in:
James Babcock committed 2026-11-15 01:54:54 -08:00
1 parent 9372b2742c
commit fd3c26333f
46 files changed
+3867 -41

No files matched your search

+6
View File
@@ -23,6 +23,12 @@ and Mentra Labs, Inc. (MIT License): https://github.com/tetramo-labs/glassly and
https://github.com/tetramo-labs/glassly-rayneo-cfw. The iO wire codecs in
native/kotlin/shared/.../rayneo/RayNeoIoProtocol.kt follow their protocol work.
Bluetooth keyboard support on the G2 uses the keyboard bridge Tetramo, Inc. wrote
for their Glassly custom firmware (https://github.com/tetramo-labs/g2flash).
Faceclaw's client for it, in app/g2/keyboard/ and app/apps/terminal/terminal-keys.ts,
follows the reference client in that repository and the keyboard handling in the
Glassly app (MIT License): https://github.com/tetramo-labs/glassly.
iPhone notification icons are Pebble's notification and timeline icons, from
https://github.com/pebble-dev/iconography: the original Pebble Technology icons
and Rebble community additions. They are licensed under the Apache License 2.0;
@@ -322,6 +322,13 @@ class FaceclawBleCommunicator(context: Context, rightAddress: String?, leftAddre
fun sendFaceclawMicControl(record: ByteArray?, label: String, rightTemple: Boolean, leftTemple: Boolean): Boolean =
core.sendFaceclawMicControl(record, label, rightTemple, leftTemple)
fun addKeyboardEventListener(listener: FaceclawKeyboardEventListener?) = core.addKeyboardEventListener(listener)
fun removeKeyboardEventListener(listener: FaceclawKeyboardEventListener?) = core.removeKeyboardEventListener(listener)
fun sendFaceclawKeyboardControl(record: ByteArray?, label: String): Boolean =
core.sendFaceclawKeyboardControl(record, label)
fun startG2AudioForwarding(listener: FaceclawAudioPacketListener?): Boolean = core.startG2AudioForwarding(listener)
fun stopG2AudioForwarding() = core.stopG2AudioForwarding()
+3
View File
@@ -187,6 +187,8 @@ export async function launchWorkerAppWindow(
matchExistingBy?: "appId" | "windowId";
/** Deliver watch swipes raw instead of the fallback (see WorkerWindowSpec). */
acceptsDirectional?: boolean;
/** Deliver hardware-keyboard keys as keys (see WorkerWindowSpec). */
acceptsKeys?: boolean;
},
): Promise<void> {
const existing = shell
@@ -207,6 +209,7 @@ export async function launchWorkerAppWindow(
icon: options.icon,
focus: true,
acceptsDirectional: options.acceptsDirectional,
acceptsKeys: options.acceptsKeys,
});
ctx.appendLog(`launched ${options.windowId}`);
}
+1
View File
@@ -312,6 +312,7 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
}
case "navigation-sensors":
case "text-input":
case "key":
case "tool-call":
break;
}
+1
View File
@@ -305,6 +305,7 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
break;
case "navigation-sensors":
case "text-input":
case "key":
case "tool-call":
break;
}
+1
View File
@@ -236,6 +236,7 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
case "navigation-sensors":
case "screen":
case "text-input":
case "key":
case "tool-call":
break;
}
@@ -272,6 +272,7 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
}
case "navigation-sensors":
case "text-input":
case "key":
case "tool-call":
break;
}
+3
View File
@@ -370,6 +370,9 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
frameTimings.logFrame(message.frameId, `input received in ${message.windowId} worker`);
handleInput(window, message.event as InputEvent, message.frameId);
break;
case "key":
// Only windows opened with acceptsKeys are sent keys.
break;
case "text-input":
if (editing) {
// Voice input as an alternative to the phone keyboard.
+1
View File
@@ -433,6 +433,7 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
}
case "navigation-sensors":
case "text-input":
case "key":
case "tool-call":
break;
}
+3
View File
@@ -227,6 +227,9 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
frameTimings.logFrame(message.frameId, `input received in ${message.windowId} worker`);
handleInput(window, message.event as InputEvent, message.frameId);
break;
case "key":
// Only windows opened with acceptsKeys are sent keys.
break;
case "text-input":
if (editingSetting) {
// Voice input as an alternative to the phone keyboard.
+3
View File
@@ -424,6 +424,9 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
frameTimings.logFrame(message.frameId, `input received in ${message.windowId} worker`);
handleInput(window, message.event as InputEvent, message.frameId);
break;
case "key":
// Only windows opened with acceptsKeys are sent keys.
break;
case "text-input":
if (window && window.windowId === message.windowId) handleTextInput(message.text.trim());
break;
+2
View File
@@ -14,6 +14,8 @@ const terminalApp: AppDefinition = {
// Session windows stay independent: launching reopens the hub even
// while terminal sessions are open.
matchExistingBy: "windowId",
// The hub window can show a session too, so it takes keys like one.
acceptsKeys: true,
}),
};
+39
View File
@@ -55,6 +55,8 @@ import {
import * as frameTimings from "../../native/frame-timings";
import { getActiveDisplay } from "../../native/active-display";
import { GESTURE_DOUBLE_CLICK, type InputEvent } from "../../ui/gestures";
import { navigationGestureForKey, type KeyEvent } from "../../g2/keyboard/keys";
import { encodeTerminalKey, terminalScrollbackKey } from "./terminal-keys";
import { G2MirrorClient, type G2MirrorClientOptions, type G2MirrorSession, type G2MirrorState } from "../../native/g2mirror-client";
import { onSettingsStoreChanged } from "../../native/settings-store";
import { clamp } from "../../util/numeric-util";
@@ -435,6 +437,13 @@ global.onmessage = (event: { data: WorkerAppMessage }) => {
}
break;
}
case "key": {
const window = windows.get(message.windowId);
if (!window) break;
window.focused = message.focused;
handleKey(window, message.event as KeyEvent);
break;
}
case "render": {
const window = windows.get(message.windowId);
if (!window) break;
@@ -1260,6 +1269,35 @@ function handleInput(window: TerminalWindow, event: InputEvent, frameId: number)
frameTimings.finishFrame(frameId, "discarded: terminal view ignored input");
}
/**
* A key from a hardware keyboard (the glasses' keyboard bridge). A session
* with nothing over it gets the key as its terminal would, every key
* included: Escape and the arrows belong to the program, so leaving is still
* the ring's double tap. Anywhere else (the hub's lists, an open menu) the
* navigation keys act as the ring gestures they stand for.
*/
function handleKey(window: TerminalWindow, event: KeyEvent): void {
if (window.kind === "view" && !window.menu?.isOpen()) {
activeViewId = window.windowId;
const page = terminalScrollbackKey(event);
if (page !== null) {
handleViewScroll(window, page, 0);
return;
}
const bytes = encodeTerminalKey(event, window.emulator.applicationCursorKeys());
if (bytes === null) return;
// Typing follows the live screen, as in any terminal emulator.
if (window.scrollTop !== null) {
window.scrollTop = null;
scheduleRender(window);
}
window.client.sendInput(bytes);
return;
}
const gesture = navigationGestureForKey(event);
if (gesture) handleInput(window, { type: gesture, source: "ring", timestampMs: event.timestampMs }, 0);
}
/** Top visible absolute line index when following the live bottom. */
function followTop(window: ViewWindow): number {
return window.historyNext + window.emulator.bufferLength() - window.gridRows;
@@ -1800,6 +1838,7 @@ function openViewWindow(control: ControlConnection, socket: string, label: strin
focus: true,
// Default to tall sessions; the app display setting can override this.
heightMode: "max",
acceptsKeys: true,
});
}
+5
View File
@@ -82,4 +82,9 @@ export class TerminalEmulator {
cursorCol(): number {
return this.term.buffer.active.cursorX;
}
/** DECCKM: the session asked for application cursor keys (ESC O A rather than ESC [ A). */
applicationCursorKeys(): boolean {
return this.term.modes.applicationCursorKeysMode;
}
}
+118
View File
@@ -0,0 +1,118 @@
/**
* What a terminal emulator sends for a key from a hardware keyboard, by the
* classic xterm conventions: Ctrl chords become control characters, Alt
* prefixes ESC, and modified cursor and function keys carry the xterm
* modifier parameter (1 + shift + 2*alt + 4*ctrl). Follows the Glassly
* Terminal miniapp's encoder (terminal/keys.ts, MIT).
* No platform imports: this runs under node in the tests.
*/
import type { KeyEvent } from "../../g2/keyboard/keys";
const ESC = "\x1b";
/** Keys xterm encodes as `ESC [ <n> ~`, with a modifier as `;m`. */
const TILDE_KEYS: Record<string, number> = {
Insert: 2,
Delete: 3,
PageUp: 5,
PageDown: 6,
F5: 15,
F6: 17,
F7: 18,
F8: 19,
F9: 20,
F10: 21,
F11: 23,
F12: 24,
};
/** Keys with a single-letter final byte: SS3 in application cursor mode, CSI otherwise. */
const LETTER_KEYS: Record<string, string> = {
ArrowUp: "A",
ArrowDown: "B",
ArrowRight: "C",
ArrowLeft: "D",
Home: "H",
End: "F",
};
/** F1-F4 are always SS3 (`ESC O P`), or CSI with a modifier. */
const SS3_KEYS: Record<string, string> = { F1: "P", F2: "Q", F3: "R", F4: "S" };
/** Ctrl with a punctuation or digit key, per xterm (^[ ^\ ^] ^^ ^_ ^? ^@). */
const CONTROL_PUNCTUATION: Record<string, string> = {
"[": "\x1b",
"\\": "\x1c",
"]": "\x1d",
"^": "\x1e",
"6": "\x1e",
"_": "\x1f",
"-": "\x1f",
"?": "\x7f",
"/": "\x7f",
"8": "\x7f",
"@": "\x00",
"2": "\x00",
};
/**
* The text to write to the terminal for one key event, or null when the key
* sends nothing: releases, bare modifiers, Meta chords, and keys a terminal
* has no bytes for (volume, media). `appCursor` is DECCKM, which the emulator
* tracks from the session's output.
*/
export function encodeTerminalKey(event: KeyEvent, appCursor: boolean): string | null {
if (event.phase !== "down") return null;
const { key, modifiers } = event;
if (modifiers.meta) return null;
const modifierParam = 1 + (modifiers.shift ? 1 : 0) + (modifiers.alt ? 2 : 0) + (modifiers.ctrl ? 4 : 0);
const modified = (prefix: string, final: string): string | null =>
modifierParam > 1 ? `${ESC}[${prefix};${modifierParam}${final}` : null;
switch (key) {
case "Enter":
return modifiers.alt ? `${ESC}\r` : "\r";
case "Escape":
return ESC;
case "Tab":
return modifiers.shift ? `${ESC}[Z` : "\t";
case "Backspace":
if (modifiers.alt) return `${ESC}\x7f`;
return modifiers.ctrl ? "\x08" : "\x7f";
case " ":
return modifiers.ctrl ? "\x00" : modifiers.alt ? `${ESC} ` : " ";
}
const letter = LETTER_KEYS[key];
if (letter) return modified("1", letter) ?? (appCursor ? `${ESC}O${letter}` : `${ESC}[${letter}`);
const tilde = TILDE_KEYS[key];
if (tilde) return modified(String(tilde), "~") ?? `${ESC}[${tilde}~`;
const ss3 = SS3_KEYS[key];
if (ss3) return modified("1", ss3) ?? `${ESC}O${ss3}`;
if (modifiers.ctrl) {
// From the unshifted key: ^A..^Z, then the punctuation set.
const base = key.length === 1 ? key.toLowerCase() : "";
let char: string | undefined;
if (base >= "a" && base <= "z") char = String.fromCharCode(base.charCodeAt(0) - 96);
else char = CONTROL_PUNCTUATION[key];
if (char === undefined) return null;
return modifiers.alt ? `${ESC}${char}` : char;
}
// With Alt held the translator leaves `text` out (it is a chord, not
// typing); a terminal still wants ESC and the character.
const text = event.text ?? (modifiers.alt && key.length === 1 ? key : undefined);
if (text === undefined) return null;
return modifiers.alt ? `${ESC}${text}` : text;
}
/** Shift+PageUp / Shift+PageDown page the emulator's own scrollback, as in xterm. */
export function terminalScrollbackKey(event: KeyEvent): -1 | 1 | null {
if (event.phase !== "down") return null;
const { shift, ctrl, alt, meta } = event.modifiers;
if (!shift || ctrl || alt || meta) return null;
if (event.key === "PageUp") return -1;
if (event.key === "PageDown") return 1;
return null;
}
+61
View File
@@ -22,6 +22,8 @@ import { defaultRingName, setGlassesRingLink } from "../native/ring-status";
import { getBooleanSetting, setBooleanSetting } from "../native/settings-store";
import { grayImageToPreviewSource } from "../native/gray-image-preview";
import { firmwareIncompatibilityMessage, hasCompatibleFirmware } from "./firmware-compat";
import { keyboardService } from "./keyboard/service";
import { navigationGestureForKey, type KeyEvent } from "./keyboard/keys";
import { hasExtractedEvenHubFonts } from "./firmware-builder";
import { isHaltedSessionPhase, resumeAutoReconnect, suppressAutoReconnect } from "./reconnect-policy";
import { WearRemote, type WearRemoteInputKind } from "./wear-remote";
@@ -460,6 +462,7 @@ class DashboardController {
if (on) this.glance.dismiss();
this.handleScreenStateChanged(on);
if (on) this.requestShellRender();
if (on) keyboardService.retryNow();
this.emit();
},
});
@@ -512,6 +515,16 @@ class DashboardController {
assistantAvailable: () => shell.isAssistantAvailable(),
assistant: text => shell.sendToAssistant(text),
});
// A keyboard paired through the glasses (CFW keyboard bridge). Its keys
// go to the focused window when that takes keys, else act as navigation.
keyboardService.setHost({
onKey: (event) => this.handleKeyboardKey(event),
log: (line) => this.appendLog(line),
// A keyboard that is switched off would otherwise keep the glasses'
// radio looking for it around the clock. One still connected when the
// display sleeps stays connected, and its next key wakes the display.
shouldReconnect: () => this.phase === "connected" && shell.isScreenOn(),
});
this.wearRemote = new WearRemote({
apps: launchableApps,
injectInput: (kind) => this.injectSyntheticRingInput(kind, "watch"),
@@ -1766,6 +1779,7 @@ class DashboardController {
this.appendLog(`wake takeover lease sync failed: ${this.formatError(error)}`);
});
this.ensureWearStateTracking();
this.syncKeyboardLink();
}
// The shared session halts on incompatible firmware by itself
// ("incompatible-firmware" phase); this only explains why.
@@ -2625,6 +2639,52 @@ class DashboardController {
}
}
/**
* Tell the keyboard bridge whether the session can host a keyboard: a G2
* on firmware with the bridge, connected and in use. While the glasses
* charge in their case the link stays up but nobody is typing, so the
* firmware is told to let the keyboard go.
*/
private syncKeyboardLink(): void {
const up =
this.phase === "connected" &&
this.customFirmwareConfirmed &&
glassesTypeSetting.get() === "g2";
// Charging, or a disconnect the user asked for: the link is still up, so
// the DISABLE gets out ahead of everything the teardown sends.
if (up) keyboardService.linkReady();
else keyboardService.linkLost(this.phase === "charging" || this.phase === "disconnecting");
}
/**
* A key from the keyboard paired through the glasses. A window that takes
* keys (a terminal session) gets it as a key; everywhere else the few
* navigation keys act as the ring gestures they stand for. A dark display
* takes no typing: the first press only wakes it, as the ring's double tap
* would, and a locked one stays locked.
*/
private handleKeyboardKey(event: KeyEvent): void {
if (this.phase !== "connected") return;
if (this.glassesLocked || !shell.isScreenOn()) {
if (event.phase !== "down" || event.repeat || shell.isScreenOn()) return;
void this.handleInputEvent({
kind: "display-wake",
containerName: "",
eventType: OsEventTypeList.DOUBLE_CLICK_EVENT,
eventSource: EventSourceType.TOUCH_EVENT_FORM_DUMMY_NULL,
systemExitReasonCode: 0,
frameId: 0,
}).catch((error) => this.appendLog(`keyboard wake failed: ${this.formatError(error)}`));
return;
}
if (shell.receiveKeyEvent(event)) return;
const gesture = navigationGestureForKey(event);
if (!gesture) return;
void this.injectSyntheticRingInput(gesture).catch((error) =>
this.appendLog(`keyboard navigation failed: ${this.formatError(error)}`),
);
}
/**
* The Glanceboard event a sleep-time input means, or null when the shell
* should see the input as usual. A display-wake carries the head-tilt
@@ -3097,6 +3157,7 @@ class DashboardController {
private setPhase(phase: ConnectionPhase): void {
if (this.phase === phase) return;
this.phase = phase;
this.syncKeyboardLink();
if (phase !== "connected" && phase !== "charging") {
shell.setBatteryLevels({ ring: null, ringCharging: null });
}
+1 -1
View File
@@ -26,7 +26,7 @@ export type FirmwareInfo = {
};
/** The Faceclaw firmware revision this build of the app needs. */
export const REQUIRED_FACECLAW_FIRMWARE_VERSION = 38;
export const REQUIRED_FACECLAW_FIRMWARE_VERSION = 39;
const FACECLAW_PREFIX = "Faceclaw/";
const LEGACY_PREFIX = "EVENCFW";
+65 -35
View File
@@ -19,12 +19,42 @@ export type FirmwarePatchSet = {
export const CFW_PATCH_SET: FirmwarePatchSet = {
"base": "g2_2.3.0.24.bin",
"baseSha256": "187ccf2bcc5c17a212106e8a376745511e8289c4232b634a7ea94b9bf25a0979",
"outputSha256": "4aac023f49ec6965186d9106e328a516f20a2915ab400d561f662f984023a432",
"outputSha256": "e43be9d04031d261574f96d45cb1e0edd67bfb39f0213f323ff82d8560ae454d",
"patches": [
{
"offset": 1379947,
"old": "0ef009fa",
"new": "0af3b8fb",
"desc": "DM callback allocation: retain keyboard lifecycle on queue exhaustion"
},
{
"offset": 1380027,
"old": "0ef0e1f9",
"new": "0af316fb",
"desc": "ATT callback allocation: expose lost keyboard events as relay gaps"
},
{
"offset": 2649417,
"old": "0a681279",
"new": "d4f167fb",
"desc": "SMP Pairing I/O capability: KeyboardDisplay only for owned keyboard"
},
{
"offset": 2651811,
"old": "0a681279",
"new": "d3f1bafe",
"desc": "SMP Pairing I/O capability: KeyboardDisplay only for owned keyboard"
},
{
"offset": 1385975,
"old": "38b584b0",
"new": "08f3d4be",
"desc": "BLE app dispatcher: isolate explicitly enabled keyboard connection"
},
{
"offset": 1045797,
"old": "38b584b0",
"new": "5cf371bb",
"new": "5df31bb9",
"desc": "ring receiver entry: timestamped unfiltered reports under framebuffer lease"
},
{
@@ -36,49 +66,49 @@ export const CFW_PATCH_SET: FirmwarePatchSet = {
{
"offset": 1437923,
"old": "fef788ff",
"new": "fdf2a2f8",
"new": "fdf24cfe",
"desc": "cfw_ancs_event"
},
{
"offset": 1437951,
"old": "fef7e8fb",
"new": "fcf2d0fd",
"new": "fdf27afb",
"desc": "cfw_ancs_open"
},
{
"offset": 1437969,
"old": "fef7e7fb",
"new": "fcf2ebfd",
"new": "fdf295fb",
"desc": "cfw_ancs_close"
},
{
"offset": 1388387,
"old": "39694d00",
"new": "25597d00",
"new": "79647d00",
"desc": "connection-bound ANCS EUS write callback"
},
{
"offset": 971497,
"old": "fff717f8",
"new": "6ef3a1fc",
"new": "6ff34bfa",
"desc": "bl faceclaw_input_bridge_received (ring relay and ordered private transport before worker pool)"
},
{
"offset": 971845,
"old": "fef769ff",
"new": "6ef3f3fb",
"new": "6ff39df9",
"desc": "bl faceclaw_input_bridge_received (ring relay and ordered private transport before worker pool)"
},
{
"offset": 979579,
"old": "fdf74ef8",
"new": "6cf3d8fc",
"new": "6df382fa",
"desc": "bl faceclaw_input_bridge_received (ring relay and ordered private transport before worker pool)"
},
{
"offset": 1428895,
"old": "f8f76cfd",
"new": "fbf250fe",
"new": "fbf2acfa",
"desc": "bl cfw_receive_packet (private SID-f0 probe before TPL reassembly)"
},
{
@@ -102,7 +132,7 @@ export const CFW_PATCH_SET: FirmwarePatchSet = {
{
"offset": 1058287,
"old": "fff754fb",
"new": "59f342fb",
"new": "5af3ecf8",
"desc": "bl ble_classify_link (only a <= 11.25 ms / latency-0 link is 'already fast')"
},
{
@@ -114,145 +144,145 @@ export const CFW_PATCH_SET: FirmwarePatchSet = {
{
"offset": 1248487,
"old": "d4f712fb",
"new": "29f344fd",
"new": "29f396f8",
"desc": "bl settings_send_wrapper (append caps field 100)"
},
{
"offset": 1246183,
"old": "f5f7e2f8",
"new": "29f3e8fe",
"new": "29f394fa",
"desc": "bl settings_decode_wrapper (Faceclaw lease field 101)"
},
{
"offset": 975219,
"old": "02f083fc",
"new": "6bf34aff",
"new": "6bf3f6fa",
"desc": "bl faceclaw_display_start @ 0x467d68 (fail-open wake takeover)"
},
{
"offset": 975411,
"old": "02f023fc",
"new": "6bf3b8ff",
"new": "6bf364fb",
"desc": "bl faceclaw_display_start_headup @ 0x467e28 (fail-open wake takeover)"
},
{
"offset": 975103,
"old": "07f085fb",
"new": "6df3a6fc",
"new": "6ef350fa",
"desc": "bl headup_gate (idle input gate: tap/long/release -> field-102 events, stock result kept)"
},
{
"offset": 830549,
"old": "19f03efb",
"new": "90f37bfe",
"new": "91f325fc",
"desc": "bl gesture_ring_press_mode (ring touch-down 14, head up 12 / down 15; stock dispatch preserved)"
},
{
"offset": 830795,
"old": "1ff071ff",
"new": "90f334fe",
"new": "91f3defb",
"desc": "bl gesture_press (owned event 9 before stock menu gate)"
},
{
"offset": 830887,
"old": "1ff043ff",
"new": "90f32efe",
"new": "91f3d8fb",
"desc": "bl gesture_short_long (Faceclaw lease gates event 11 vs stock Menu path)"
},
{
"offset": 831763,
"old": "1ff08dfd",
"new": "90f364fc",
"new": "91f30efa",
"desc": "bl gesture_release (owned event 10 before stock menu gate)"
},
{
"offset": 1570209,
"old": "7fb50600",
"new": "dbf2d5b8",
"new": "daf227bc",
"desc": "even_ai_display_ctrl entry -> conditional Faceclaw lease trampoline"
},
{
"offset": 1051545,
"old": "f6f787f9",
"new": "55f3c9f8",
"new": "54f31dfe",
"desc": "bl display_copy_hook @ 0x47a78e (640x480 direct framebuffer)"
},
{
"offset": 1051861,
"old": "f6f7e9f8",
"new": "55f32bf8",
"new": "54f37ffd",
"desc": "bl display_copy_hook @ 0x47a8ca (640x480 direct framebuffer)"
},
{
"offset": 1262237,
"old": "d9f7d0fd",
"new": "25f3bffd",
"new": "25f3c3f9",
"desc": "bl faceclaw_send_wear_event @ 0x4ade92 (outside onboarding)"
},
{
"offset": 1262337,
"old": "d9f79efd",
"new": "25f38dfd",
"new": "25f391f9",
"desc": "bl faceclaw_send_wear_event @ 0x4adef6 (outside onboarding)"
},
{
"offset": 1309405,
"old": "67f02dff",
"new": "19f35bfe",
"new": "19f35ffa",
"desc": "bl compass_decode_capture (sample-matched GAF diagnostics)"
},
{
"offset": 1307865,
"old": "fff7c9fb",
"new": "1af3ddf9",
"new": "19f3e1fd",
"desc": "bl compass_report_event (stock UI + heading with diagnostics over BLE)"
},
{
"offset": 1300937,
"old": "00210170",
"new": "1bf3bbfe",
"new": "1bf3bffa",
"desc": "bl compass_preserve_accuracy (retain magnetic calibration under Faceclaw framebuffer lease)"
},
{
"offset": 4537963,
"old": "",
"new": "b0b581ea00039b0701d0034637e0c2b110f0030315d000f1010ca2f1010e0023cc5c9e45c45403f1010404d0634413f003032346f4d121440319121b102a14d302e00346102a10d3d1f800c0d1f804e0cc688d68103adc609d60c3f804e043f810cb0f2a01f11001eed8042a07d300bf51f8045b043a032a43f8045bf8d8002a08bfb0bd0139013b11f8015f013a03f8015ff9d1b0bd00bf884218bf002a00d1704710b50b1a38bf431a934207d288420ad281ea00039b0726d0034669e0fff79fffbde81040704781ea000300eb020c9b0701eb020e42d15fea8c732bd0a0f1010c00bf8b1813f801ec8418531e04f801ec04d0624412f003021a46f2d101eb030e00eb030c17e0830736d0a2f1010c00f1010e002300bfcc5c9c45c45403f1010404d0734413f003032346f4d1121b2144031922e01346042b0ed3aef10402acf1040152f80449043b032b41f80449f8d802f1040e01f1040c1a4653b1aef10101acf1010300bf11f80149013a03f80149f9d1bde8104070470346042a06d351f8044b043a032a43f8044bf8d8002af0d00139013b00bf11f8014f013a03f8014ff9d1e6e700bf80b5002a18bf10f0030301d186460ce000f1010c864600bf013a0ef8011b04d01cf003030cf1010cf6d1102a11d35ffa81fc4ff001330cfb03fc00bf103acef80cc0cef808c0cef804c04ef810cb0f2af4d8042a0bd35ffa81fc4ff001330cfb03fc00bf043a032a4ef804cbfad8002a08bf80bdaef10103013a03f8011ffbd180bd00bf2de9f04fc7b04ff29c5bc2f2290b4ff6ff754ff47d7400274ff0010847f67f7a7f261191cde90f3007e000bf48f2a351c0f24501bff32f8f8847dbf80090bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0bd101684ef66c62ccf2ff02914204d14068b0f57d7f00f096804ff47d7006f004fd002800f0cb814ff60c41cff6ff7100bf42182e3182f8f47382f8f57382f8f67382f8f77382f8f87382f8f97382f8fa7382f8fb7382f8fc7382f8fd7382f8fe7382f8ff7382f8007482f8017482f8027482f8037482f8047482f8057482f8067482f8077482f8087482f8097482f80a7482f80b7482f80c7482f80d7482f80e7482f80f7482f8107482f8117482f8127482f8137482f8147482f8157482f8167482f8177482f8187482f8197482f81a7482f81b7482f81c7482f81d7482f81e7482f81f7482f8207482f82174a0d14ef66c61ccf2ff010160446080f80e80a0f8c4a180f8c361058445848584c584058545858585c585058645868586c586058745878587c5875be8001f49457ff452afbff35f8f4be8000121b15be8001f4945f8d047e74ff47d7800274ff0010a47f67f797f2607e000bf48f2a351c0f24501bff32f8f8847dbf80040bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0bd101684ef66c62ccf2ff02914204d14168b1f57d7f00f098804ff47d7006f042fc002800f009814ff60c41cff6ff7100bf42182e3182f8f47382f8f57382f8f67382f8f77382f8f87382f8f97382f8fa7382f8fb7382f8fc7382f8fd7382f8fe7382f8ff7382f8007482f8017482f8027482f8037482f8047482f8057482f8067482f8077482f8087482f8097482f80a7482f80b7482f80c7482f80d7482f80e7482f80f7482f8107482f8117482f8127482f8137482f8147482f8157482f8167482f8177482f8187482f8197482f81a7482f81b7482f81c7482f81d7482f81e7482f81f7482f8207482f82174a0d14ef66c61ccf2ff010160c0f8048080f80ea0a0f8c49180f8c361058445848584c584058545858585c585058645868586c586058745878587c5875be8001fa1427ff451afbff35f8f00bf4be8000121b15be8001fa142f8d045e7d0f8948242f6f76ac0f2440ab8f1000fbff35f8f4ad00af19a0240464ff0ff314ff0ff379047002840f090811198002861d010980778a7f1170002285bd811980c2840f07d81109c6078a178084300f07781e0780138022800f27281a279e379667a42ea0322237a207942ea034242ea0663a27ae67a6179192f42ea062200f0de81172f40f0f481002a40f05981fe2800f0b086812800f0a386002840f0b68651ea030040f04c8100f000bf04460020d047e8b104f5257151e8008fb8f1000f0cd1bff35f8f00bf41e80002002a00f0e58051e8008fb8f1000ff5d00021bff32f8f0029bff35f8f00f0d480804692e74ff0ff372ae147f6df40c0f24f00cdf83880804700274ff47d784ff0010947f67f744ff07f0a1397adf8507007e000bf48f2a351c0f24501bff32f8f8847dbf80060bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0bd101684ef66c62ccf2ff02914204d14168b1f57d7f00f09f804ff47d7006f0f8fa002800f097804ff60c41cff6ff7100bf42182e3182f8f47382f8f57382f8f67382f8f77382f8f87382f8f97382f8fa7382f8fb7382f8fc7382f8fd7382f8fe7382f8ff7382f8007482f8017482f8027482f8037482f8047482f8057482f8067482f8077482f8087482f8097482f80a7482f80b7482f80c7482f80d7482f80e7482f80f7482f8107482f8117482f8127482f8137482f8147482f8157482f8167482f8177482f8187482f8197482f81a7482f81b7482f81c7482f81d7482f81e7482f81f7482f8207482f82174a0d14ef66c61ccf2ff010160c0f8048080f80e90a0f8c44180f8c3a1058445848584c584058545858585c585058645868586c586058745878587c5875be8001fb1427ff451afbff35f8f00bf4be8000159b15be8001fb142f8d045e70af5a9718847bce6012120e70020109f42f6f76addf83880c0f2440a9fb1119989b1397801f07f02b2f10b0418bf0124b2f11c0618bf01268a2924dc0b2926d01c2924d03ce00f9012a803f045ff4ff0ff3701249df85100002812a818bf4ff0ff3704f05ff8054644b99df8500028b94af21f30c0f247004c3080470f98002818bf056114e09c2901d08b2918d168b14af21f31c0f247010746884797f8681121b997f824133846109f49b14ff0ff370af5807140468847384647b0bde8f08f0f9012a8344003f007ff387800f07f061e2e05d11199384607f094fe0746b9e71d2e00f07e0018bf1a2819d1dbf800100322cff680720a40b2f1005fbff35f8f12d10a684ef66c63ccf2ff039a420bd14a68b2f57d7f04bf002281f8a12303e0a6f115010129e1d90f2e2cdd142e40f31082152e00f05d83162e00f069831f2e40f02c841198012840f0fc8438781f2840f0f88445f64d55c0f24605a847012841f0828140f24c71c0f2010105f5e2777944e02029220023b8470746002818bf4ff0ff3766e7092e00f3fe80052e00f03e82072e40f0028400274ff0010947f67f764ff07f080d943ae000294ff0ff3708bf002b7ff47caf1328bff479af102a4ff0000138bf01211228b2fa82f218bf510901297ff46caf0Line truncated
"new": "b0b581ea00039b0701d0034637e0c2b110f0030315d000f1010ca2f1010e0023cc5c9e45c45403f1010404d0634413f003032346f4d121440319121b102a14d302e00346102a10d3d1f800c0d1f804e0cc688d68103adc609d60c3f804e043f810cb0f2a01f11001eed8042a07d300bf51f8045b043a032a43f8045bf8d8002a08bfb0bd0139013b11f8015f013a03f8015ff9d1b0bd00bf884218bf002a00d1704710b50b1a38bf431a934207d288420ad281ea00039b0726d0034669e0fff79fffbde81040704781ea000300eb020c9b0701eb020e42d15fea8c732bd0a0f1010c00bf8b1813f801ec8418531e04f801ec04d0624412f003021a46f2d101eb030e00eb030c17e0830736d0a2f1010c00f1010e002300bfcc5c9c45c45403f1010404d0734413f003032346f4d1121b2144031922e01346042b0ed3aef10402acf1040152f80449043b032b41f80449f8d802f1040e01f1040c1a4653b1aef10101acf1010300bf11f80149013a03f80149f9d1bde8104070470346042a06d351f8044b043a032a43f8044bf8d8002af0d00139013b00bf11f8014f013a03f8014ff9d1e6e700bf80b5002a18bf10f0030301d186460ce000f1010c864600bf013a0ef8011b04d01cf003030cf1010cf6d1102a11d35ffa81fc4ff001330cfb03fc00bf103acef80cc0cef808c0cef804c04ef810cb0f2af4d8042a0bd35ffa81fc4ff001330cfb03fc00bf043a032a4ef804cbfad8002a08bf80bdaef10103013a03f8011ffbd180bd00bf2de9f04fc7b04ff29c5bc2f2290b4ff6ff754ff47e740027012647f67f784ff07f0a1191cde90f3007e000bf48f2a351c0f24501bff32f8f8847dbf80090bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0ad101684ef66c62ccf2ff02914203d14068b0f57e7f3ed04ff47e7006f017fa002800f01b816ff0070142180831b1f57c7f177257729772d772177357739773d773f2d14ef66c61ccf2ff01016044608673a0f8c48180f8c3a1058445848584c584058545858585c585058645868586c586058745878587c5875be8001f4945a9d1bff35f8f4be8000121b15be8001f4945f8d09fe74ff47e7800264ff0010a47f67f797f2707e000bf48f2a351c0f24501bff32f8f8847dbf80040bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0ad101684ef66c62ccf2ff02914203d14168b1f57e7f40d04ff47e7006f0adf9002800f0b1806ff0070142180831b1f57c7f167256729672d672167356739673d673f2d14ef66c61ccf2ff010160c0f8048080f80ea0a0f8c49180f8c371058445848584c584058545858585c585058645868586c586058745878587c5875be8001fa142a7d1bff35f8f4be8000121b15be8001fa142f8d09de7d0f8948242f6f76ac0f2440ab8f1000fbff35f8f4ad00af19a0240464ff0ff314ff0ff379047002840f036811198002860d010980778a7f1170002285ad811980c2840f02381109c6078a178084300f01d81e0780138022800f21881a279e379667a42ea0322237a207942ea034242ea0663a27ae67a6179192f42ea062200f08481172f40f09a81002a40f0ff80fe2800f0b285812800f0a585002840f0b88551ea030040f0f28000f002be04460020d047e0b104f5257151e8008fb8f1000f0cd1bff35f8f00bf41e80002002a00f08b8051e8008fb8f1000ff5d00021bff32f8f0029bff35f8f7ad0804693e74ff0ff37d1e047f6df40c0f24f00cdf83880804700274ff47e784ff0010947f67f764ff07f0a1397adf8507006e048f2a351c0f24501bff32f8f8847dbf80040bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0ad101684ef66c62ccf2ff02914203d14168b1f57e7f47d04ff47e7006f0bdf8002840d06ff0070100bf42180831b1f57c7f177257729772d772177357739773d773f2d14ef66c61ccf2ff010160c0f8048080f80e90a0f8c46180f8c3a1058445848584c584058545858585c585058645868586c586058745878587c5875be8001fa142a7d1bff35f8f4be8000159b15be8001fa142f8d09de70af5a971884716e701217ae70020109f42f6f76addf83880c0f2440a9fb1119989b1397801f07f02b2f10b0418bf0124b2f11c0618bf01268a2924dc0b2926d01c2924d03ce00f9012a803f055fd4ff0ff3701269df85100002812a818bf4ff0ff3703f019fe054646b99df8500028b94af21f30c0f247004c3080470f98002818bf056114e09c2901d08b2918d168b14af21f31c0f247010746884797f8681121b997f824133846109f49b14ff0ff370af5807140468847384647b0bde8f08f0f9012a8264003f017fd387800f07f041e2c05d11199384608f048fd0746b9e71d2c00f07e0018bf1a2819d1dbf800100322cff680720a40b2f1005fbff35f8f12d10a684ef66c63ccf2ff039a420bd14a68b2f57e7f04bf002281f8a12303e0a4f115010129e1d90f2c2cdd142c40f3bb81152c00f0ba82162c00f0c4821f2c40f088831198012840f0588438781f2840f0548445f64d54c0f24604a047012841f0388041f21051c0f2010104f5e2777944e02029220023b8470746002818bf4ff0ff3766e7092c00f3a980052c00f0f081072c40f05e830d9600264ff0010947f67f744ff07f083ae000294ff0ff3708bf002b7ff47caf1328bff479af102a4ff0000138bf01211228b2fa82f218bf510901297ff46caf00f07abc182f4ff0ff3708bf00297ff463af002b7ff460af352800f36483002800f05284012800f05e84312840f05084082abff451af00f05fbc48f2a351c0f24501bff32f8f8847dbf80070bff35f8fdbf800000321cff680710140b1f1005fbff35f8f0bd101684ef66c62ccf2ff02914204d14168b1f57e7f00f060854ff47e7005f051ff002800f058856ff0070142180831b1f57c7f167256729672d672167356739673d673f2d14ef66c61ccf2ff0101604ff47e71416080f80e90a0f8c44180f8c381058445848584c584058545858585c585058645868586c586058745878587c5875be8001fb942a5d1bff35f8f4be80001002900f021855be8001fb942f6d099e70a2c00f0bc810b2c40f0b582dbf800500320cff680702840b0f1005fbff35f8f40f0698728684ef66c61ccf2ff01884240f0618768680027b0f57e7f7ff49baed5f8900342f68d49c0f244090028a5f8a07318bfc8470021a5f8d013c5f8cc13c5f86c1185f86a1185f86811d5f87001c5f8641185f86911c5f87011c5f82013a5f88c1320b148f2a351c0f245018847d5f89802002818bf03f099fd0024c5f89842d5f8880320b148f2a351c0f245018847c5f88843a5f88c43686ca5f8484040b1c847686c09f166018847002804bf002068644bf63940c0f251008047dbf800400320cff680702040b0f1005fbff35f8f48d120684ef66c61ccf2ff01884241d16068b0f57e7f3dd194f87b014Line truncated
"desc": "append injected blobs to main-app payload"
},
{
"offset": 779123,
"old": "805a3900",
"new": "68703a00",
"new": "187c3a00",
"desc": "main-app subheader payload size (ps)"
},
{
"offset": 152,
"old": "005b3900",
"new": "e8703a00",
"new": "987c3a00",
"desc": "main-app TOC entry size (ps + 128)"
},
{
"offset": 779243,
"old": "805a3904",
"new": "68703a04",
"new": "187c3a04",
"desc": "main-app preamble length (low 24 bits)"
},
{
"offset": 779247,
"old": "effdbcea",
"new": "0b0c48b0",
"new": "ed6f6deb",
"desc": "[5] ota/s200_firmware_ota.bin preamble crc32"
},
{
"offset": 156,
"old": "c0c6322a",
"new": "52937d21",
"new": "7141aa39",
"desc": "[5] ota/s200_firmware_ota.bin component crc32c (TOC)"
},
{
"offset": 779127,
"old": "c0c6322a",
"new": "52937d21",
"new": "7141aa39",
"desc": "[5] ota/s200_firmware_ota.bin component crc32c (subheader)"
}
]
+559
View File
@@ -0,0 +1,559 @@
/**
* The phone side of the CFW keyboard bridge for one glasses session: the
* client, the remembered keyboard, reconnecting it, and what the UI shows.
* The session hands it field-131 records and a way to send controls; the
* rest stays in here. Modelled on the Glassly app's G2KeyboardBridge (MIT).
*
* The firmware keeps nothing across a reboot (it comes back with the bridge
* off), and holds the keyboard's connection only while told to. So the
* remembered keyboard is brought back whenever the glasses link comes up and
* whenever the keyboard drops, backing off while it stays away. The
* discovered handle mapping is good for one connection and is never stored.
* No platform imports: this runs under node in the tests.
*/
import { KeyboardClient, KeyboardClientError, type KeyboardStatus } from "./client";
import type { HidKeyEvent } from "./hid";
import {
KeyboardDm,
KeyboardError,
mergeKeyboardAdverts,
parseKeyboardAddress,
type KeyboardAdvert,
} from "./protocol";
export type SavedKeyboard = { address: string; addressType: number; name: string };
export type KeyboardBridgeState =
/** No glasses link that can host a keyboard. */
| "unavailable"
| "idle"
| "scanning"
| "connecting"
| "pairing"
| "configuring"
| "connected"
| "error";
/** A pairing step waiting on the user. */
export type KeyboardPairingPrompt =
/** Type this on the keyboard, then Enter. */
| { kind: "display"; pin: number }
/** Confirm both sides show this value (answerCompare). */
| { kind: "compare"; value: number }
/** The keyboard shows a code to enter here (answerPasskey). */
| { kind: "entry" };
export type KeyboardBridgeSnapshot = {
state: KeyboardBridgeState;
saved: SavedKeyboard | null;
/** Name of the keyboard being connected or in use. */
activeName: string;
error: string;
pairing: KeyboardPairingPrompt | null;
/** Advertisers from the last scan, HID devices first, strongest first. */
scanResults: KeyboardAdvert[];
/** A user-started scan or connect is running. */
busy: boolean;
/** The remembered keyboard is away and the bridge keeps trying to bring it back. */
waiting: boolean;
};
export type KeyboardBridgeHost = {
/** Queue a control record on the live session; false when there is none. */
send(record: Uint8Array): boolean;
loadSaved(): SavedKeyboard | null;
storeSaved(saved: SavedKeyboard | null): void;
/** Key transitions from the keyboard (including forced releases). */
onKeys(events: HidKeyEvent[]): void;
/** The keyboard stopped being usable; drop held-key state without releases. */
onKeyboardGone(): void;
/** Something in snapshot() changed. */
onChanged(): void;
/**
* A line for the log. `routine` marks the ones that repeat for as long as
* a remembered keyboard stays away, which only a verbose log wants.
*/
log(line: string, routine?: boolean): void;
/** A fresh six-digit pairing passkey from a good random source. */
randomPasskey?(): number;
/**
* Whether looking for an absent keyboard is worthwhile now. Each attempt
* has the glasses' radio listening for the keyboard for up to half a
* minute, so the owner limits it to when the glasses are in use, and calls
* retryNow() when that starts. Default: always.
*/
shouldReconnect?(): boolean;
};
/** Delay before each automatic attempt after a failure; the last one repeats. */
const RECONNECT_BACKOFF_MS = [2_000, 5_000, 10_000, 20_000, 30_000];
/** After the glasses link comes up, before the first attempt. */
const RESUME_DELAY_MS = 1_000;
/** After the keyboard drops (it may just be going to sleep). */
const DROP_RETRY_DELAY_MS = 2_000;
const RELEASE_POLLS = 20;
const RELEASE_POLL_MS = 150;
export class KeyboardBridge {
private client: KeyboardClient | null = null;
private available = false;
private state: KeyboardBridgeState = "unavailable";
private saved: SavedKeyboard | null;
private activeName = "";
private error = "";
private pairing: KeyboardPairingPrompt | null = null;
private scanResults: KeyboardAdvert[] = [];
/** A user-started scan/connect holds the bridge. */
private busy = false;
/** The keyboard is connected, encrypted and subscribed. */
private ready = false;
private userDisconnected = false;
/** The keyboard was let go while the glasses were out of reach; tell the firmware when they are back. */
private releaseOnLink = false;
private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
private reconnectAttempt = 0;
/** Bumped whenever the client is replaced; work started for an older one stops quietly. */
private generation = 0;
constructor(private readonly host: KeyboardBridgeHost) {
this.saved = host.loadSaved();
}
snapshot(): KeyboardBridgeSnapshot {
return {
state: this.state,
saved: this.saved,
activeName: this.activeName,
error: this.error,
pairing: this.pairing,
scanResults: sortAdverts(this.scanResults),
busy: this.busy,
waiting: this.available && !!this.saved && !this.ready && !this.userDisconnected && !this.busy,
};
}
/** True while key events can arrive. */
isConnected(): boolean {
return this.ready;
}
// ---------- Link lifecycle (driven by the session owner) ----------
/** The glasses link is up on firmware with the bridge: bring the remembered keyboard back. */
linkReady(): void {
if (this.available) return;
this.available = true;
this.userDisconnected = false;
this.reconnectAttempt = 0;
this.error = "";
const client = this.replaceClient();
this.setState("idle");
if (this.saved && !this.releaseOnLink) {
this.scheduleReconnect(RESUME_DELAY_MS);
} else if (this.releaseOnLink && client) {
this.userDisconnected = !!this.saved;
client.query().then((status) => {
if (status.enabled || status.conn) return client.disable();
}).catch(() => {});
}
this.releaseOnLink = false;
}
/** The glasses link is gone. Only the remembered keyboard survives. */
linkLost(): void {
if (!this.available && !this.client) return;
this.available = false;
this.cancelReconnect();
this.generation++;
this.client?.close();
this.client = null;
this.busy = false;
this.pairing = null;
this.error = "";
this.dropKeyboard();
this.setState("unavailable");
}
/**
* The app is about to close the glasses link on purpose: tell the firmware
* to let the keyboard go, so it isn't left attached to glasses nobody is
* listening to. Best effort; nothing waits for the answer.
*/
linkClosing(): void {
const client = this.client;
if (!client || !this.available || !client.status.enabled) return;
client.disable().catch(() => {});
}
/** One field-131 payload from the session. */
accept(payload: Uint8Array): void {
this.client?.accept(payload);
}
/**
* The keyboard may be reachable now, or is wanted now (the display woke):
* if it is away and the bridge is waiting out a backoff, try at once.
*/
retryNow(): void {
if (!this.available || !this.saved || this.ready || this.userDisconnected || this.busy) return;
// No timer means an attempt is already in flight.
if (this.reconnectTimer === null) return;
this.reconnectAttempt = 0;
this.scheduleReconnect(0);
}
// ---------- Commands (the settings UI) ----------
/** Scan for about five seconds; results accumulate in the snapshot as they arrive. */
async scan(): Promise<KeyboardAdvert[]> {
const client = this.beginUserOperation();
const generation = this.generation;
this.scanResults = [];
this.error = "";
this.setState("scanning");
try {
await this.releaseLink(client);
await client.enable();
await client.scan();
if (generation === this.generation) this.setState("idle");
} catch (e) {
if (generation === this.generation) this.fail(e);
throw friendly(e);
} finally {
if (generation === this.generation) this.endUserOperation();
}
return sortAdverts(this.scanResults);
}
/** Connect, pair and subscribe a keyboard, then remember it. */
async connect(keyboard: SavedKeyboard): Promise<void> {
if (!parseKeyboardAddress(keyboard.address) || keyboard.addressType < 0 || keyboard.addressType > 3) {
throw new KeyboardClientError("Invalid keyboard address");
}
const client = this.beginUserOperation();
const generation = this.generation;
this.userDisconnected = false;
try {
await this.connectWith(client, generation, keyboard, false);
} finally {
if (generation === this.generation) this.endUserOperation();
}
}
/** Try the remembered keyboard again now. */
async reconnect(): Promise<void> {
if (!this.saved) throw new KeyboardClientError("No remembered keyboard");
await this.connect(this.saved);
}
/** Drop the keyboard but keep it remembered. No automatic reconnect until the next explicit connect or glasses session. */
async disconnect(): Promise<void> {
this.userDisconnected = true;
this.cancelReconnect();
const client = this.replaceClient();
// A scan or connect this interrupts no longer owns the bridge.
this.busy = false;
this.dropKeyboard();
this.pairing = null;
this.error = "";
if (!client) {
this.releaseOnLink = true;
this.setState("unavailable");
return;
}
this.setState("idle");
try {
await client.query();
await client.disable();
} catch (e) {
this.host.log(`keyboard disconnect: ${messageOf(e)}`);
}
}
/** Forget the remembered keyboard. The glasses keep their bond with it. */
async forget(): Promise<void> {
this.saved = null;
this.host.storeSaved(null);
await this.disconnect();
this.scanResults = [];
this.activeName = "";
this.host.onChanged();
}
/** Answer a "compare" pairing prompt. */
async answerCompare(accept: boolean): Promise<void> {
if (!this.client || this.pairing?.kind !== "compare") throw new KeyboardClientError("No pairing comparison is pending");
this.pairing = null;
this.host.onChanged();
await this.client.confirm(accept);
}
/** Answer an "entry" pairing prompt with the code the keyboard shows. */
async answerPasskey(pin: number): Promise<void> {
if (!this.client || this.pairing?.kind !== "entry") throw new KeyboardClientError("No pairing code is pending");
this.pairing = null;
this.host.onChanged();
await this.client.authenticate(pin);
}
// ---------- Internals ----------
private beginUserOperation(): KeyboardClient {
if (!this.available) throw new KeyboardClientError("Connect to G2 glasses running Faceclaw firmware first");
if (this.busy) throw new KeyboardClientError("Another keyboard operation is in progress");
// An automatic attempt may be mid-flight (a sleeping keyboard holds one
// for up to 30 s): a fresh client fails it at once and takes over.
this.cancelReconnect();
const client = this.replaceClient()!;
this.dropKeyboard();
this.pairing = null;
this.busy = true;
return client;
}
private endUserOperation(): void {
this.busy = false;
this.host.onChanged();
}
/** Close the current client and, while the link is up, start a fresh one. */
private replaceClient(): KeyboardClient | null {
this.generation++;
this.client?.close();
this.client = null;
if (!this.available) return null;
const generation = this.generation;
const live = () => generation === this.generation;
const client = new KeyboardClient(
(record) => live() && this.host.send(record),
{
keys: (events) => { if (live() && this.ready) this.host.onKeys(events); },
advert: (advert) => { if (live()) this.addAdvert(advert); },
status: (status) => { if (live()) this.onStatus(status); },
dm: (event, status) => { if (live()) this.onDm(event, status); },
passkeyDisplay: (pin) => { if (live()) this.prompt({ kind: "display", pin }); },
passkeyRequest: () => { if (live()) this.prompt({ kind: "entry" }); },
compareRequest: (value) => { if (live()) this.prompt({ kind: "compare", value }); },
servicesChanged: () => { if (live()) this.onServicesChanged(); },
error: (message) => { if (live()) this.host.log(`keyboard: ${message}`); },
log: (line) => { if (live()) this.host.log(`keyboard setup: ${line}`); },
},
{ randomPasskey: this.host.randomPasskey ? () => this.host.randomPasskey!() : undefined },
);
this.client = client;
return client;
}
private async connectWith(
client: KeyboardClient,
generation: number,
keyboard: SavedKeyboard,
resume: boolean,
): Promise<void> {
const live = () => generation === this.generation;
this.error = "";
this.activeName = keyboard.name;
this.setState("connecting");
try {
const status = await client.query();
if (resume && status.enabled && status.connected && status.encrypted) {
// The glasses kept the keyboard through a phone-side drop (or an app
// restart): only the handle mapping is missing.
this.host.log("keyboard still connected to the glasses; rediscovering");
} else {
await this.releaseLink(client);
await client.enable();
await client.connect(keyboard.addressType, parseKeyboardAddress(keyboard.address)!);
}
if (!live()) return;
this.pairing = null;
this.setState("configuring");
const config = await client.configure();
if (!live()) return;
this.ready = true;
this.reconnectAttempt = 0;
// The list was for choosing; it is stale from here on.
this.scanResults = [];
if (!sameKeyboard(this.saved, keyboard)) {
this.saved = { ...keyboard };
this.host.storeSaved(this.saved);
}
this.host.log(
`keyboard ready: ${keyboard.name || keyboard.address}, ${config.watched.length} of ` +
`${config.reports.filter((r) => r.type === 1).length} input reports subscribed, epoch ${config.epoch}`);
this.setState("connected");
} catch (e) {
if (!live()) return;
this.ready = false;
this.pairing = null;
if (resume) {
// An automatic attempt: a keyboard that is asleep or out of range is
// the ordinary case, not an error to put in front of the user.
this.host.log(`keyboard reconnect: ${messageOf(friendly(e))}`, true);
this.setState("idle");
} else {
this.fail(e);
}
throw friendly(e);
}
}
/**
* The firmware refuses SCAN and CONNECT while it still owns a keyboard
* slot, and an interrupted connect keeps initiating until the close lands.
* DISABLE is epoch-checked and a fresh client hasn't seen the epoch yet,
* so QUERY first (it isn't, and its answer carries the epoch), then wait
* for the slot to clear.
*/
private async releaseLink(client: KeyboardClient): Promise<void> {
const status = await client.query();
if (!status.enabled && status.conn === 0) return;
await client.disable();
for (let i = 0; i < RELEASE_POLLS; i++) {
if ((await client.query()).conn === 0) return;
await delay(RELEASE_POLL_MS);
}
throw new KeyboardClientError("The glasses are still closing the previous keyboard link; try again in a moment");
}
private cancelReconnect(): void {
if (this.reconnectTimer !== null) clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
}
private scheduleReconnect(delayMs: number): void {
this.cancelReconnect();
this.reconnectTimer = setTimeout(() => {
this.reconnectTimer = null;
void this.attemptReconnect();
}, delayMs);
}
private async attemptReconnect(): Promise<void> {
const saved = this.saved;
const client = this.client;
if (!this.available || !client || !saved || this.userDisconnected || this.ready || this.busy) return;
if (this.host.shouldReconnect && !this.host.shouldReconnect()) {
this.parkFirmware(client);
this.scheduleReconnect(RECONNECT_BACKOFF_MS[RECONNECT_BACKOFF_MS.length - 1]!);
return;
}
const generation = this.generation;
try {
await this.connectWith(client, generation, saved, true);
} catch {
if (generation !== this.generation || !this.available || this.userDisconnected) return;
// Keyboards sleep, and the ring's own scan can hold the controller
// (BUSY): keep trying, less often, while the glasses stay up.
const backoff = RECONNECT_BACKOFF_MS[Math.min(this.reconnectAttempt, RECONNECT_BACKOFF_MS.length - 1)]!;
this.reconnectAttempt++;
this.scheduleReconnect(backoff);
}
}
/**
* While it is enabled the firmware bridge runs a 20 ms timer and reports
* its status every second, keyboard or no keyboard. When nothing will be
* tried for a while, switch it off; the next attempt enables it again.
*/
private parkFirmware(client: KeyboardClient): void {
if (!client.status.enabled) return;
client.disable().catch(() => {});
}
private onStatus(status: KeyboardStatus): void {
if (this.ready && (!status.connected || !status.encrypted)) this.keyboardDropped("status");
else if (this.state === "connecting" && status.connected && !status.encrypted) this.setState("pairing");
}
private onDm(event: number, status: number): void {
if (event === KeyboardDm.connClose || event === KeyboardDm.pairFailed || event === KeyboardDm.encryptFailed) {
this.host.log(`keyboard DM event 0x${event.toString(16)} status ${status}`);
if (this.ready) this.keyboardDropped("dm");
}
}
private onServicesChanged(): void {
this.host.log("keyboard services changed; rediscovering");
this.dropKeyboard();
this.setState("idle");
if (this.saved && !this.userDisconnected && !this.busy) this.scheduleReconnect(0);
}
private keyboardDropped(reason: string): void {
this.host.log(`keyboard disconnected (${reason})`);
this.dropKeyboard();
this.setState("idle");
if (this.saved && !this.userDisconnected && !this.busy) this.scheduleReconnect(DROP_RETRY_DELAY_MS);
}
/** The keyboard is no longer usable: tell the host once. */
private dropKeyboard(): void {
if (!this.ready) return;
this.ready = false;
this.host.onKeyboardGone();
}
private addAdvert(advert: KeyboardAdvert): void {
const index = this.scanResults.findIndex(
(a) => a.address === advert.address && a.addressType === advert.addressType);
if (index < 0) {
this.scanResults.push(advert);
} else {
const merged = mergeKeyboardAdverts(this.scanResults[index]!, advert);
const old = this.scanResults[index]!;
if (merged.name === old.name && merged.hid === old.hid && merged.rssi === old.rssi) return;
this.scanResults[index] = merged;
}
this.host.onChanged();
}
private prompt(pairing: KeyboardPairingPrompt): void {
this.pairing = pairing;
this.setState("pairing");
}
private setState(next: KeyboardBridgeState): void {
this.state = next;
if (next !== "pairing" && next !== "connecting") this.pairing = null;
this.host.onChanged();
}
private fail(error: unknown): void {
this.error = messageOf(friendly(error));
this.host.log(`keyboard error: ${this.error}`);
this.setState("error");
}
}
function sameKeyboard(a: SavedKeyboard | null, b: SavedKeyboard): boolean {
return !!a && a.address === b.address && a.addressType === b.addressType && a.name === b.name;
}
function sortAdverts(adverts: readonly KeyboardAdvert[]): KeyboardAdvert[] {
return [...adverts].sort((a, b) => Number(b.hid) - Number(a.hid) || b.rssi - a.rssi);
}
/**
* Firmware BUSY nearly always means the ring's own scan or reconnect holds
* the radio; say that rather than the raw control error.
*/
function friendly(error: unknown): Error {
if (error instanceof KeyboardClientError && error.code === KeyboardError.busy) {
return new KeyboardClientError(
"The glasses' radio is busy (usually the ring reconnecting). Wait a few seconds and try again.", error.code);
}
if (error instanceof KeyboardClientError && error.code === KeyboardError.noSpace) {
return new KeyboardClientError(
"The glasses have no room for another connection or pairing.", error.code);
}
return error instanceof Error ? error : new Error(String(error));
}
function messageOf(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
function delay(ms: number): Promise<void> {
return new Promise<void>((resolve) => setTimeout(resolve, ms));
}
+709
View File
@@ -0,0 +1,709 @@
/**
* Transport-independent client for the CFW keyboard bridge: enable, scan,
* connect and pair a keyboard through the glasses, discover its HID service
* over the relayed ATT operations, subscribe its input reports, and decode
* them into key transitions. From the reference client in g2flash demos/
* (keyboard-client.ts), with the fixes its use in the Glassly app turned up.
*
* The firmware keeps almost no policy: it owns the connection and the bond,
* and forwards one ATT request at a time. Everything HID lives here. Handle
* numbers found by configure() are only good for one connection epoch.
* No platform imports: this runs under node in the tests.
*/
import { HidKeys, parseReportMap, reportHasKeys, type HidKeyEvent, type HidReport } from "./hid";
import {
KeyboardDm,
KeyboardError,
KeyboardKind,
KeyboardOp,
KeyboardRecords,
keyboardControl,
keyboardErrorName,
le16,
parseKeyboardAdvert,
u16,
u32,
type KeyboardAdvert,
type KeyboardRecord,
} from "./protocol";
/** Queue one field-130 control record; false when the glasses link can't take it now. */
export type KeyboardTransport = (record: Uint8Array) => boolean;
export type KeyboardStatus = {
enabled: boolean;
/** The firmware's connection id for the keyboard, 0 when it owns none. */
conn: number;
connected: boolean;
encrypted: boolean;
scanning: boolean;
};
export type KeyboardClientEvents = {
/** Key transitions from one input report (or the releases a gap forces). */
keys?(events: HidKeyEvent[]): void;
advert?(advert: KeyboardAdvert): void;
status?(status: KeyboardStatus): void;
/** The stream may have lost records; held keys were released. */
gap?(): void;
/** Device-manager event from the glasses' BLE host (KeyboardDm). */
dm?(event: number, status: number): void;
/** The keyboard shows a six-digit passkey; answer with authenticate(). */
passkeyRequest?(): void;
/** We chose a passkey and answered with it; the user types it on the keyboard, then Enter. */
passkeyDisplay?(pin: number): void;
/** Numeric comparison: answer with confirm() once the user has compared. */
compareRequest?(value: number): void;
/** The keyboard's GATT table changed; the mapping is void until configure() runs again. */
servicesChanged?(): void;
error?(message: string): void;
/** Setup diagnostics: the keyboard's attribute table and what was made of it. Never key contents. */
log?(line: string): void;
};
export type KeyboardReport = {
/** Handle of the HID service declaration the report belongs to. */
service: number;
handle: number;
id: number;
/** 1 input, 2 output, 3 feature. */
type: number;
ccc?: number;
/** From the characteristic's declaration; undefined when the keyboard wouldn't say (see declaredProperties). */
properties?: number;
map: Uint8Array;
};
export type KeyboardConfiguration = {
epoch: number;
/** Every report found, input or not. */
reports: KeyboardReport[];
/** Handles of the input reports subscribed for keys. */
watched: number[];
serviceChanged?: number;
};
export type KeyboardClientOptions = {
/** A fresh six-digit passkey for display pairing. Default: Math.random (pass a stronger source). */
randomPasskey?: () => number;
};
export class KeyboardClientError extends Error {
/** The firmware's control error code (KeyboardError), when that is what failed. */
readonly code: number | undefined;
/** The keyboard's ATT error code, when it refused a read or write. */
readonly attStatus: number | undefined;
constructor(message: string, code?: number, attStatus?: number) {
super(message);
this.name = "KeyboardClientError";
this.code = code;
this.attStatus = attStatus;
}
}
type Attribute = { handle: number; uuid: number | string };
type Pending = {
op: number;
resolve: (r: KeyboardRecord) => void;
reject: (e: Error) => void;
timer: ReturnType<typeof setTimeout>;
};
type Waiter = { test: () => boolean; resolve: () => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> };
type Input = { report: HidReport; id: number; service: number };
const COMMAND_TIMEOUT_MS = 32_000;
const MAX_PENDING = 8;
const MAX_ATTRIBUTES = 512;
const MAX_VALUE = 512;
const MAX_WATCHES = 16;
const UUID_PRIMARY_SERVICE = 0x2800;
const UUID_SECONDARY_SERVICE = 0x2801;
const UUID_CHARACTERISTIC = 0x2803;
const UUID_CCC = 0x2902;
const UUID_EXTERNAL_REPORT_REFERENCE = 0x2907;
const UUID_REPORT_REFERENCE = 0x2908;
const UUID_HID_SERVICE = 0x1812;
const UUID_SERVICE_CHANGED = 0x2a05;
const UUID_REPORT_MAP = 0x2a4b;
const UUID_REPORT = 0x2a4d;
const UUID_PROTOCOL_MODE = 0x2a4e;
/** ATT error codes that end a paged read rather than failing it. */
const ATT_INVALID_OFFSET = 7;
const ATT_NOT_LONG = 11;
const ATT_NOT_FOUND = 10;
/**
* ATT UUIDs are little endian. A 128-bit UUID on the Bluetooth base collapses
* to its 16-bit form; vendor UUIDs stay as hex strings.
*/
export function attributeUuid(bytes: Uint8Array): number | string {
if (bytes.length === 2) return u16(bytes);
if (bytes.length !== 16) throw new KeyboardClientError("Invalid ATT UUID length");
const base = [0xfb, 0x34, 0x9b, 0x5f, 0x80, 0, 0, 0x80, 0, 0x10, 0, 0];
if (base.every((v, i) => bytes[i] === v) && bytes[14] === 0 && bytes[15] === 0) return u16(bytes, 12);
return Array.from(bytes, (x) => x.toString(16).padStart(2, "0")).join("");
}
export class KeyboardClient {
/** The firmware's connection generation; every control but QUERY/ENABLE must carry the live one. */
epoch = 0;
status: KeyboardStatus = { enabled: false, conn: 0, connected: false, encrypted: false, scanning: false };
configuration: KeyboardConfiguration | undefined;
private serial = 0;
private closed = false;
/** The link under connect() went away (close, failed open, failed pairing). */
private linkLost = false;
private readonly pending = new Map<number, Pending>();
private readonly waiters = new Set<Waiter>();
private readonly keys = new HidKeys();
private inputs = new Map<number, Input>();
private readonly records = new KeyboardRecords(() => this.gap());
private readonly randomPasskey: () => number;
constructor(
private readonly transport: KeyboardTransport,
private readonly events: KeyboardClientEvents = {},
options: KeyboardClientOptions = {},
) {
this.randomPasskey = options.randomPasskey ?? (() => Math.floor(Math.random() * 1_000_000));
}
// ---------- Inbound ----------
/** Feed one field-131 payload, in arrival order. */
accept(data: Uint8Array): void {
if (this.closed) return;
const r = this.records.push(data);
if (!r) return;
this.epoch = r.epoch;
if (r.kind === KeyboardKind.status && r.data.length === 10) {
this.status = {
enabled: !!r.data[0], conn: r.data[1]!, connected: !!r.data[2], encrypted: !!r.data[3], scanning: !!r.data[4],
};
if (!this.status.enabled || !this.status.connected || !this.status.encrypted) this.release();
this.events.status?.(this.status);
}
const pending = this.pending.get(r.request);
if (pending && (r.kind === KeyboardKind.status || r.kind === KeyboardKind.att)) {
this.pending.delete(r.request);
clearTimeout(pending.timer);
if (r.kind === KeyboardKind.status && r.code) {
pending.reject(new KeyboardClientError(
`Keyboard command ${opName(pending.op)}: firmware ${keyboardErrorName(r.code)}`, r.code));
} else {
pending.resolve(r);
}
}
if (r.kind === KeyboardKind.dm) this.acceptDm(r);
else if (r.kind === KeyboardKind.input) this.acceptInput(r);
else if (r.kind === KeyboardKind.advert) {
const advert = parseKeyboardAdvert(r.data);
if (advert) this.events.advert?.(advert);
}
this.checkWaiters();
}
private acceptDm(r: KeyboardRecord): void {
const event = r.code & 255;
const status = r.code >>> 8;
if (event === KeyboardDm.connClose || event === KeyboardDm.pairFailed || event === KeyboardDm.encryptFailed ||
(event === KeyboardDm.connOpen && status !== 0)) {
this.linkLost = true;
this.gap();
this.inputs.clear();
this.configuration = undefined;
}
if (event === KeyboardDm.authRequest && r.data.length === 2) {
if (r.data[0]) {
this.command(KeyboardOp.disconnect).catch(() => {});
this.events.error?.("This keyboard only pairs out of band, which isn't supported.");
} else if (r.data[1]) {
// KeyboardDisplay on our side: choose the passkey, show it, and
// answer at once; the user types it on the keyboard.
const pin = Math.min(999_999, Math.max(0, Math.floor(this.randomPasskey())));
this.events.passkeyDisplay?.(pin);
this.authenticate(pin).catch((e) => this.events.error?.(messageOf(e)));
} else {
this.events.passkeyRequest?.();
}
}
if (event === KeyboardDm.compare && r.data.length === 4) this.events.compareRequest?.(u32(r.data));
this.events.dm?.(event, status);
}
private acceptInput(r: KeyboardRecord): void {
const changed = this.configuration?.serviceChanged;
if (changed !== undefined && r.handle === changed) {
this.gap();
this.inputs.clear();
this.configuration = undefined;
this.events.servicesChanged?.();
return;
}
const input = this.inputs.get(r.handle);
if (!input || this.configuration?.epoch !== r.epoch) {
this.gap();
return;
}
try {
const events = this.keys.update(r.handle, input.report, r.data);
if (events.length) this.events.keys?.(events);
} catch (e) {
this.release();
this.events.error?.(messageOf(e));
}
}
private release(): void {
const events = this.keys.reset();
if (events.length) this.events.keys?.(events);
}
private gap(): void {
this.release();
this.events.gap?.();
for (const [id, p] of this.pending) {
if (p.op < KeyboardOp.find) continue;
clearTimeout(p.timer);
this.pending.delete(id);
p.reject(new KeyboardClientError("Keyboard stream gap during ATT transaction"));
}
}
/** The phone's link to the glasses dropped: release held keys and fail everything in flight. */
lostPhoneLink(): void {
this.records.reset();
this.cancel("Glasses link lost");
}
/** Stop for good; later accept() calls are ignored. */
close(): void {
if (this.closed) return;
this.lostPhoneLink();
this.closed = true;
}
private cancel(reason: string): void {
for (const p of this.pending.values()) {
clearTimeout(p.timer);
p.reject(new KeyboardClientError(reason));
}
this.pending.clear();
for (const w of this.waiters) {
clearTimeout(w.timer);
w.reject(new KeyboardClientError(reason));
}
this.waiters.clear();
}
private checkWaiters(): void {
for (const w of [...this.waiters]) {
let done = false;
try {
done = w.test();
} catch (e) {
this.waiters.delete(w);
clearTimeout(w.timer);
w.reject(e instanceof Error ? e : new KeyboardClientError(String(e)));
continue;
}
if (!done) continue;
this.waiters.delete(w);
clearTimeout(w.timer);
w.resolve();
}
}
/** Resolve once `test` holds; it is re-evaluated after every accepted record. */
private waitFor(test: () => boolean, timeoutMs: number, what: string): Promise<void> {
if (this.closed) return Promise.reject(new KeyboardClientError("Keyboard client closed"));
if (test()) return Promise.resolve();
return new Promise<void>((resolve, reject) => {
const waiter: Waiter = {
test, resolve, reject,
timer: setTimeout(() => {
this.waiters.delete(waiter);
reject(new KeyboardClientError(`Timed out waiting for ${what}`));
}, timeoutMs),
};
this.waiters.add(waiter);
});
}
// ---------- Commands ----------
/** Send one control and await the STATUS or ATT record that answers it. */
command(op: number, body: readonly number[] = []): Promise<KeyboardRecord> {
if (this.closed) return Promise.reject(new KeyboardClientError("Keyboard client closed"));
if (this.pending.size >= MAX_PENDING) return Promise.reject(new KeyboardClientError("Too many keyboard commands"));
const request = this.serial = this.serial % 65535 + 1;
return new Promise<KeyboardRecord>((resolve, reject) => {
const timer = setTimeout(() => {
this.pending.delete(request);
reject(new KeyboardClientError(`Keyboard command ${opName(op)} timed out`));
}, COMMAND_TIMEOUT_MS);
this.pending.set(request, { op, resolve, reject, timer });
let queued = false;
try {
queued = this.transport(keyboardControl(op, request, this.epoch, body));
} catch {
queued = false;
}
if (!queued) {
clearTimeout(timer);
this.pending.delete(request);
reject(new KeyboardClientError("The glasses aren't ready for keyboard commands"));
}
});
}
async enable(): Promise<void> {
await this.command(KeyboardOp.enable);
}
/** Disconnect the keyboard and stop the bridge; the bond stays. */
async disable(): Promise<void> {
await this.command(KeyboardOp.disable);
this.release();
}
/** Ask for the firmware's state. Also the way to learn the live epoch: QUERY isn't epoch-checked. */
async query(): Promise<KeyboardStatus> {
await this.command(KeyboardOp.query);
return this.status;
}
/**
* Active scan for about five seconds; adverts arrive through events.advert.
* The firmware only clears `scanning` once the stock scanner is idle again,
* and a ring looking for its lens can hold that well past the window, so a
* lingering flag is not an error: the adverts already delivered stand.
*/
async scan(): Promise<void> {
await this.command(KeyboardOp.scan);
try {
await this.waitFor(() => !this.status.scanning, 8000, "the scan to finish");
} catch (e) {
if (this.closed) throw e;
}
}
/** Connect, then pair unless the link comes up encrypted. `address` is LSB first. */
async connect(addressType: number, address: Uint8Array): Promise<void> {
if (address.length !== 6 || !Number.isInteger(addressType) || addressType < 0 || addressType > 3) {
throw new KeyboardClientError("Invalid BLE address");
}
this.release();
this.inputs.clear();
this.configuration = undefined;
this.linkLost = false;
await this.command(KeyboardOp.connect, [addressType, ...address]);
await this.waitFor(() => this.status.connected || this.linkLost, 32_000, "the keyboard to connect");
if (!this.status.connected) throw new KeyboardClientError("The keyboard didn't answer");
if (!this.status.encrypted) {
// The keyboard's own security request may have started pairing already.
// BUSY is not success: the encrypted status below still decides.
try {
await this.command(KeyboardOp.pair);
} catch (e) {
if (!(e instanceof KeyboardClientError) || e.code !== KeyboardError.busy) throw e;
}
await this.waitFor(() => this.status.encrypted || this.linkLost, 65_000, "pairing to finish");
if (!this.status.encrypted) throw new KeyboardClientError("Pairing with the keyboard failed");
}
}
async disconnect(): Promise<void> {
await this.command(KeyboardOp.disconnect);
this.release();
}
/** Answer a pending passkey prompt. */
async authenticate(pin: number): Promise<void> {
if (!Number.isInteger(pin) || pin < 0 || pin > 999_999) throw new KeyboardClientError("Invalid pairing passkey");
await this.command(KeyboardOp.auth, [pin & 255, (pin >>> 8) & 255, pin >>> 16]);
}
/** Answer a pending numeric comparison. */
async confirm(accept: boolean): Promise<void> {
await this.command(KeyboardOp.compare, [accept ? 1 : 0]);
}
private async att(op: number, body: readonly number[]): Promise<KeyboardRecord> {
const r = await this.command(op, body);
if (r.kind !== KeyboardKind.att) throw new KeyboardClientError("Expected keyboard ATT response");
return r;
}
/** Read a whole attribute: Read, then Read Blob until a short or empty reply. Never assumes the MTU. */
async read(handle: number): Promise<Uint8Array> {
const parts: number[] = [];
for (;;) {
const r = await this.att(KeyboardOp.read, [...le16(handle), ...le16(parts.length)]);
const status = r.code >>> 8;
if (parts.length && (status === ATT_INVALID_OFFSET || status === ATT_NOT_LONG)) break;
if (status) throw new KeyboardClientError(`ATT read ${handle}: ${status}`, undefined, status);
if (!r.data.length) break;
for (const b of r.data) parts.push(b);
if (parts.length > MAX_VALUE) throw new KeyboardClientError("Attribute exceeds 512 bytes");
if (parts.length === MAX_VALUE) break;
}
return Uint8Array.from(parts);
}
/** Read a short attribute once (a Report Reference, a declaration, a service UUID). */
private async shortRead(handle: number): Promise<Uint8Array> {
const r = await this.att(KeyboardOp.read, [...le16(handle), 0, 0]);
if (r.code >>> 8) throw new KeyboardClientError(`ATT read ${handle}: ${r.code >>> 8}`, undefined, r.code >>> 8);
return r.data;
}
/** Write 1..18 bytes (an output report such as the LEDs, a CCC, the protocol mode). */
async write(handle: number, value: Uint8Array, withoutResponse = false): Promise<void> {
if (!value.length || value.length > 18) throw new KeyboardClientError("Keyboard write supports 1..18 bytes");
const r = await this.att(KeyboardOp.write, [...le16(handle), withoutResponse ? 1 : 0, value.length, ...value]);
if (r.code >>> 8) throw new KeyboardClientError(`ATT write ${handle}: ${r.code >>> 8}`, undefined, r.code >>> 8);
}
private async attributes(): Promise<Attribute[]> {
const attrs: Attribute[] = [];
let start = 1;
while (start <= 65535) {
const r = await this.att(KeyboardOp.find, [...le16(start), 255, 255]);
const status = r.code >>> 8;
if (status === ATT_NOT_FOUND) break; // the normal end of the table
if (status) throw new KeyboardClientError(`ATT Find Information: ${status}`);
const width = r.data[0] === 1 ? 4 : r.data[0] === 2 ? 18 : 0;
if (!width || r.data.length <= 1 || (r.data.length - 1) % width) {
throw new KeyboardClientError("Malformed Find Information response");
}
for (let i = 1; i < r.data.length; i += width) {
const handle = u16(r.data, i);
if (handle < start || attrs.length >= MAX_ATTRIBUTES) throw new KeyboardClientError("Invalid or excessive GATT handles");
attrs.push({ handle, uuid: attributeUuid(r.data.subarray(i + 2, i + width)) });
start = handle + 1;
}
}
return attrs;
}
/**
* The properties byte of a characteristic, from its declaration, or
* undefined when the keyboard won't say. A GATT client normally learns
* declarations through Read By Type, which the bridge doesn't relay, so
* this reads the declaration attribute itself. Most stacks answer that
* with the full declaration. Some keep only the properties byte there and
* build the rest for Read By Type alone (older Telink SDKs, common in
* small keyboards), and some refuse the read. None of that is a reason to
* turn a keyboard away: the report's handle and UUID are already known.
*/
private async declaredProperties(attrs: readonly Attribute[], a: Attribute): Promise<number | undefined> {
const decl = attrs.filter((d) => d.handle < a.handle && d.uuid === UUID_CHARACTERISTIC).pop();
if (!decl) return undefined;
let declaration: Uint8Array;
try {
declaration = await this.shortRead(decl.handle);
} catch (e) {
const status = attRefusal(e);
this.events.log?.(`declaration ${decl.handle} of ${a.handle}: read refused (ATT ${status})`);
return undefined;
}
if (declaration.length === 5 || declaration.length === 19) {
if (u16(declaration, 1) === a.handle && attributeUuid(declaration.subarray(3)) === a.uuid) return declaration[0]!;
this.events.log?.(`declaration ${decl.handle} of ${a.handle}: describes something else (${hex(declaration)})`);
return undefined;
}
if (declaration.length === 1) return declaration[0]!;
this.events.log?.(`declaration ${decl.handle} of ${a.handle}: unexpected value (${hex(declaration)})`);
return undefined;
}
/**
* Discover every HID service, its Report Map and each report's Report
* Reference; select Report Protocol and subscribe the input reports that
* can carry keys. Needs an encrypted link. No handle is assumed.
*
* Only what typing needs is required of the keyboard: a Report Map that
* parses, and at least one key-bearing input report with a Report
* Reference and a CCC. A report that can't be placed is skipped and
* logged, as is anything wrong with an external report (the battery
* level, usually).
*/
async configure(): Promise<KeyboardConfiguration> {
const epoch = this.epoch;
const log = (line: string): void => this.events.log?.(line);
// A new discovery replaces any earlier mapping, whether or not it succeeds.
this.release();
this.inputs.clear();
this.configuration = undefined;
const attrs = await this.attributes();
log(`gatt ${attrs.map((a) => `${a.handle}=${typeof a.uuid === "number" ? a.uuid.toString(16) : a.uuid}`).join(" ")}`);
const reports: KeyboardReport[] = [];
const watched: KeyboardReport[] = [];
const skipped: string[] = [];
const descriptorsFor = (handle: number): Attribute[] => {
const end = attrs.find((a) => a.handle > handle &&
(a.uuid === UUID_PRIMARY_SERVICE || a.uuid === UUID_SECONDARY_SERVICE || a.uuid === UUID_CHARACTERISTIC))?.handle ?? 65536;
return attrs.filter((a) => a.handle > handle && a.handle < end);
};
/** Why a report was left out; the link going away is not a reason to carry on. */
const skip = (a: Attribute, reason: string): void => {
skipped.push(`${a.handle}: ${reason}`);
log(`report ${a.handle} skipped: ${reason}`);
};
const addReport = async (service: number, a: Attribute, map: Uint8Array, parsed: Map<number, HidReport>) => {
if (reports.some((r) => r.handle === a.handle)) return skip(a, "already listed by another HID service");
const descriptors = descriptorsFor(a.handle);
const ref = descriptors.find((d) => d.uuid === UUID_REPORT_REFERENCE);
if (!ref) return skip(a, "no Report Reference descriptor");
let reference: Uint8Array;
try {
reference = await this.shortRead(ref.handle);
} catch (e) {
return skip(a, `Report Reference ${ref.handle} unreadable (ATT ${attRefusal(e)})`);
}
if (reference.length !== 2) return skip(a, `Report Reference ${ref.handle} is ${hex(reference) || "empty"}`);
const id = reference[0]!;
const type = reference[1]!;
if (type < 1 || type > 3) return skip(a, `Report Reference type ${type}`);
const ccc = descriptors.find((d) => d.uuid === UUID_CCC)?.handle;
const properties = await this.declaredProperties(attrs, a);
const report: KeyboardReport = { service, handle: a.handle, id, type, ccc, properties, map };
if (type === 1) {
const layout = parsed.get(id);
if (!layout) return skip(a, `input report id ${id} is not in the Report Map`);
if (ccc === undefined || (properties !== undefined && !(properties & 0x10))) return skip(a, "input report can't notify");
if (reportHasKeys(layout)) watched.push(report);
else log(`report ${a.handle} (id ${id}) carries no keys; not subscribed`);
}
reports.push(report);
log(`report ${a.handle}: id ${id} type ${type} ccc ${ccc ?? "-"} properties ${properties ?? "?"}`);
};
for (let i = 0; i < attrs.length; i++) {
const service = attrs[i]!;
if (service.uuid !== UUID_PRIMARY_SERVICE) continue;
if (attributeUuid(await this.shortRead(service.handle)) !== UUID_HID_SERVICE) continue;
const end = attrs.slice(i + 1).find((a) => a.uuid === UUID_PRIMARY_SERVICE || a.uuid === UUID_SECONDARY_SERVICE)?.handle ?? 65536;
const members = attrs.filter((a) => a.handle > service.handle && a.handle < end);
const mapAttr = members.find((a) => a.uuid === UUID_REPORT_MAP);
if (!mapAttr) throw new KeyboardClientError(`HID service ${service.handle} has no Report Map`);
const map = await this.read(mapAttr.handle);
log(`report map ${mapAttr.handle}: ${hex(map)}`);
const parsed = parseReportMap(map);
for (const mode of members.filter((a) => a.uuid === UUID_PROTOCOL_MODE)) {
try {
await this.write(mode.handle, Uint8Array.of(1), true);
} catch (e) {
// Report Protocol is the default after a connection; a keyboard
// that won't take the write is almost certainly in it already.
log(`protocol mode ${mode.handle}: write refused (ATT ${attRefusal(e)})`);
}
}
for (const a of members.filter((m) => m.uuid === UUID_REPORT)) await addReport(service.handle, a, map, parsed);
// HOGP lets a Report Map refer to reports in other services (commonly Battery).
for (const ext of descriptorsFor(mapAttr.handle).filter((a) => a.uuid === UUID_EXTERNAL_REPORT_REFERENCE)) {
let value: Uint8Array;
try {
value = await this.shortRead(ext.handle);
} catch (e) {
log(`external report reference ${ext.handle} skipped: unreadable (ATT ${attRefusal(e)})`);
continue;
}
if (value.length !== 2 && value.length !== 16) {
log(`external report reference ${ext.handle} skipped: value ${hex(value) || "empty"}`);
continue;
}
const uuid = attributeUuid(value);
for (const a of attrs.filter((m) => m.uuid === uuid && (m.handle < service.handle || m.handle >= end))) {
await addReport(service.handle, a, map, parsed);
}
}
}
if (this.closed || this.epoch !== epoch) throw new KeyboardClientError("The keyboard link changed during setup");
if (!watched.length) {
throw new KeyboardClientError(reports.length || skipped.length
? `No usable keyboard input report (${skipped.join("; ") || "none carries keys"})`
: "This device has no HID service");
}
if (watched.length > MAX_WATCHES) throw new KeyboardClientError("Keyboard has more than 16 input reports");
const changed = attrs.find((a) => a.uuid === UUID_SERVICE_CHANGED);
const changedCcc = changed && descriptorsFor(changed.handle).find((a) => a.uuid === UUID_CCC);
const watches = watched.map((r) => r.handle);
if (changed && changedCcc && watches.length < MAX_WATCHES) watches.push(changed.handle);
const serviceChanged = changed && changedCcc && watches.includes(changed.handle) ? changed.handle : undefined;
const config: KeyboardConfiguration = { epoch: this.epoch, reports, watched: watched.map((r) => r.handle), serviceChanged };
this.restore(config);
try {
await this.command(KeyboardOp.watch, [watches.length, ...watches.flatMap(le16)]);
if (serviceChanged !== undefined) {
try {
await this.write(changedCcc!.handle, Uint8Array.of(2, 0));
} catch (e) {
log(`service changed ${changedCcc!.handle}: subscription refused (ATT ${attRefusal(e)})`);
}
}
for (const r of watched) await this.write(r.ccc!, Uint8Array.of(1, 0));
} catch (e) {
this.inputs.clear();
this.configuration = undefined;
this.release();
throw e;
}
return config;
}
/**
* Install a mapping found by configure(). It is only good while the glasses
* keep the same connection (the same epoch): after a keyboard reconnect or
* a firmware boot, discover again.
*/
restore(config: KeyboardConfiguration): void {
if (!config.reports.length || config.reports.length > 64) throw new KeyboardClientError("Invalid keyboard configuration");
const inputs = new Map<number, Input>();
for (const r of config.reports) {
if (r.type !== 1 || !config.watched.includes(r.handle)) continue;
if (!Number.isInteger(r.handle) || r.handle < 1 || r.handle > 65535 || inputs.has(r.handle)) {
throw new KeyboardClientError("Invalid restored Report handle");
}
if (!r.map.length || r.map.length > MAX_VALUE) throw new KeyboardClientError("Invalid restored Report Map");
const report = parseReportMap(r.map).get(r.id);
if (!report) throw new KeyboardClientError("Restored Report ID missing");
inputs.set(r.handle, { report, id: r.id, service: r.service });
}
if (!inputs.size || inputs.size > MAX_WATCHES) throw new KeyboardClientError("Invalid restored input count");
this.release();
this.inputs = inputs;
this.configuration = config;
}
/** Output reports of the configured keyboard (the LED report is the usual one). */
outputReports(): KeyboardReport[] {
return this.configuration?.reports.filter((r) => r.type === 2) ?? [];
}
}
/**
* The ATT error code when `error` is the keyboard refusing a read or write.
* Anything else (the link dropping, a timeout, a stream gap) is rethrown:
* those end the setup, where a refusal only costs the one attribute.
*/
function attRefusal(error: unknown): number {
if (error instanceof KeyboardClientError && error.attStatus !== undefined) return error.attStatus;
throw error;
}
function hex(bytes: Uint8Array): string {
return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
}
function opName(op: number): string {
for (const [name, value] of Object.entries(KeyboardOp)) if (value === op) return name;
return String(op);
}
function messageOf(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
+188
View File
@@ -0,0 +1,188 @@
/**
* Bounded HID report-descriptor decoder for the keyboard bridge: turns a
* keyboard's Report Map into the layout of each input report, and input
* reports into the set of keys held. From the reference client in g2flash
* demos/ (keyboard-hid.ts).
*
* HID over GATT carries the Report ID out of band (in each characteristic's
* Report Reference descriptor), so byte zero of a report value is data: it is
* never stripped as USB HID would. Only the keyboard/keypad page (7) and the
* consumer page (12) produce keys; pointer axes and padding are ignored.
* No platform imports: this runs under node in the tests.
*/
export type HidUsage = { page: number; usage: number };
export type HidKeyEvent = HidUsage & { down: boolean };
type Global = { page: number; min: number; max: number; size: number; count: number; id: number };
type Field = {
bit: number;
size: number;
count: number;
variable: boolean;
min: number;
max: number;
usages: HidUsage[];
range?: [HidUsage, HidUsage];
};
export type HidReport = { id: number; bits: number; fields: Field[] };
const HID_PAGE_KEYBOARD = 7;
const HID_PAGE_CONSUMER = 12;
const REPORT_MAP_MAX = 512;
function fail(reason: string): never {
throw new Error(`Unsupported or malformed HID descriptor: ${reason}`);
}
const usageKey = (u: HidUsage): string => `${u.page}:${u.usage}`;
/** Input reports by Report ID (0 when the descriptor uses none). Throws on anything out of bounds. */
export function parseReportMap(bytes: Uint8Array): Map<number, HidReport> {
if (!bytes.length || bytes.length > REPORT_MAP_MAX) fail("report map must contain 1..512 bytes");
const reports = new Map<number, HidReport>();
let g: Global = { page: 0, min: 0, max: 0, size: 0, count: 0, id: 0 };
const stack: Global[] = [];
let usages: HidUsage[] = [];
let lo: HidUsage | undefined;
let hi: HidUsage | undefined;
let depth = 0;
const usage = (v: number, n: number): HidUsage =>
n === 4 ? { page: v >>> 16, usage: v & 65535 } : { page: g.page, usage: v };
for (let p = 0; p < bytes.length;) {
const prefix = bytes[p++]!;
if (prefix === 0xfe) fail("long items");
const n = [0, 1, 2, 4][prefix & 3]!;
if (p + n > bytes.length) fail("truncated item");
let v = 0;
for (let j = 0; j < n; j++) v += bytes[p++]! * 2 ** (8 * j);
const signed = n && v >= 2 ** (n * 8 - 1) ? v - 2 ** (n * 8) : v;
const type = (prefix >> 2) & 3;
const tag = prefix >> 4;
if (type === 1) {
switch (tag) {
case 0: g.page = v; break;
case 1: g.min = signed; break;
case 2: g.max = g.min < 0 ? signed : v; break;
case 7: g.size = v; break;
case 8: if (!v || v > 255) fail("Report ID"); g.id = v; break;
case 9: g.count = v; break;
case 10: if (stack.length >= 8) fail("global stack overflow"); stack.push({ ...g }); break;
case 11: if (!stack.length) fail("global stack underflow"); g = stack.pop()!; break;
case 3: case 4: case 5: case 6: break; // physical range, unit and exponent
default: fail("unknown global item");
}
} else if (type === 2) {
if (tag === 0) { if (usages.length >= 512) fail("too many usages"); usages.push(usage(v, n)); }
else if (tag === 1) lo = usage(v, n);
else if (tag === 2) hi = usage(v, n);
else if (tag === 10) fail("usage delimiters");
else if (tag > 9) fail("unknown local item");
} else if (type === 0) {
if (tag === 10) { if (++depth > 32) fail("collection depth"); }
else if (tag === 12) { if (--depth < 0) fail("collection underflow"); }
else if (tag === 8) {
if (!g.size || g.size > 32 || !g.count || g.count > 512) fail("field dimensions");
let r = reports.get(g.id);
if (!r) {
if (reports.size >= 16) fail("too many input reports");
r = { id: g.id, bits: 0, fields: [] };
reports.set(g.id, r);
}
const field: Field = {
bit: r.bits, size: g.size, count: g.count, variable: !!(v & 2), min: g.min, max: g.max, usages: [...usages],
};
if (lo || hi) {
if (!lo || !hi || lo.page !== hi.page || hi.usage < lo.usage) fail("usage range");
field.range = [lo!, hi!];
}
r.bits += g.size * g.count;
if (r.bits > 4096) fail("report exceeds 512 bytes");
// Constant padding and relative pointer axes are not keys.
if (!(v & 1) && !(v & 4)) r.fields.push(field);
} else if (tag !== 9 && tag !== 11) fail("unknown main item");
usages = [];
lo = hi = undefined;
} else fail("reserved item type");
}
if (depth || stack.length) fail("unbalanced collection/global stack");
if (reports.has(0) && reports.size > 1) fail("mixed numbered and unnumbered input reports");
if (!reports.size) fail("no input reports");
return reports;
}
function usageAt(f: Field, index: number): HidUsage | undefined {
if (index < 0) return undefined;
if (index < f.usages.length) return f.usages[index];
const rangeIndex = index - f.usages.length;
if (f.range && rangeIndex <= f.range[1].usage - f.range[0].usage) {
return { page: f.range[0].page, usage: f.range[0].usage + rangeIndex };
}
// Variable items reuse their last usage when Report Count exceeds the usages.
if (f.variable) return f.range?.[1] ?? f.usages[f.usages.length - 1];
return undefined;
}
/**
* Whether an input report can ever say a key is held. False for a pointer's
* report (a trackpad or mouse on a combined device), whose movement would
* otherwise be relayed, and thrown away, a hundred times a second.
*/
export function reportHasKeys(report: HidReport): boolean {
const isKeyPage = (u: HidUsage): boolean => u.page === HID_PAGE_KEYBOARD || u.page === HID_PAGE_CONSUMER;
return report.fields.some((f) => f.usages.some(isKeyPage) || (f.range !== undefined && isKeyPage(f.range[0])));
}
/** The keys one input report says are held. Throws on a length mismatch or a rollover report. */
export function reportKeys(report: HidReport, data: Uint8Array): HidUsage[] {
if (data.length !== Math.ceil(report.bits / 8)) throw new Error("HID input length does not match Report Map");
const keys = new Map<string, HidUsage>();
for (const f of report.fields) {
for (let i = 0; i < f.count; i++) {
let value = 0;
for (let j = 0; j < f.size; j++) {
const bit = f.bit + i * f.size + j;
if (data[bit >>> 3]! & (1 << (bit & 7))) value += 2 ** j;
}
if (f.min < 0 && value >= 2 ** (f.size - 1)) value -= 2 ** f.size;
if (value < f.min || value > f.max) continue; // null state
const u = usageAt(f, f.variable ? i : value - f.min);
if (!u || (f.variable && value === 0) || !u.usage) continue;
if (u.page === HID_PAGE_KEYBOARD && u.usage <= 3) throw new Error("HID keyboard rollover/error report");
if (u.page === HID_PAGE_KEYBOARD || u.page === HID_PAGE_CONSUMER) keys.set(usageKey(u), u);
}
}
return [...keys.values()];
}
/**
* Held keys across a keyboard's input reports. Ownership is per report
* characteristic, then unioned: releasing a key in one report cannot release
* a modifier another report still holds.
*/
export class HidKeys {
private reports = new Map<number, HidUsage[]>();
private held = new Map<string, HidUsage>();
/** Apply one report from characteristic `handle`; returns the transitions it caused. */
update(handle: number, report: HidReport, data: Uint8Array): HidKeyEvent[] {
this.reports.set(handle, reportKeys(report, data));
return this.diff();
}
/** Release everything (a stream gap, a dropped link). */
reset(): HidKeyEvent[] {
this.reports.clear();
return this.diff();
}
private diff(): HidKeyEvent[] {
const next = new Map<string, HidUsage>();
for (const values of this.reports.values()) for (const u of values) next.set(usageKey(u), u);
const events: HidKeyEvent[] = [];
for (const [k, u] of this.held) if (!next.has(k)) events.push({ ...u, down: false });
for (const [k, u] of next) if (!this.held.has(k)) events.push({ ...u, down: true });
this.held = next;
return events;
}
}
+315
View File
@@ -0,0 +1,315 @@
/**
* Key events as the rest of Faceclaw sees them, and the translation from the
* keyboard bridge's raw HID transitions: layout (US only for now), modifier
* and Caps Lock state, and typematic repeat, which a BLE keyboard never sends
* (its report just stays asserted). The translation tables follow the Glassly
* app's (GlassesKeyboardInput.ts, MIT).
* No platform imports: this runs under node in the tests, and in app workers.
*/
import type { HidKeyEvent } from "./hid";
export type KeyModifiers = { shift: boolean; ctrl: boolean; alt: boolean; meta: boolean };
/**
* One key transition, shaped like a DOM KeyboardEvent: `key` is the logical
* key with the layout applied ("a", "A", "Enter", "ArrowUp"), `code` the
* physical key ("KeyA"), `text` what a press types (absent for releases, for
* keys that type nothing, and for Ctrl/Alt/Meta chords, which are commands).
*/
export type KeyEvent = {
phase: "down" | "up";
key: string;
code: string;
text?: string;
modifiers: KeyModifiers;
/** A synthesized auto-repeat of a held key. */
repeat: boolean;
/** Date.now() when the phone saw the transition. */
timestampMs: number;
};
const HID_PAGE_KEYBOARD = 7;
const HID_PAGE_CONSUMER = 12;
const USAGE_CAPS_LOCK = 57;
/** [unshifted, shifted, code] for US-layout punctuation on the keyboard page. */
const PUNCTUATION: Record<number, [string, string, string]> = {
45: ["-", "_", "Minus"],
46: ["=", "+", "Equal"],
47: ["[", "{", "BracketLeft"],
48: ["]", "}", "BracketRight"],
49: ["\\", "|", "Backslash"],
50: ["#", "~", "IntlHash"],
51: [";", ":", "Semicolon"],
52: ["'", '"', "Quote"],
53: ["`", "~", "Backquote"],
54: [",", "<", "Comma"],
55: [".", ">", "Period"],
56: ["/", "?", "Slash"],
100: ["\\", "|", "IntlBackslash"],
};
const DIGITS = "1234567890";
const SHIFTED_DIGITS = "!@#$%^&*()";
/** [key, code] for keys that type nothing. */
const NAMED: Record<number, [string, string]> = {
40: ["Enter", "Enter"],
41: ["Escape", "Escape"],
42: ["Backspace", "Backspace"],
43: ["Tab", "Tab"],
57: ["CapsLock", "CapsLock"],
70: ["PrintScreen", "PrintScreen"],
71: ["ScrollLock", "ScrollLock"],
72: ["Pause", "Pause"],
73: ["Insert", "Insert"],
74: ["Home", "Home"],
75: ["PageUp", "PageUp"],
76: ["Delete", "Delete"],
77: ["End", "End"],
78: ["PageDown", "PageDown"],
79: ["ArrowRight", "ArrowRight"],
80: ["ArrowLeft", "ArrowLeft"],
81: ["ArrowDown", "ArrowDown"],
82: ["ArrowUp", "ArrowUp"],
83: ["NumLock", "NumLock"],
88: ["Enter", "NumpadEnter"],
101: ["ContextMenu", "ContextMenu"],
102: ["Power", "Power"],
224: ["Control", "ControlLeft"],
225: ["Shift", "ShiftLeft"],
226: ["Alt", "AltLeft"],
227: ["Meta", "MetaLeft"],
228: ["Control", "ControlRight"],
229: ["Shift", "ShiftRight"],
230: ["Alt", "AltRight"],
231: ["Meta", "MetaRight"],
};
/** [key and text, code] for the numeric keypad's operators. */
const NUMPAD: Record<number, [string, string]> = {
84: ["/", "NumpadDivide"],
85: ["*", "NumpadMultiply"],
86: ["-", "NumpadSubtract"],
87: ["+", "NumpadAdd"],
99: [".", "NumpadDecimal"],
103: ["=", "NumpadEqual"],
};
const CONSUMER: Record<number, string> = {
0xe9: "AudioVolumeUp",
0xea: "AudioVolumeDown",
0xe2: "AudioVolumeMute",
0xcd: "MediaPlayPause",
0xb0: "MediaPlay",
0xb1: "MediaPause",
0xb5: "MediaTrackNext",
0xb6: "MediaTrackPrevious",
0xb7: "MediaStop",
0x6f: "BrightnessUp",
0x70: "BrightnessDown",
0x221: "BrowserSearch",
0x223: "BrowserHome",
0x224: "BrowserBack",
0x225: "BrowserForward",
0x18a: "LaunchMail",
0x192: "LaunchApplication2",
0x194: "LaunchApplication1",
};
const MODIFIER_USAGES: Record<number, keyof KeyModifiers> = {
224: "ctrl", 228: "ctrl", 225: "shift", 229: "shift", 226: "alt", 230: "alt", 227: "meta", 231: "meta",
};
type Translated = { key: string; code: string; text?: string };
/** One HID usage under the US layout. Caps Lock only affects letters. */
export function translateUsage(page: number, usage: number, shift: boolean, capsLock: boolean): Translated {
if (page === HID_PAGE_KEYBOARD) {
if (usage >= 4 && usage <= 29) {
const lower = String.fromCharCode(97 + usage - 4);
const key = shift !== capsLock ? lower.toUpperCase() : lower;
return { key, code: `Key${lower.toUpperCase()}`, text: key };
}
if (usage >= 30 && usage <= 39) {
const index = usage - 30;
const key = shift ? SHIFTED_DIGITS[index]! : DIGITS[index]!;
return { key, code: `Digit${DIGITS[index]}`, text: key };
}
if (usage === 44) return { key: " ", code: "Space", text: " " };
const punctuation = PUNCTUATION[usage];
if (punctuation) {
const key = shift ? punctuation[1] : punctuation[0];
return { key, code: punctuation[2], text: key };
}
if (usage >= 58 && usage <= 69) return { key: `F${usage - 57}`, code: `F${usage - 57}` };
if (usage >= 104 && usage <= 115) return { key: `F${usage - 91}`, code: `F${usage - 91}` };
if (usage >= 89 && usage <= 97) {
const digit = String(usage - 88);
return { key: digit, code: `Numpad${digit}`, text: digit };
}
if (usage === 98) return { key: "0", code: "Numpad0", text: "0" };
const numpad = NUMPAD[usage];
if (numpad) return { key: numpad[0], code: numpad[1], text: numpad[0] };
const named = NAMED[usage];
if (named) return { key: named[0], code: named[1] };
return { key: "Unidentified", code: `Usage${usage.toString(16).padStart(2, "0")}` };
}
if (page === HID_PAGE_CONSUMER) {
const name = CONSUMER[usage];
return name ? { key: name, code: name } : { key: "Unidentified", code: `Consumer${usage.toString(16)}` };
}
return { key: "Unidentified", code: `Page${page.toString(16)}Usage${usage.toString(16)}` };
}
export type KeyTranslatorOptions = {
emit: (event: KeyEvent) => void;
now?: () => number;
setTimer?: (callback: () => void, delayMs: number) => unknown;
clearTimer?: (handle: unknown) => void;
/** Hold time before the first repeat, and the gap between repeats. */
repeatDelayMs?: number;
repeatIntervalMs?: number;
};
const REPEAT_DELAY_MS = 400;
const REPEAT_INTERVAL_MS = 50;
/**
* Raw HID transitions in, KeyEvents out. Modifier state comes from the same
* stream, and the bridge reports a release for every key when the stream may
* have lost something, so a missed key-up cannot leave a modifier stuck or a
* key repeating forever.
*/
export class KeyTranslator {
private readonly emitEvent: (event: KeyEvent) => void;
private readonly now: () => number;
private readonly setTimer: (callback: () => void, delayMs: number) => unknown;
private readonly clearTimer: (handle: unknown) => void;
private readonly repeatDelayMs: number;
private readonly repeatIntervalMs: number;
private readonly held = new Set<string>();
private modifiers: KeyModifiers = { shift: false, ctrl: false, alt: false, meta: false };
private capsLock = false;
private repeatTimer: unknown = null;
private repeating: { page: number; usage: number } | null = null;
constructor(options: KeyTranslatorOptions) {
this.emitEvent = options.emit;
this.now = options.now ?? (() => Date.now());
this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
this.repeatDelayMs = options.repeatDelayMs ?? REPEAT_DELAY_MS;
this.repeatIntervalMs = options.repeatIntervalMs ?? REPEAT_INTERVAL_MS;
}
/** Apply the transitions one input report produced, in order. */
handle(events: readonly HidKeyEvent[]): void {
for (const event of events) this.handleOne(event);
}
private handleOne(event: HidKeyEvent): void {
const id = `${event.page}:${event.usage}`;
const modifier = event.page === HID_PAGE_KEYBOARD ? MODIFIER_USAGES[event.usage] : undefined;
if (event.down) {
if (this.held.has(id)) return;
this.held.add(id);
if (modifier) this.modifiers[modifier] = true;
if (event.page === HID_PAGE_KEYBOARD && event.usage === USAGE_CAPS_LOCK) this.capsLock = !this.capsLock;
this.emit("down", event.page, event.usage, false);
// The newest non-modifier key is the one that repeats, as on a PC.
if (!modifier) this.startRepeat(event.page, event.usage);
} else {
if (!this.held.delete(id)) return;
if (modifier) this.modifiers[modifier] = this.otherHeld(event.usage, modifier);
if (this.repeating?.page === event.page && this.repeating.usage === event.usage) this.stopRepeat();
this.emit("up", event.page, event.usage, false);
}
}
/** The keyboard went away: forget everything without emitting releases. */
reset(): void {
this.stopRepeat();
this.held.clear();
this.modifiers = { shift: false, ctrl: false, alt: false, meta: false };
this.capsLock = false;
}
/** Whether the same modifier's key on the other side is still down. */
private otherHeld(released: number, modifier: keyof KeyModifiers): boolean {
for (const [usage, name] of Object.entries(MODIFIER_USAGES)) {
if (name === modifier && Number(usage) !== released && this.held.has(`${HID_PAGE_KEYBOARD}:${usage}`)) return true;
}
return false;
}
private emit(phase: "down" | "up", page: number, usage: number, repeat: boolean): void {
const translated = translateUsage(page, usage, this.modifiers.shift, this.capsLock);
const event: KeyEvent = {
phase,
key: translated.key,
code: translated.code,
modifiers: { ...this.modifiers },
repeat,
timestampMs: this.now(),
};
if (phase === "down" && translated.text !== undefined &&
!this.modifiers.ctrl && !this.modifiers.alt && !this.modifiers.meta) {
event.text = translated.text;
}
this.emitEvent(event);
}
private startRepeat(page: number, usage: number): void {
this.stopRepeat();
this.repeating = { page, usage };
this.repeatTimer = this.setTimer(() => this.repeatTick(), this.repeatDelayMs);
}
private repeatTick(): void {
const key = this.repeating;
this.repeatTimer = null;
if (!key || !this.held.has(`${key.page}:${key.usage}`)) {
this.repeating = null;
return;
}
this.emit("down", key.page, key.usage, true);
this.repeatTimer = this.setTimer(() => this.repeatTick(), this.repeatIntervalMs);
}
private stopRepeat(): void {
if (this.repeatTimer !== null) this.clearTimer(this.repeatTimer);
this.repeatTimer = null;
this.repeating = null;
}
}
/** The ring gestures a keyboard can stand in for. */
export type KeyNavigationGesture = "scroll-up" | "scroll-down" | "click" | "double-click";
/**
* What a key does where nothing takes keys as keys: the ring's vocabulary,
* with the same reading of left and right as a watch swipe (right selects,
* left backs out). Held arrows keep scrolling; Enter and Escape act once per
* press. Chords and every other key do nothing. This is a deliberately small
* default, not a button-mapping scheme.
*/
export function navigationGestureForKey(event: KeyEvent): KeyNavigationGesture | null {
if (event.phase !== "down") return null;
const { ctrl, alt, meta } = event.modifiers;
if (ctrl || alt || meta) return null;
switch (event.key) {
case "ArrowUp":
return "scroll-up";
case "ArrowDown":
return "scroll-down";
case "Enter":
case "ArrowRight":
return event.repeat ? null : "click";
case "Escape":
case "ArrowLeft":
return event.repeat ? null : "double-click";
default:
return null;
}
}
+297
View File
@@ -0,0 +1,297 @@
/**
* Wire format of the CFW keyboard bridge (Faceclaw/39). The master temple acts
* as a BLE central for one HID-over-GATT keyboard; the phone drives that link
* over private settings fields and gets the keyboard's raw input reports back.
* The firmware side is g2flash patches/keyboard_core.h, documented in its
* docs/keyboard.md. This follows the reference client in g2flash demos/
* (keyboard-protocol.ts), which came with the firmware from tetramo-labs.
*
* Phone -> glasses, settings field 130 (wrapped by the native session):
* ['K','B',1,op, request LE16, epoch LE16, body...] at most 80 bytes
* Glasses -> phone, settings field 131:
* ['K','B',1,kind, sequence LE32, epoch LE16, request LE16, code LE16,
* handle LE16, total LE16, offset LE16, timestamp LE32, fragment...]
*
* All integers are little endian. No platform imports: this runs under node
* in the tests.
*/
export const KEYBOARD_PROTOCOL_VERSION = 1;
/** Fixed part of a field-131 record, before its fragment. */
export const KEYBOARD_RECORD_HEADER = 24;
/** Most body bytes one record carries; longer bodies are fragmented. */
export const KEYBOARD_RECORD_CHUNK = 96;
/** Largest reassembled body (an ATT value or a HID report). */
export const KEYBOARD_BODY_MAX = 512;
/** Largest control body after the 8-byte prefix. */
export const KEYBOARD_CONTROL_BODY_MAX = 72;
export const KeyboardOp = {
query: 0,
enable: 1,
disable: 2,
scan: 3,
connect: 4,
disconnect: 5,
pair: 6,
auth: 7,
compare: 8,
find: 9,
read: 10,
write: 11,
watch: 12,
} as const;
export type KeyboardOpCode = (typeof KeyboardOp)[keyof typeof KeyboardOp];
export const KeyboardKind = {
status: 1,
att: 2,
input: 3,
dm: 4,
advert: 5,
} as const;
/** Control error codes, carried in a STATUS record's `code`. */
export const KeyboardError = {
ok: 0,
badRequest: 1,
disabled: 2,
busy: 3,
staleEpoch: 4,
noSpace: 5,
notConnected: 6,
notEncrypted: 7,
timeout: 8,
noMemory: 9,
} as const;
export function keyboardErrorName(code: number): string {
switch (code) {
case KeyboardError.ok: return "ok";
case KeyboardError.badRequest: return "bad request";
case KeyboardError.disabled: return "keyboard bridge disabled";
case KeyboardError.busy: return "busy";
case KeyboardError.staleEpoch: return "stale epoch";
case KeyboardError.noSpace: return "no connection or bond space";
case KeyboardError.notConnected: return "not connected";
case KeyboardError.notEncrypted: return "not encrypted";
case KeyboardError.timeout: return "timeout";
case KeyboardError.noMemory: return "allocation failure";
default: return `error ${code}`;
}
}
/** Cordio device-manager events the bridge relays (a DM record's `code & 0xff`). */
export const KeyboardDm = {
connOpen: 0x27,
connClose: 0x28,
pairComplete: 0x2a,
pairFailed: 0x2b,
encrypted: 0x2c,
encryptFailed: 0x2d,
authRequest: 0x2e,
compare: 0x35,
} as const;
/** ATT client events (an ATT record's `code & 0xff`; the status is `code >> 8`). */
export const KeyboardAtt = {
notification: 13,
indication: 14,
} as const;
export type KeyboardRecord = {
kind: number;
sequence: number;
epoch: number;
request: number;
code: number;
handle: number;
/** Glasses uptime in ms when the record was queued. */
timestamp: number;
data: Uint8Array;
};
export const u16 = (p: Uint8Array, off = 0): number => p[off]! | (p[off + 1]! << 8);
export const u32 = (p: Uint8Array, off = 0): number =>
(p[off]! | (p[off + 1]! << 8) | (p[off + 2]! << 16) | (p[off + 3]! << 24)) >>> 0;
export const le16 = (v: number): number[] => [v & 255, (v >>> 8) & 255];
/** A field-130 control record. The session wraps it in the settings package. */
export function keyboardControl(op: number, request: number, epoch: number, body: readonly number[] = []): Uint8Array {
if (!Number.isInteger(op) || op < 0 || op > KeyboardOp.watch || body.length > KEYBOARD_CONTROL_BODY_MAX) {
throw new Error("Keyboard control bounds");
}
return Uint8Array.from([75, 66, KEYBOARD_PROTOCOL_VERSION, op, ...le16(request), ...le16(epoch), ...body]);
}
/**
* Bounded, ordered reassembly of field-131 records. `onGap` fires whenever
* the stream may have lost something (a skipped sequence, an epoch change, a
* malformed or orphaned fragment): the caller then releases every held key
* and fails any setup transaction in flight. The firmware's once-a-second
* status record makes a lost final release visible even when no further keys
* arrive.
*/
export class KeyboardRecords {
private epoch: number | undefined;
private last: number | undefined;
private fragment: { record: KeyboardRecord; total: number; used: number } | undefined;
constructor(private readonly onGap: () => void) {}
/** Forget the stream position (the phone link dropped); counts as a gap. */
reset(): void {
this.epoch = undefined;
this.last = undefined;
this.fragment = undefined;
this.onGap();
}
/** Feed one field-131 payload; returns a complete record, or undefined. */
push(p: Uint8Array): KeyboardRecord | undefined {
const invalid = (): undefined => {
this.fragment = undefined;
this.onGap();
return undefined;
};
if (
p.length < KEYBOARD_RECORD_HEADER || p.length > KEYBOARD_RECORD_HEADER + KEYBOARD_RECORD_CHUNK ||
p[0] !== 75 || p[1] !== 66 || p[2] !== KEYBOARD_PROTOCOL_VERSION
) {
return invalid();
}
const r: KeyboardRecord = {
kind: p[3]!,
sequence: u32(p, 4),
epoch: u16(p, 8),
request: u16(p, 10),
code: u16(p, 12),
handle: u16(p, 14),
timestamp: u32(p, 20),
data: new Uint8Array(0),
};
const total = u16(p, 16);
const offset = u16(p, 18);
const n = p.length - KEYBOARD_RECORD_HEADER;
if (r.kind < KeyboardKind.status || r.kind > KeyboardKind.advert || total > KEYBOARD_BODY_MAX ||
offset + n > total || (total > 0 && n === 0)) {
return invalid();
}
if (this.epoch !== r.epoch) {
this.onGap();
this.fragment = undefined;
this.last = undefined;
this.epoch = r.epoch;
}
if (offset === 0) {
if (this.last !== undefined) {
const distance = (r.sequence - this.last) >>> 0;
if (distance === 0 || distance >= 0x80000000) return undefined; // duplicate or old delivery
}
if (this.fragment || (this.last !== undefined && r.sequence !== ((this.last + 1) >>> 0))) this.onGap();
this.last = r.sequence;
this.fragment = { record: { ...r, data: new Uint8Array(total) }, total, used: 0 };
}
const f = this.fragment;
if (!f || f.used !== offset || f.total !== total || f.record.sequence !== r.sequence ||
f.record.kind !== r.kind || f.record.request !== r.request || f.record.code !== r.code ||
f.record.handle !== r.handle || f.record.timestamp !== r.timestamp) {
return invalid();
}
f.record.data.set(p.subarray(KEYBOARD_RECORD_HEADER), offset);
f.used += n;
if (f.used !== total) return undefined;
this.fragment = undefined;
return f.record;
}
}
/** BLE address types as the controller reports them. */
export const KEYBOARD_ADDRESS_TYPES = ["public", "random", "public-identity", "random-identity"] as const;
/** One advertiser seen during a scan (an ADVERT record's body, parsed). */
export type KeyboardAdvert = {
addressType: number;
/** "aa:bb:cc:dd:ee:ff", most significant byte first. */
address: string;
rssi: number;
name: string;
/** Advertises the HID service, or a HID appearance. */
hid: boolean;
};
/** ADVERT body: addrType, addr[6] (LSB first), RSSI, event type, AD length, AD structures. */
export function parseKeyboardAdvert(body: Uint8Array): KeyboardAdvert | null {
if (body.length < 10 || body[0]! > 3) return null;
let name = "";
let hid = false;
for (let i = 10; i < body.length;) {
const n = body[i++]!;
if (n === 0 || i + n > body.length) break;
const type = body[i]!;
if (type === 8 || type === 9) name = decodeUtf8(body.subarray(i + 1, i + n));
// 16-bit service lists (incomplete / complete): 0x1812 is HID.
if (type === 2 || type === 3) {
for (let j = i + 1; j + 1 < i + n; j += 2) if (body[j] === 0x12 && body[j + 1] === 0x18) hid = true;
}
// Appearance 0x03C0..0x03FF is the HID category (0x03C1 keyboard); some
// keyboards advertise that without the service list.
if (type === 0x19 && n >= 3 && body[i + 2] === 0x03 && body[i + 1]! >= 0xc0) hid = true;
i += n;
}
return {
addressType: body[0]!,
address: formatKeyboardAddress(body.subarray(1, 7)),
rssi: (body[7]! << 24) >> 24,
name,
hid,
};
}
/**
* Fold a later record for the same advertiser into an earlier one. An active
* scan reports the advertisement and its scan response separately and the
* name usually only rides in the latter: keep a name once seen, HID once
* seen, and the best signal.
*/
export function mergeKeyboardAdverts(a: KeyboardAdvert, b: KeyboardAdvert): KeyboardAdvert {
return { ...a, rssi: Math.max(a.rssi, b.rssi), name: a.name || b.name, hid: a.hid || b.hid };
}
/** Controller byte order (LSB first) to the usual "aa:bb:cc:dd:ee:ff". */
export function formatKeyboardAddress(lsbFirst: Uint8Array): string {
return Array.from(lsbFirst).reverse().map((b) => b.toString(16).padStart(2, "0")).join(":");
}
/** "aa:bb:cc:dd:ee:ff" to the controller's LSB-first bytes, or null if malformed. */
export function parseKeyboardAddress(text: string): Uint8Array | null {
if (!/^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/i.test(text)) return null;
return Uint8Array.from(text.split(":").reverse().map((part) => parseInt(part, 16)));
}
/** Lenient UTF-8 decode (advertised names); no TextDecoder in every runtime this loads in. */
function decodeUtf8(bytes: Uint8Array): string {
let out = "";
for (let i = 0; i < bytes.length;) {
const b = bytes[i++]!;
let code = b;
let extra = 0;
if (b >= 0xf0 && b < 0xf8) { code = b & 0x07; extra = 3; }
else if (b >= 0xe0) { code = b & 0x0f; extra = 2; }
else if (b >= 0xc0) { code = b & 0x1f; extra = 1; }
else if (b >= 0x80) { out += "�"; continue; }
if (i + extra > bytes.length) { out += "�"; break; }
let valid = true;
for (let k = 0; k < extra; k++) {
const c = bytes[i + k]!;
if ((c & 0xc0) !== 0x80) { valid = false; break; }
code = (code << 6) | (c & 0x3f);
}
if (!valid || code > 0x10ffff) { out += "�"; continue; }
i += extra;
if (code === 0) continue;
out += String.fromCodePoint(code);
}
return out;
}
+131
View File
@@ -0,0 +1,131 @@
/**
* The keyboard bridge as the app uses it: one KeyboardBridge for the life of
* the app, fed by whichever glasses session is live, its remembered keyboard
* kept in the settings store, and its key transitions turned into KeyEvents.
* The dashboard controller reports the link coming and going and takes the
* keys; the Settings app drives pairing through `bridge`.
*/
import { addKeyboardEventListener, keyboardLinkSession, sendKeyboardControlRecord } from "../../native/keyboard-link";
import { getStringSetting, setStringSetting } from "../../native/settings-store";
import { KeyboardBridge, type KeyboardBridgeSnapshot, type SavedKeyboard } from "./bridge";
import { KeyTranslator, type KeyEvent } from "./keys";
declare const java: any;
declare const arc4random_uniform: ((bound: number) => number) | undefined;
/** JSON of the remembered keyboard ({ address, addressType, name }), or "" for none. */
const SAVED_KEYBOARD_KEY = "keyboard.saved";
export type KeyboardServiceHost = {
onKey(event: KeyEvent): void;
/** Routine lines only (failed background reconnects); the rest go to the device log directly. */
log(line: string): void;
/** Whether an absent keyboard is worth looking for now (see KeyboardBridgeHost). */
shouldReconnect(): boolean;
};
function loadSavedKeyboard(): SavedKeyboard | null {
try {
const raw = getStringSetting(SAVED_KEYBOARD_KEY, "");
if (!raw) return null;
const value = JSON.parse(raw);
if (typeof value?.address !== "string" || typeof value?.addressType !== "number") return null;
return { address: value.address, addressType: value.addressType, name: typeof value.name === "string" ? value.name : "" };
} catch {
return null;
}
}
/** Passkey entry only protects the pairing if the passkey can't be guessed. */
function randomPasskey(): number {
try {
if (global.isAndroid) return new java.security.SecureRandom().nextInt(1_000_000);
if (typeof arc4random_uniform === "function") return arc4random_uniform(1_000_000);
} catch {
// Fall through to the weaker source rather than failing the pairing.
}
return Math.floor(Math.random() * 1_000_000);
}
class KeyboardService {
private host: KeyboardServiceHost | null = null;
private session: unknown = null;
private offEvents: (() => void) | null = null;
private readonly listeners = new Set<() => void>();
private readonly translator = new KeyTranslator({ emit: (event) => this.host?.onKey(event) });
readonly bridge = new KeyboardBridge({
send: (record) => {
const session = this.session;
if (!session) return false;
try {
return sendKeyboardControlRecord(session, record, `op=${record[3]}`);
} catch {
return false;
}
},
loadSaved: loadSavedKeyboard,
storeSaved: (saved) => setStringSetting(SAVED_KEYBOARD_KEY, saved ? JSON.stringify(saved) : ""),
onKeys: (events) => this.translator.handle(events),
onKeyboardGone: () => this.translator.reset(),
onChanged: () => {
for (const listener of [...this.listeners]) listener();
},
// Pairing and setup are rare and are what a failure report needs, so
// they always reach the device log. Nothing here ever includes a key.
log: (line, routine) => {
if (routine) this.host?.log(line);
else console.log(`[keyboard] ${line}`);
},
randomPasskey,
shouldReconnect: () => this.host?.shouldReconnect() ?? true,
});
setHost(host: KeyboardServiceHost): void {
this.host = host;
}
snapshot(): KeyboardBridgeSnapshot {
return this.bridge.snapshot();
}
/** Called on every bridge state change. Returns an unsubscribe function. */
subscribe(listener: () => void): () => void {
this.listeners.add(listener);
return () => this.listeners.delete(listener);
}
/** The glasses came into use (the display woke): look for an absent keyboard now. */
retryNow(): void {
this.bridge.retryNow();
}
/** A G2 session on firmware with the bridge is up. Idempotent. */
linkReady(): void {
const session = keyboardLinkSession();
if (!session) return;
if (session !== this.session) {
// The native session object is rebuilt across reconnects.
this.offEvents?.();
this.session = session;
this.offEvents = addKeyboardEventListener(session, (body) => this.bridge.accept(body));
}
this.bridge.linkReady();
}
/**
* The session can't host the keyboard any more. `release` asks the firmware
* to let the keyboard go first, for when the link itself stays up (the
* glasses went into their case, or the app is disconnecting on purpose).
* Idempotent.
*/
linkLost(release = false): void {
if (release) this.bridge.linkClosing();
this.bridge.linkLost();
this.offEvents?.();
this.offEvents = null;
this.session = null;
}
}
export const keyboardService = new KeyboardService();
+21
View File
@@ -19,6 +19,7 @@ declare const FaceclawKitFaceclawCompassListener: any;
declare const FaceclawKitFaceclawImuListener: any;
declare const FaceclawKitIosAmbientLightListener: any;
declare const FaceclawKitIosMicStatusListener: any;
declare const FaceclawKitIosKeyboardEventListener: any;
export type CommunicatorPhase =
@@ -198,6 +199,13 @@ class MicStatusListener extends NSObject {
onNsDataMicStatusBodyArm(body: NSData, arm: string): void { this.handler(fromData(body), String(arm ?? "")); }
}
@NativeClass()
class KeyboardEventListener extends NSObject {
static ObjCProtocols = [FaceclawKitIosKeyboardEventListener];
handler!: (body: Uint8Array) => void;
onNsDataKeyboardEventBody(body: NSData): void { this.handler(fromData(body)); }
}
/**
* The iOS twin of the Android communicator bridge: the same public API over
* the shared Kotlin session (FaceclawKitIosGlassesSession, CoreBluetooth
@@ -803,6 +811,19 @@ export class FaceclawCommunicatorBridge {
toData(new Uint8Array(record)), label, Boolean(rightTemple), Boolean(leftTemple)));
}
/** Raw field-131 keyboard-bridge records, in arrival order, on the main queue. */
addKeyboardEventListener(listener: (body: Uint8Array) => void): () => void {
const proxy = KeyboardEventListener.new() as KeyboardEventListener;
proxy.handler = listener;
const handle = this.communicator.addKeyboardEventListenerNsDataListener(proxy);
return () => { this.communicator.removeKeyboardEventListenerListener(handle); };
}
/** Queue a CFW keyboard-bridge control for the right temple; false when nothing was queued. */
sendFaceclawKeyboardControl(record: Uint8Array, label: string): boolean {
return Boolean(this.communicator.sendFaceclawKeyboardControlRecordLabel(toData(new Uint8Array(record)), label));
}
/**
* Every audio-characteristic packet, whatever enabled the mics, on the
* main queue. Passive: sends nothing and doesn't affect capture.
+24
View File
@@ -0,0 +1,24 @@
import { FaceclawCommunicatorBridge } from "./faceclaw-communicator.ios";
/** The iOS twin of keyboard-link.ts, over the running shared-Kotlin session. */
export function keyboardLinkSession(): unknown {
return FaceclawCommunicatorBridge.getActive();
}
/** Queue a control record for the right temple; false when the session wasn't ready and nothing was queued. */
export function sendKeyboardControlRecord(session: unknown, record: Uint8Array, label: string): boolean {
return (session as FaceclawCommunicatorBridge).sendFaceclawKeyboardControl(record, label);
}
/** Raw keyboard-bridge records (undecoded, possibly fragments), in arrival order. Returns an unsubscribe function. */
export function addKeyboardEventListener(session: unknown, listener: (body: Uint8Array) => void): () => void {
const unsubscribe = (session as FaceclawCommunicatorBridge).addKeyboardEventListener(listener);
return () => {
try {
unsubscribe();
} catch {
// The session may have been closed during a reconnect.
}
};
}
+40
View File
@@ -0,0 +1,40 @@
import { toJavaBytes } from "./cloud-stt";
import { toUint8Array } from "../util/array-util";
declare const com: any;
/**
* Platform plumbing for the CFW keyboard bridge (app/g2/keyboard/): the running
* session to send field-130 controls on and to hear field-131 records from.
* The session is opaque and is a different object after a reconnect.
*/
export function keyboardLinkSession(): unknown {
if (!global.isAndroid) return null;
try {
return com.faceclaw.app.FaceclawBleCommunicator.getActive();
} catch {
return null;
}
}
/** Queue a control record for the right temple; false when the session wasn't ready and nothing was queued. */
export function sendKeyboardControlRecord(session: unknown, record: Uint8Array, label: string): boolean {
return (session as any).sendFaceclawKeyboardControl(toJavaBytes(record), label) !== false;
}
/** Raw keyboard-bridge records (undecoded, possibly fragments), in arrival order. Returns an unsubscribe function. */
export function addKeyboardEventListener(session: unknown, listener: (body: Uint8Array) => void): () => void {
const communicator = session as any;
const proxy = new com.faceclaw.app.FaceclawKeyboardEventListener({
onKeyboardEvent: (body: any) => listener(toUint8Array(body)),
});
communicator.addKeyboardEventListener(proxy);
return () => {
try {
communicator.removeKeyboardEventListener(proxy);
} catch {
// The old communicator instance may be gone after a reconnect.
}
};
}
+9
View File
@@ -103,6 +103,7 @@ import { openSettingsSubMenu, SettingsPanelLayer, type SettingsSection } from ".
import { uiFontPickerMenuItem } from "../font-picker";
import { NotificationFilterLayer } from "../notification-filter";
import { compatibleModelDiscoveryMenuItem } from "../openai-compatible-model-picker";
import { keyboardSettingsMenuItem } from "../keyboard-settings";
import { isVeniceApiBaseUrl } from "../../native/openai-chat";
/** The Settings section the Notifications app's "Settings" menu item opens. */
@@ -242,6 +243,14 @@ function settingsSections(): SettingsSection[] {
],
renderDetail: renderWatchStatus,
},
// A Bluetooth keyboard paired with the glasses themselves (the G2's
// custom firmware hosts it; app/g2/keyboard/). Hidden rather than left
// out: the Settings window can be open across a change of glasses.
{
label: "Keyboard",
items: [keyboardSettingsMenuItem()],
hidden: () => glassesTypeSetting.get() !== "g2",
},
{
label: "Developer",
items: [
+30 -2
View File
@@ -28,6 +28,13 @@ export type SettingsSection = {
height: number;
ctx: LayerContext;
}) => number | void;
/**
* Leave the section out of the list while this returns true. Re-read on
* every paint and input, for a section that only applies with some other
* setting (the paired glasses' type): the Settings window outlives changes
* to those.
*/
hidden?: () => boolean;
};
const LEFT_W = 150;
@@ -66,7 +73,7 @@ export class SettingsPanelLayer implements Layer {
constructor(private readonly sections: SettingsSection[]) {
this.leftMenu = new Menu<SettingsSection>({
items: sections,
items: sections.filter((section) => !section.hidden?.()),
wrap: true,
rowGap: ROW_GAP,
highlight: { radius: 6 },
@@ -108,9 +115,28 @@ export class SettingsPanelLayer implements Layer {
return this.leftMenu.selectedItem ?? this.sections[0]!;
}
/**
* Bring the left column in line with which sections are hidden now. The
* highlight stays on its section; if that one just went away it moves to
* the list's start, with focus back in the left column.
*/
private syncSections(): void {
const visible = this.sections.filter((section) => !section.hidden?.());
const shown = this.leftMenu.items;
if (visible.length === shown.length && visible.every((section, index) => section === shown[index])) return;
const selected = this.leftMenu.selectedItem;
const index = selected ? visible.indexOf(selected) : -1;
this.leftMenu.setItems(visible, Math.max(0, index));
if (index < 0) {
this.focus = "left";
this.resetRight();
}
}
/** Select a left-column section by label (deep link, e.g. from an app's menu). */
focusSection(label: string): void {
const index = this.sections.findIndex((section) => section.label === label);
this.syncSections();
const index = this.leftMenu.items.findIndex((section) => section.label === label);
if (index < 0) return;
this.leftMenu.select(index);
this.focus = "left";
@@ -123,6 +149,7 @@ export class SettingsPanelLayer implements Layer {
const { width, height, padding } = viewport;
const image = new GrayImage(width, height, 0);
const appFocused = ctx.stack.isFocused();
this.syncSections();
const section = this.section();
const rightItems = section.items;
this.rightMenu.setItems(rightItems);
@@ -228,6 +255,7 @@ export class SettingsPanelLayer implements Layer {
}
async handleInput(event: InputEvent, ctx: LayerContext): Promise<void> {
this.syncSections();
const scroll = scrollEventFor(event);
if (this.focus === "left") {
if (scroll) {
+232
View File
@@ -0,0 +1,232 @@
import { getDefaultSmallFont } from "../graphics/ui-fonts";
import type { KeyboardBridgeSnapshot } from "../g2/keyboard/bridge";
import type { KeyboardAdvert } from "../g2/keyboard/protocol";
import { keyboardService } from "../g2/keyboard/service";
import { ConfigSettingString, textSettingMenuItem } from "./dashboard-settings";
import type { LayerContext } from "./layers";
import { drawRightValueMenuItem, MenuLayer, type MenuItem } from "./menu";
/**
* Settings > Keyboard: pairing a Bluetooth keyboard with the glasses (the
* CFW keyboard bridge, app/g2/keyboard/). The keyboard pairs with the
* glasses, not the phone, so all of it happens here, on the glasses: scan,
* pick, and for a keyboard that wants one, the passkey to type on it.
*/
/** The code a keyboard with a display shows, typed on the phone. Scratch, not a preference. */
const pairingCodeSetting = new ConfigSettingString({
id: "keyboardPairingCode",
storageKey: "keyboard.pairingCode",
label: "Code on keyboard",
defaultValue: "",
normalize: (value) => (value ?? "").replace(/\D/g, "").slice(0, 6),
});
const sixDigits = (value: number): string => {
const text = String(value).padStart(6, "0");
return `${text.slice(0, 3)} ${text.slice(3)}`;
};
function advertLabel(advert: KeyboardAdvert): string {
const name = advert.name.trim() || advert.address;
return name.length > 30 ? `${name.slice(0, 27)}...` : name;
}
/** One line saying where the keyboard stands, for the Settings row and the menu's first row. */
export function keyboardStatusText(snapshot: KeyboardBridgeSnapshot): string {
const name = snapshot.activeName || snapshot.saved?.name || "keyboard";
switch (snapshot.state) {
case "unavailable":
return snapshot.saved ? "Glasses not connected" : "Not set up";
case "scanning":
return "Scanning...";
case "connecting":
return `Connecting to ${name}...`;
case "pairing":
return `Pairing with ${name}...`;
case "configuring":
return `Setting up ${name}...`;
case "connected":
return `Connected: ${name}`;
case "error":
return snapshot.error || "Failed";
default:
if (snapshot.waiting) return `Waiting for ${name}`;
return snapshot.saved ? `${name} (disconnected)` : "Not set up";
}
}
/** The short form for the right edge of the Settings row. */
function keyboardStatusBrief(snapshot: KeyboardBridgeSnapshot): string {
switch (snapshot.state) {
case "connected":
return "Connected";
case "scanning":
return "Scanning";
case "connecting":
case "pairing":
case "configuring":
return "Connecting";
case "error":
return "Failed";
case "unavailable":
return snapshot.saved ? "Offline" : "Off";
default:
return snapshot.waiting ? "Waiting" : snapshot.saved ? "Disconnected" : "Off";
}
}
const info = (label: string): MenuItem => ({ label, disabled: true, onSelect: () => {} });
class KeyboardSettingsLayer extends MenuLayer {
private unsubscribe: (() => void) | null = null;
private showOthers = false;
/** What kind of rows are showing; a change moves the highlight to the first row that does something. */
private shape = "";
constructor(viewport: { width: number; height: number }) {
super("Bluetooth keyboard", [], {
x: "center",
y: 8,
width: Math.min(320, viewport.width - 40),
minHeight: Math.min(160, viewport.height - 40),
maxHeight: Math.min(240, viewport.height - 40),
depth: 4,
});
}
open(ctx: LayerContext): void {
ctx.stack.push(this);
this.updateRows();
this.unsubscribe = keyboardService.subscribe(() => {
this.updateRows();
ctx.actions.requestRender();
});
}
onRemoved(): void {
this.unsubscribe?.();
this.unsubscribe = null;
}
/** Run a bridge command; its failure shows up in the snapshot, which repaints the rows. */
private run(action: () => Promise<unknown>): void {
void action().catch(() => {});
}
private updateRows(): void {
const snapshot = keyboardService.snapshot();
const bridge = keyboardService.bridge;
const rows: MenuItem[] = [info(keyboardStatusText(snapshot))];
let shape: string = snapshot.state;
const scanRow = (label: string): MenuItem => ({
label,
disabled: snapshot.busy,
onSelect: () => {
this.showOthers = false;
this.run(() => bridge.scan());
},
});
if (snapshot.state === "unavailable") {
rows.push(info("Connect G2 glasses to pair one."));
if (snapshot.saved) rows.push({ label: `Forget ${snapshot.saved.name || "keyboard"}`, onSelect: () => this.run(() => bridge.forget()) });
} else if (snapshot.pairing) {
const pairing = snapshot.pairing;
shape = `pairing:${pairing.kind}`;
if (pairing.kind === "display") {
rows.push(info(`Type ${sixDigits(pairing.pin)} on the keyboard,`), info("then press Enter."));
} else if (pairing.kind === "compare") {
rows.push(
info(`Does the keyboard show ${sixDigits(pairing.value)}?`),
{ label: "Yes, pair", onSelect: () => this.run(() => bridge.answerCompare(true)) },
{ label: "No", onSelect: () => this.run(() => bridge.answerCompare(false)) },
);
} else {
rows.push(
info("Enter the code the keyboard shows."),
textSettingMenuItem(pairingCodeSetting),
{
label: "Pair with this code",
disabled: () => pairingCodeSetting.get().length !== 6,
onSelect: () => {
const code = pairingCodeSetting.get();
pairingCodeSetting.set("");
this.run(() => bridge.answerPasskey(parseInt(code, 10)));
},
},
);
}
rows.push({ label: "Cancel pairing", onSelect: () => this.run(() => bridge.disconnect()) });
} else if (snapshot.state === "connecting" || snapshot.state === "pairing" || snapshot.state === "configuring") {
rows.push({ label: "Cancel", onSelect: () => this.run(() => bridge.disconnect()) });
} else if (snapshot.state === "scanning" || (snapshot.scanResults.length > 0 && snapshot.state !== "connected")) {
shape = "results";
const hid = snapshot.scanResults.filter((advert) => advert.hid);
const others = snapshot.scanResults.filter((advert) => !advert.hid);
const pick = (advert: KeyboardAdvert): MenuItem => ({
label: advertLabel(advert),
disabled: snapshot.busy,
onSelect: () => {
this.run(() => bridge.connect({ address: advert.address, addressType: advert.addressType, name: advert.name.trim() || advert.address }));
},
});
rows.push(...hid.map(pick));
if (!hid.length && snapshot.state !== "scanning") rows.push(info("No keyboards found."), info("Put it in pairing mode."));
if (others.length && this.showOthers) rows.push(...others.map(pick));
else if (others.length) {
rows.push({
label: `Show ${others.length} other device${others.length === 1 ? "" : "s"}`,
onSelect: (ctx) => {
this.showOthers = true;
this.updateRows();
ctx.actions.requestRender();
},
});
}
if (snapshot.state !== "scanning") rows.push(scanRow("Scan again"));
if (snapshot.saved && snapshot.state !== "scanning") {
rows.push({ label: `Reconnect ${snapshot.saved.name || "keyboard"}`, disabled: snapshot.busy, onSelect: () => this.run(() => bridge.reconnect()) });
}
} else if (snapshot.state === "connected") {
rows.push(
{ label: "Disconnect", onSelect: () => this.run(() => bridge.disconnect()) },
{ label: "Forget this keyboard", onSelect: () => this.run(() => bridge.forget()) },
scanRow("Pair a different keyboard"),
);
} else if (snapshot.saved) {
shape = snapshot.waiting ? "waiting" : "saved";
rows.push({ label: "Reconnect now", disabled: snapshot.busy, onSelect: () => this.run(() => bridge.reconnect()) });
if (snapshot.waiting) rows.push({ label: "Stop reconnecting", onSelect: () => this.run(() => bridge.disconnect()) });
rows.push(
{ label: "Forget this keyboard", onSelect: () => this.run(() => bridge.forget()) },
scanRow("Pair a different keyboard"),
);
} else {
shape = "empty";
rows.push(info("Put the keyboard in pairing mode,"), info("then scan."), scanRow("Scan for keyboards"));
}
const firstAction = rows.findIndex((row) => row.disabled !== true);
if (shape !== this.shape) {
this.shape = shape;
this.setItems(rows, Math.max(0, firstAction));
} else {
this.setItems(rows);
}
}
}
/** The Settings row that opens the keyboard menu. */
export function keyboardSettingsMenuItem(): MenuItem {
return {
label: "Bluetooth keyboard",
description:
"Pair a Bluetooth keyboard with the glasses. It types into Terminal sessions, and its arrow keys, Enter and Escape work everywhere as scroll, select and back.",
onSelect: (ctx) => new KeyboardSettingsLayer(ctx.stack.getBaseSize()).open(ctx),
render: ({ image, x, y, width }) => {
drawRightValueMenuItem(image, getDefaultSmallFont(), x, y, width, "Bluetooth keyboard", keyboardStatusBrief(keyboardService.snapshot()));
},
};
}
+24
View File
@@ -17,6 +17,7 @@ import {
isWatchInput,
makeInputEvent,
} from "../gestures";
import type { KeyEvent } from "../../g2/keyboard/keys";
import { Layer, LayerActions, LayerContext, LayerStack, noopLayerActions } from "../layers";
import { CONTEXT_MENU_DIM, MenuLayer, type MenuItem } from "../menu";
import { VoiceInputLayer, type VoiceSendTarget } from "./voice-input";
@@ -192,6 +193,14 @@ export type ShellWindow = {
* only windows that consume typed text (the terminal) implement it.
*/
receiveTextInput?: (text: string, options?: { submit?: boolean }) => void;
/**
* Take a key from a hardware keyboard (app/g2/keyboard) as a key. Optional:
* only windows that give keys a meaning of their own (the terminal)
* implement it, and they get every key while they have input focus,
* presses and releases alike. For the rest the controller turns the few
* navigation keys into ring gestures (navigationGestureForKey).
*/
handleKeyEvent?: (event: KeyEvent) => void;
/** Foreground state changed: this window's surface is (not) the visible one. */
setForeground?: (foreground: boolean) => void;
/**
@@ -1606,6 +1615,21 @@ class Shell {
this.foregroundWindow()?.receiveTextInput?.(text, options);
}
/**
* Offer a hardware-keyboard key to the window that has input focus. True
* when that window takes keys (ShellWindow.handleKeyEvent) and got this
* one; false when the key is the caller's to interpret: the screen is off,
* the sidebar or a shell overlay has focus, or the window has no use for
* keys. Typing counts as activity for the screen timeout.
*/
receiveKeyEvent(event: KeyEvent): boolean {
const window = this.inputTargetWindow();
if (!window?.handleKeyEvent) return false;
if (event.phase === "down") this.lastInputAtMs = Date.now();
window.handleKeyEvent(event);
return true;
}
/**
* Open the voice dialog aimed at the foreground window. Called when the
* user picks Voice input from the system menu (or an app asks via a
+19
View File
@@ -28,6 +28,8 @@ export type WorkerAppMessage =
| { type: "close-window"; windowId: string }
| { type: "input"; windowId: string; event: unknown; frameId: number; focused: boolean }
| { type: "text-input"; windowId: string; text: string; submit?: boolean }
/** A hardware-keyboard key (a KeyEvent), for windows opened with acceptsKeys. */
| { type: "key"; windowId: string; event: unknown; focused: boolean }
| { type: "render"; windowId: string; focused: boolean }
| { type: "foreground"; windowId: string; foreground: boolean; focused: boolean }
/**
@@ -81,6 +83,8 @@ export type WorkerAppReply =
focus?: boolean;
/** Window height: the standard 288px band ("min", default) or full screen ("max"). */
heightMode?: WindowHeightMode;
/** Send the window hardware-keyboard keys (see WorkerWindowSpec). */
acceptsKeys?: boolean;
}
| {
/**
@@ -196,6 +200,13 @@ export type WorkerWindowSpec = {
* of all four directions in every window state (see ShellWindow).
*/
acceptsDirectional?: boolean;
/**
* Deliver hardware-keyboard keys to the worker as "key" messages while the
* window has input focus, instead of the navigation-gesture fallback. The
* worker then owns what every key means in every window state, navigation
* included (see ShellWindow.handleKeyEvent).
*/
acceptsKeys?: boolean;
};
export type WorkerAppHostOptions = {
@@ -335,6 +346,7 @@ export class WorkerAppHost {
iconGlyph: message.iconGlyph,
focus: message.focus,
heightMode: message.heightMode,
acceptsKeys: message.acceptsKeys,
});
break;
case "set-height-mode":
@@ -522,6 +534,13 @@ export class WorkerAppHost {
receiveTextInput: (text, options) => {
this.post({ type: "text-input", windowId: spec.windowId, text, ...(options?.submit === undefined ? {} : { submit: options.submit }) });
},
...(spec.acceptsKeys
? {
handleKeyEvent: (event) => {
this.post({ type: "key", windowId: spec.windowId, event, focused: shell.isWindowFocused(spec.windowId) });
},
}
: {}),
setForeground: (foreground) => {
this.options.setSurfaceVisible(surfaceId, foreground);
if (foreground) {
@@ -0,0 +1,10 @@
package com.faceclaw.app
interface FaceclawKeyboardEventListener {
/**
* One CFW keyboard-bridge record (settings field 131) from the glasses: the raw
* ['K','B',ver,kind,...] bytes, possibly one fragment of a longer record. Decoded and
* reassembled on the TS side (app/g2/keyboard/protocol.ts). Delivered in arrival order.
*/
fun onKeyboardEvent(body: ByteArray?): Unit
}
@@ -119,6 +119,19 @@ class BleProtocol {
*/
const val FACECLAW_ALS_REPORT_FIELD: Int = 105
/**
* CFW keyboard bridge (Faceclaw/39): the master temple hosts one BLE HID keyboard. The
* host writes ['K','B',ver,op,request,epoch,...] controls as settings field 130; results,
* pairing prompts and the keyboard's raw input reports come back as commandId=3 pushes
* carrying field 131 (['K','B',ver,kind,...], decoded in app/g2/keyboard/protocol.ts).
*/
const val FACECLAW_KEYBOARD_CONTROL_FIELD: Int = 130
const val FACECLAW_KEYBOARD_EVENT_FIELD: Int = 131
/** Fixed header of a field-131 record; fragments follow it. */
const val FACECLAW_KEYBOARD_EVENT_HEADER: Int = 24
const val FACECLAW_WAKE_OP_ACQUIRE: Int = 1
const val FACECLAW_WAKE_OP_RELEASE: Int = 2
@@ -724,6 +737,42 @@ class BleProtocol {
return body
}
/**
* Wrap an already-encoded ['K','B',ver,op,...] keyboard control as a settings write
* carrying CFW field 130. Magic zero, like the other private controls: the answer is a
* field-131 record naming the control's request id, not the settings ACK.
*/
@JvmStatic
fun buildFaceclawKeyboardControl(record: ByteArray): ByteArray {
return concat(
CollectionUtils.listOf(
encodeVarintField(1, 1),
encodeVarintField(2, 0),
encodeBytesField(FACECLAW_KEYBOARD_CONTROL_FIELD, record),
)
)
}
/**
* Extract a CFW keyboard record (field 131) from a settings frame, or null when the frame
* carries none. Only the ['K','B'] prelude and the fixed header's length are checked
* here; the TS side validates the version and decodes the rest.
*/
@JvmStatic
fun parseFaceclawKeyboardEvent(pb: ByteArray?): ByteArray? {
if (pb == null) {
return null
}
val body = readFieldBytes(stripTrailingCrc(pb), FACECLAW_KEYBOARD_EVENT_FIELD)
if (
body == null || body.size < FACECLAW_KEYBOARD_EVENT_HEADER ||
body[0].toInt() != 75 || body[1].toInt() != 66
) {
return null
}
return body
}
/**
* Return the raw CFW ambient-light report from a sid-0x09 frame, or null when this is an
* ordinary settings frame. Only the 65.toByte(),76.toByte(),version prelude is validated
@@ -321,6 +321,24 @@ class MessageBuilder {
)
}
/**
* CFW keyboard control (settings field 130). Always the right arm: only the master temple
* acts on it, and a copy sent down each arm would run the control twice.
*/
fun faceclawKeyboardControl(record: ByteArray, label: String): OutboundMessage {
return OutboundMessage(
"keyboard-control",
"keyboard control $label",
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawKeyboardControl(record),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun faceclawWearQuery(leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"wear-query-control",
@@ -583,6 +583,22 @@ internal fun GlassesSessionCore.emitMicStatus(body: ByteArray, address: String)
}
}
internal fun GlassesSessionCore.emitKeyboardEvent(body: ByteArray) {
if (keyboardEventListeners.isEmpty()) {
return
}
val copy = body.copyOf()
host.postToMain {
for (keyboardListener in keyboardEventListeners) {
try {
keyboardListener.onKeyboardEvent(copy)
} catch (t: Throwable) {
logWarn("keyboard event listener failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitAudioMonitorPacket(data: ByteArray, arm: String, arrivalMs: Long) {
if (audioMonitorListeners.isEmpty()) {
return
@@ -131,6 +131,7 @@ class GlassesSessionCore(
internal val compassSubscriptions = CopyOnWriteList<CompassSubscription>(platform)
internal val ambientLightListeners = CopyOnWriteList<FaceclawAmbientLightListener>(platform)
internal val micStatusListeners = CopyOnWriteList<FaceclawMicStatusListener>(platform)
internal val keyboardEventListeners = CopyOnWriteList<FaceclawKeyboardEventListener>(platform)
internal val audioMonitorListeners = CopyOnWriteList<FaceclawAudioPacketListener>(platform)
@Volatile internal var running = false
@Volatile internal var userDisconnectRequested = false
@@ -1388,6 +1389,39 @@ class GlassesSessionCore(
return true
}
fun addKeyboardEventListener(listener: FaceclawKeyboardEventListener?) {
if (listener != null) {
keyboardEventListeners.add(listener)
}
}
fun removeKeyboardEventListener(listener: FaceclawKeyboardEventListener?) {
if (listener != null) {
keyboardEventListeners.remove(listener)
}
}
/**
* Queue a CFW keyboard-bridge control (['K','B',ver,op,request,epoch,...]) as a settings
* field-130 write to the right temple. Fire-and-forget: the firmware answers with field-131
* records, which arrive through addKeyboardEventListener. Returns false when nothing was
* queued (not a G2, no session, or a malformed record).
*/
fun sendFaceclawKeyboardControl(record: ByteArray?, label: String): Boolean {
if (!isG2 || record == null || record.size < 8) {
return false
}
monitor.withLock {
if (!running || !sessionReady) {
logLine("skip keyboard control ($label); session not ready")
return false
}
pendingMessages.addLast(messageBuilder.faceclawKeyboardControl(record, label))
}
interruptibleSleep.interrupt()
return true
}
/**
* Forward render-characteristic audio packets to the listener WITHOUT
* sending the stock EvenHub audio-control enable. Used for the CFW
@@ -1894,6 +1928,18 @@ class GlassesSessionCore(
}
logDebug("onNotification: address=" + address + " characteristicUuid=" + characteristicUuid + " data.length=" + data.size)
val frame = BleProtocol.parseFrame(data)
if (frame.ok && frame.sid == BleProtocol.SID_UI_SETTING) {
// CFW keyboard-bridge records (field 131) come from whichever temple hosts the
// keyboard. They are their own stream: neither an ACK nor glasses input, and the
// once-a-second status record among them must not count as user activity (which
// would hold off battery polling).
val keyboardEvent = BleProtocol.parseFaceclawKeyboardEvent(frame.pb)
if (keyboardEvent != null) {
monitor.withLock { lastIncomingAtMs = now() }
emitKeyboardEvent(keyboardEvent)
return
}
}
val decodedWearState = BleProtocol.parseWearState(frame)
val compassEvent = if (address.equals(rightAddress, ignoreCase = true))
BleProtocol.parseCompassEvent(frame)
@@ -34,6 +34,11 @@ interface IosMicStatusListener {
fun onNsDataMicStatus(body: NSData, arm: String)
}
/** CFW keyboard-bridge records (the raw field-131 record) as NSData. Main queue. */
interface IosKeyboardEventListener {
fun onNsDataKeyboardEvent(body: NSData)
}
/**
* ObjC-facing facade over the shared [GlassesSessionCore] for the NativeScript app: the iOS
* counterpart of Android's FaceclawBleCommunicator with the same method names. GATT goes
@@ -230,6 +235,20 @@ class IosGlassesSession internal constructor(
return adapter
}
fun addKeyboardEventListenerNsData(listener: IosKeyboardEventListener): FaceclawKeyboardEventListener {
val adapter = object : FaceclawKeyboardEventListener {
override fun onKeyboardEvent(body: ByteArray?) =
listener.onNsDataKeyboardEvent((body ?: ByteArray(0)).data())
}
core.addKeyboardEventListener(adapter)
return adapter
}
fun removeKeyboardEventListener(listener: FaceclawKeyboardEventListener?) = core.removeKeyboardEventListener(listener)
fun sendFaceclawKeyboardControl(record: NSData?, label: String): Boolean =
core.sendFaceclawKeyboardControl(record?.byteArray(), label)
/** Every audio-characteristic packet, whether or not a capture is active (passive; sends nothing). */
fun addAudioMonitorListenerNsData(listener: IosAudioPacketListener): FaceclawAudioPacketListener {
val adapter = object : FaceclawAudioPacketListener {
+22 -1
View File
@@ -2,7 +2,7 @@ const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
function settingsEnv(initialUrl = '', initialModel = 'openai-compatible') {
function settingsEnv(initialUrl = '', initialModel = 'openai-compatible', glassesType = 'g2') {
let url = initialUrl;
let model = initialModel;
let webSearch = false;
@@ -31,6 +31,7 @@ function settingsEnv(initialUrl = '', initialModel = 'openai-compatible') {
assistantHermesUrlSetting: { ...dummySetting, id: 'assistant-hermes-url', label: 'Hermes URL' },
assistantHermesKeySetting: { ...dummySetting, id: 'assistant-hermes-key', label: 'Hermes key' },
veniceWebSearchSetting: searchSetting,
glassesTypeSetting: { ...dummySetting, id: 'glasses-type', get: () => (typeof glassesType === 'function' ? glassesType() : glassesType) },
enumSettingMenuItem: row,
textSettingMenuItem: row,
toggleSettingMenuItem: row,
@@ -73,6 +74,7 @@ function settingsEnv(initialUrl = '', initialModel = 'openai-compatible') {
},
'../font-picker': { uiFontPickerMenuItem: () => ({ label: 'Font' }) },
'../notification-filter': { NotificationFilterLayer: class {} },
'../keyboard-settings': { keyboardSettingsMenuItem: () => ({ label: 'Bluetooth keyboard' }) },
'../openai-compatible-model-picker': {
compatibleModelDiscoveryMenuItem: () => ({ label: 'Discover models' }),
},
@@ -83,6 +85,7 @@ function settingsEnv(initialUrl = '', initialModel = 'openai-compatible') {
assert.ok(section);
return {
section,
sections: panel.sections,
labels: () => section.items.map(item => item.label),
setUrl: value => { url = value; },
setModel: value => { model = value; },
@@ -148,3 +151,21 @@ test('OpenAI-compatible rows appear only while OpenAI-compatible is the selected
const labels = env.labels();
assert.equal(labels.indexOf('Compatible API URL'), labels.indexOf('Assistant model') + 1, 'compatible rows follow the model row');
});
test('the Keyboard section, with its pairing row, follows the glasses type while Settings stays open', () => {
let glassesType = 'g1';
const sections = settingsEnv('', 'openai-compatible', () => glassesType).sections;
const labels = sections.map(section => section.label);
// Always in the list, between the other input devices and the developer
// options; whether it shows is asked again on every paint.
assert.equal(labels.indexOf('Keyboard'), labels.indexOf('Watch') + 1);
const keyboard = sections.find(section => section.label === 'Keyboard');
assert.equal(keyboard.items.map(item => item.label).join(), 'Bluetooth keyboard');
assert.equal(keyboard.hidden(), true);
glassesType = 'rayneo-io';
assert.equal(keyboard.hidden(), true);
glassesType = 'g2';
assert.equal(keyboard.hidden(), false);
// Nothing else is conditional this way.
assert.equal(sections.filter(section => section.hidden).length, 1);
});
+1 -1
View File
@@ -33,7 +33,7 @@ function harness(refused = new Set()) {
FaceclawKitIosGlassesSession: { alloc: () => ({ initWithRightAddressLeftAddressRingAddress: () => session }) },
FaceclawKitFaceclawBleCommunicatorListener: {}, FaceclawKitIosAncsListener: {}, FaceclawKitIosAudioPacketListener: {},
FaceclawKitFaceclawCompassListener: {}, FaceclawKitFaceclawImuListener: {}, FaceclawKitIosAmbientLightListener: {},
FaceclawKitIosMicStatusListener: {}, console: { log() {}, warn() {} },
FaceclawKitIosMicStatusListener: {}, FaceclawKitIosKeyboardEventListener: {}, console: { log() {}, warn() {} },
}, {
'@nativescript/core': { File: {}, knownFolders: {}, path: {} },
'../g2/firmware-compat': { REQUIRED_FACECLAW_FIRMWARE_VERSION: 37 },
+1 -1
View File
@@ -37,7 +37,7 @@ function harness() {
FaceclawKitIosGlassesSession: { alloc: () => ({ initWithRightAddressLeftAddressRingAddress: () => session }) },
FaceclawKitFaceclawBleCommunicatorListener: {}, FaceclawKitIosAncsListener: {}, FaceclawKitIosAudioPacketListener: {},
FaceclawKitFaceclawCompassListener: {}, FaceclawKitFaceclawImuListener: {}, FaceclawKitIosAmbientLightListener: {},
FaceclawKitIosMicStatusListener: {}, console: { log() {}, warn() {} },
FaceclawKitIosMicStatusListener: {}, FaceclawKitIosKeyboardEventListener: {}, console: { log() {}, warn() {} },
}, {
'@nativescript/core': { File: {}, knownFolders: {}, path: {} },
'../g2/firmware-compat': { REQUIRED_FACECLAW_FIRMWARE_VERSION: 37 },
+509
View File
@@ -0,0 +1,509 @@
const test = require('node:test')
const assert = require('node:assert/strict')
const { HidKeys, parseReportMap, reportKeys } = require('../.test-build/app/g2/keyboard/hid.js')
const {
KeyboardRecords, keyboardControl, le16, u16, parseKeyboardAdvert, mergeKeyboardAdverts,
parseKeyboardAddress, formatKeyboardAddress,
} = require('../.test-build/app/g2/keyboard/protocol.js')
const { KeyboardClient, KeyboardClientError, attributeUuid } = require('../.test-build/app/g2/keyboard/client.js')
const { KeyboardBridge } = require('../.test-build/app/g2/keyboard/bridge.js')
// The HID vectors and the simulated HOGP keyboard follow g2flash demos/keyboard.test.ts.
const boot = Uint8Array.from([
0x05,1,0x09,6,0xa1,1,0x05,7,0x19,0xe0,0x29,0xe7,0x15,0,0x25,1,0x75,1,0x95,8,0x81,2,
0x75,8,0x95,1,0x81,1,0x95,6,0x75,8,0x15,0,0x25,0x65,0x05,7,0x19,0,0x29,0x65,0x81,0,0xc0,
])
const numbered = Uint8Array.from([
...boot.slice(0, 6), 0x85,1,...boot.slice(6, -1),
0x85,2,0x05,0x0c,0x15,0,0x25,1,0x75,1,0x95,3,0x09,0xe9,0x09,0xea,0x09,0xe2,0x81,2,
0x75,5,0x95,1,0x81,1,0xc0,
])
function frame(kind, seq, epoch, request, code, handle, data, offset = 0, total = data.length) {
const p = new Uint8Array(24 + data.length), v = new DataView(p.buffer)
p.set([75,66,1,kind]); v.setUint32(4,seq,true); v.setUint16(8,epoch,true); v.setUint16(10,request,true)
v.setUint16(12,code,true); v.setUint16(14,handle,true); v.setUint16(16,total,true); v.setUint16(18,offset,true)
v.setUint32(20,1234,true); p.set(data,24); return p
}
const flush = () => new Promise(resolve => setImmediate(resolve))
async function settle(rounds = 20) { for (let i = 0; i < rounds; i++) await flush() }
test('boot array, modifiers, release, repeats and rollover', () => {
const r = parseReportMap(boot).get(0), keys = new HidKeys()
assert.deepEqual(keys.update(12,r,Uint8Array.of(2,0,4,0,0,0,0,0)), [
{page:7,usage:0xe1,down:true},{page:7,usage:4,down:true},
])
assert.deepEqual(keys.update(12,r,Uint8Array.of(2,0,4,0,0,0,0,0)), [])
assert.throws(() => keys.update(12,r,Uint8Array.of(0,0,1,1,1,1,1,1)), /rollover/)
assert.deepEqual(keys.reset().map(k => k.down), [false,false])
assert.throws(() => reportKeys(r,Uint8Array.of(0)), /length/)
})
test('HOGP report IDs are out of band, with consumer keys', () => {
const maps = parseReportMap(numbered)
assert.deepEqual(reportKeys(maps.get(1),Uint8Array.of(0,0,5,0,0,0,0,0)), [{page:7,usage:5}])
assert.deepEqual(reportKeys(maps.get(2),Uint8Array.of(5)), [{page:12,usage:0xe9},{page:12,usage:0xe2}])
assert.throws(() => reportKeys(maps.get(2),Uint8Array.of(2,5)), /length/)
})
test('NKRO bitmap with non-byte-aligned fields and report union', () => {
const map = Uint8Array.of(5,7,0x19,4,0x29,19,0x15,0,0x25,1,0x75,1,0x95,16,0x81,2)
const r = parseReportMap(map).get(0), keys = new HidKeys()
assert.deepEqual(reportKeys(r,Uint8Array.of(0x81,0x80)), [{page:7,usage:4},{page:7,usage:11},{page:7,usage:19}])
assert.equal(keys.update(10,r,Uint8Array.of(1,0)).length, 1)
assert.deepEqual(keys.update(11,r,Uint8Array.of(1,0)), [])
assert.deepEqual(keys.update(10,r,Uint8Array.of(0,0)), [])
assert.deepEqual(keys.update(11,r,Uint8Array.of(0,0)), [{page:7,usage:4,down:false}])
})
test('array values index usages relative to logical minimum', () => {
const r = parseReportMap(Uint8Array.of(5,7,0x19,4,0x29,6,0x15,1,0x25,3,0x75,8,0x95,1,0x81,0)).get(0)
assert.deepEqual(reportKeys(r,Uint8Array.of(2)), [{page:7,usage:5}])
assert.deepEqual(reportKeys(r,Uint8Array.of(0)), [])
})
test('descriptor resource bounds and malformed items', () => {
for (const data of [new Uint8Array(),new Uint8Array(513),Uint8Array.of(0xfe),Uint8Array.of(0x75),
Uint8Array.of(0xb4),Uint8Array.of(0xc0),Uint8Array.of(0x85,0),Uint8Array.of(0x75,33,0x95,1,0x81,2),
Uint8Array.of(0x75,32,0x96,0,2,0x81,2),Uint8Array.of(0xa1,1)]) assert.throws(() => parseReportMap(data))
// Deterministic malformed corpus; parsing must be bounded and never hang.
let seed = 1
for (let i = 0; i < 1000; i++) {
const data = Uint8Array.from({length:i%128+1}, () => { seed=(Math.imul(seed,1664525)+1013904223)>>>0; return seed>>>24 })
try { parseReportMap(data) } catch (e) { assert.ok(e instanceof Error) }
}
})
test('control records, UUIDs and addresses', () => {
assert.deepEqual([...keyboardControl(4,0x1234,0x5678,[1,2,3,4,5,6,7])], [75,66,1,4,0x34,0x12,0x78,0x56,1,2,3,4,5,6,7])
assert.throws(() => keyboardControl(13,1,1))
assert.throws(() => keyboardControl(11,1,1,new Array(73).fill(0)))
assert.equal(attributeUuid(Uint8Array.of(0xfb,0x34,0x9b,0x5f,0x80,0,0,0x80,0,0x10,0,0,0x12,0x18,0,0)), 0x1812)
const address = parseKeyboardAddress('AA:bb:cc:dd:ee:01')
assert.deepEqual([...address], [1,0xee,0xdd,0xcc,0xbb,0xaa])
assert.equal(formatKeyboardAddress(address), 'aa:bb:cc:dd:ee:01')
assert.equal(parseKeyboardAddress('aa:bb:cc:dd:ee'), null)
assert.equal(parseKeyboardAddress('aa:bb:cc:dd:ee:gg'), null)
})
test('fragments, duplicate delivery, gaps, epochs and sequence wrap', () => {
let gaps = 0; const stream = new KeyboardRecords(() => gaps++)
const data = Uint8Array.from({length:200}, (_,i) => i)
assert.equal(stream.push(frame(3,0xffffffff,1,0,13,33,data.slice(0,96),0,200)), undefined)
assert.equal(stream.push(frame(3,0xffffffff,1,0,13,33,data.slice(96,192),96,200)), undefined)
assert.deepEqual(stream.push(frame(3,0xffffffff,1,0,13,33,data.slice(192),192,200)).data, data)
const status = frame(1,0,1,0,0,0,new Uint8Array(10))
assert.equal(stream.push(status).sequence, 0)
assert.equal(stream.push(status), undefined); assert.equal(gaps, 1)
stream.push(frame(1,2,1,0,0,0,new Uint8Array(10))); assert.equal(gaps, 2)
assert.equal(stream.push(status), undefined); assert.equal(gaps, 2)
stream.push(frame(1,3,2,0,0,0,new Uint8Array(10))); assert.equal(gaps, 3)
})
test('missing or mismatched fragments never emit partial input', () => {
let gaps = 0; const stream = new KeyboardRecords(() => gaps++)
stream.push(frame(3,1,1,0,13,10,new Uint8Array(96),0,100))
assert.equal(stream.push(frame(3,1,1,0,13,11,new Uint8Array(4),96,100)), undefined)
assert.equal(gaps, 2)
assert.equal(stream.push(frame(3,1,1,0,13,10,new Uint8Array(4),96,100)), undefined)
assert.equal(stream.push(new Uint8Array(513)), undefined)
// Another protocol version is not ours to decode.
const future = frame(1,5,1,0,0,0,new Uint8Array(10)); future[2] = 2
assert.equal(stream.push(future), undefined)
})
test('adverts: name from the scan response, HID from the service list or the appearance', () => {
const body = (ad, rssi = -60) => Uint8Array.from([1, 6,5,4,3,2,1, rssi & 255, 0, ad.length, ...ad])
const services = parseKeyboardAdvert(body([2,1,6, 3,3,0x12,0x18]))
assert.deepEqual(services, { addressType: 1, address: '01:02:03:04:05:06', rssi: -60, name: '', hid: true })
const named = parseKeyboardAdvert(body([5,9,0x4b,0x33,0x38,0x30], -48))
assert.equal(named.name, 'K380'); assert.equal(named.hid, false)
assert.deepEqual(mergeKeyboardAdverts(services, named), { ...services, name: 'K380', rssi: -48 })
assert.equal(parseKeyboardAdvert(body([3,0x19,0xc1,0x03])).hid, true)
assert.equal(parseKeyboardAdvert(body([3,0x19,0x41,0x03])).hid, false)
assert.equal(parseKeyboardAdvert(Uint8Array.of(1,2,3)), null)
// A truncated AD structure ends the parse without reading past the body.
assert.equal(parseKeyboardAdvert(body([9,9,0x41])).name, '')
})
/**
* The firmware bridge and a HOGP keyboard behind it, as far as the phone can
* tell: answers control records with the records the real one sends.
*/
function fakeGlasses(deliver) {
const attrs = new Map()
const add = (h, uuid, bytes) => attrs.set(h, { uuid, value: Uint8Array.from(bytes) })
const mockMap = Uint8Array.from([...numbered.slice(0,-1),0x85,3,0x05,6,0x09,0x20,0x15,0,0x25,100,0x75,8,0x95,1,0x81,2,0xc0])
add(1,0x2800,[1,0x18]); add(2,0x2803,[0x20,3,0,5,0x2a]); add(3,0x2a05,[]); add(4,0x2902,[0,0])
add(20,0x2800,[0x12,0x18])
add(21,0x2803,[2,22,0,0x4b,0x2a]); add(22,0x2a4b,mockMap); add(23,0x2907,[0x19,0x2a])
add(24,0x2803,[6,25,0,0x4e,0x2a]); add(25,0x2a4e,[1])
add(26,0x2803,[0x12,27,0,0x4d,0x2a]); add(27,0x2a4d,[]); add(28,0x2902,[0,0]); add(29,0x2908,[1,1])
add(30,0x2803,[0x12,31,0,0x4d,0x2a]); add(31,0x2a4d,[]); add(32,0x2902,[0,0]); add(33,0x2908,[2,1])
add(40,0x2800,[0x0f,0x18]); add(41,0x2803,[0x12,42,0,0x19,0x2a]); add(42,0x2a19,[100]); add(43,0x2902,[0,0]); add(44,0x2908,[3,1])
const g = {
seq: 0, epoch: 0, enabled: 0, conn: 0, connected: 0, encrypted: 0, scanning: 0,
ops: [], writes: [], watches: [], adverts: [], pins: [], compares: [],
reachable: true, bonded: false, pairing: 'just-works', up: true,
// The keyboard's attribute table, and how its stack answers a direct read
// of a characteristic declaration: 'full', 'short' (the properties byte
// alone) or 'refused'.
attrs, add, declarations: 'full',
}
g.emit = (kind, request, code, handle, data = []) =>
deliver(frame(kind, ++g.seq, g.epoch, request, code, handle, Uint8Array.from(data)))
g.status = (request = 0, code = 0) =>
g.emit(1, request, code, 0, [g.enabled, g.conn, g.connected, g.encrypted, g.scanning, 0, 0,0,0,0])
g.dm = (event, status = 0, data = []) => g.emit(4, 0, event | (status << 8), 0, data)
g.close = () => { if (!g.conn) return; g.conn = g.connected = g.encrypted = 0; g.watches = []; g.dm(0x28); g.status() }
g.encrypt = () => { g.encrypted = 1; g.dm(0x2c); g.status() }
g.input = (handle, bytes) => g.emit(3, 0, 13, handle, bytes)
g.send = (record) => {
if (!g.up) return false
const op = record[3], req = u16(record,4), epoch = u16(record,6), h = record.length >= 10 ? u16(record,8) : 0
g.ops.push(op)
if (op !== 0 && op !== 1 && epoch !== g.epoch) { g.status(req, 4); return true }
if (op === 0) g.status(req)
else if (op === 1) { g.enabled = 1; g.status(req) }
else if (op === 2) { g.enabled = 0; g.status(req); g.close() }
else if (op === 3) {
if (g.conn) { g.status(req, 3); return true }
g.scanning = 1; g.status(req)
for (const advert of g.adverts) g.emit(5, 0, 0, 0, advert)
g.scanning = 0; g.status()
} else if (op === 4) {
if (g.conn) { g.status(req, 3); return true }
g.epoch = (g.epoch + 1) & 0xffff; g.conn = 3; g.status(req)
if (!g.reachable) return true
g.connected = 1; g.dm(0x27); g.status()
if (g.bonded) g.encrypt()
} else if (op === 5) { g.status(req); g.close() }
else if (op === 6) {
if (!g.connected) { g.status(req, 6); return true }
g.status(req)
if (g.pairing === 'just-works') { g.dm(0x2a); g.encrypt() }
else if (g.pairing === 'display') g.dm(0x2e, 0, [0, 1])
else if (g.pairing === 'entry') g.dm(0x2e, 0, [0, 0])
else if (g.pairing === 'compare') g.dm(0x35, 0, [0x40, 0xe2, 0x01, 0])
else if (g.pairing === 'fail') { g.dm(0x2b, 5); g.close() }
} else if (op === 7) {
g.pins.push(record[8] | (record[9] << 8) | (record[10] << 16)); g.status(req); g.dm(0x2a); g.encrypt()
} else if (op === 8) {
g.compares.push(record[8]); g.status(req)
if (record[8]) { g.dm(0x2a); g.encrypt() } else { g.dm(0x2b, 4); g.close() }
} else if (op === 9) {
const batch = [...attrs].filter(([handle]) => handle >= h).slice(0,4)
g.emit(2, req, batch.length ? 2 : (10<<8)|2, h, batch.length ? [1, ...batch.flatMap(([handle,a]) => [...le16(handle), ...le16(a.uuid)])] : [])
} else if (op === 10) {
const attr = attrs.get(h), offset = u16(record,10)
if (attr.uuid === 0x2803 && g.declarations === 'refused') { g.emit(2, req, (2<<8)|5, h); return true }
const data = attr.uuid === 0x2803 && g.declarations === 'short' ? attr.value.slice(0,1) : attr.value
g.emit(2, req, offset >= data.length ? (7<<8)|6 : offset ? 6 : 5, h, data.slice(offset, offset+20))
} else if (op === 11) { g.writes.push(h); g.emit(2, req, record[10] ? 10 : 9, h) }
else if (op === 12) { g.watches = Array.from({length:record[8]}, (_,i) => u16(record,9+2*i)); g.status(req) }
else throw new Error(`Unexpected op ${op}`)
return true
}
return g
}
test('client: HOGP discovery, long Report Map, subscriptions, typing and loss recovery', async () => {
const events = []
let client
const g = fakeGlasses(payload => client.accept(payload))
client = new KeyboardClient(g.send, { keys: e => events.push(...e) })
await client.enable(); await client.connect(1, new Uint8Array(6)); const config = await client.configure()
// The battery level (an external report) is found, but it can't carry a
// key, so it isn't subscribed: only the two key reports and Service Changed.
assert.deepEqual(g.watches, [27,31,3]); assert.deepEqual(g.writes, [25,4,28,32])
assert.deepEqual(config.reports.map(r => r.id), [1,2,3]); assert.deepEqual(config.watched, [27,31])
assert.deepEqual(config.reports.map(r => r.properties), [0x12,0x12,0x12])
g.input(27, [0,0,4,0,0,0,0,0]); g.input(31, [1])
assert.deepEqual(events.map(e => [e.usage,e.down]), [[4,true],[0xe9,true]])
g.seq++ // a release lost in the firmware queue or on the way to the phone
g.status()
assert.deepEqual(events.slice(-2).map(e => e.down), [false,false])
// Another client on the same connection can take over with the mapping.
const restored = new KeyboardClient(() => true, { keys: e => events.push(...e) })
restored.restore(config); restored.accept(frame(3, g.seq + 1, g.epoch, 0, 13, 27, Uint8Array.of(0,0,5,0,0,0,0,0)))
assert.deepEqual([events.at(-1).usage, events.at(-1).down], [5, true]); restored.lostPhoneLink()
assert.deepEqual([events.at(-1).usage, events.at(-1).down], [5, false])
// Service Changed voids the handles: no more keys until configure() runs again.
g.emit(3, 0, 14, 3, [1,0,255,255])
const count = events.length; g.input(27, [0,0,6,0,0,0,0,0])
assert.equal(events.length, count)
client.close(); restored.close()
})
// A pointer's report, as a keyboard with a built-in trackpad adds: buttons and relative X/Y.
const mouseCollection = [0x05,1,0x09,2,0xa1,1,0x85,4,0x09,1,0xa1,0,0x05,9,0x19,1,0x29,3,0x15,0,0x25,1,0x75,1,0x95,3,0x81,2,
0x75,5,0x95,1,0x81,1,0x05,1,0x09,0x30,0x09,0x31,0x15,0x81,0x25,0x7f,0x75,8,0x95,2,0x81,6,0xc0,0xc0]
/** Turn the fake into a keyboard with a trackpad, whose battery level has no Report Reference. */
function makeCombo(g) {
g.add(22, 0x2a4b, [...g.attrs.get(22).value, ...mouseCollection])
g.add(34,0x2803,[0x12,35,0,0x4d,0x2a]); g.add(35,0x2a4d,[]); g.add(36,0x2902,[0,0]); g.add(37,0x2908,[4,1])
g.attrs.delete(44)
const sorted = [...g.attrs].sort((a, b) => a[0] - b[0])
g.attrs.clear(); for (const [handle, attr] of sorted) g.attrs.set(handle, attr)
}
for (const declarations of ['short', 'refused']) {
test(`client: a keyboard with a trackpad whose stack answers declaration reads ${declarations} still types`, async () => {
const events = [], logs = []
let client
const g = fakeGlasses(payload => client.accept(payload))
makeCombo(g); g.declarations = declarations
client = new KeyboardClient(g.send, { keys: e => events.push(...e), log: line => logs.push(line) })
await client.enable(); await client.connect(1, new Uint8Array(6)); const config = await client.configure()
// Keys and media keys are subscribed; the pointer and the battery are not.
assert.deepEqual(config.watched, [27,31]); assert.deepEqual(g.watches, [27,31,3]); assert.deepEqual(g.writes, [25,4,28,32])
assert.deepEqual(config.reports.map(r => [r.handle, r.id]), [[27,1],[31,2],[35,4]])
assert.deepEqual(config.reports.map(r => r.properties), declarations === 'short' ? [0x12,0x12,0x12] : [undefined,undefined,undefined])
g.input(27, [0,0,4,0,0,0,0,0])
assert.deepEqual(events.map(e => [e.usage,e.down]), [[4,true]])
// What was skipped, and why, is in the log; so is the table it came from.
assert.ok(logs.some(line => /^gatt 1=2800 2=2803 /.test(line)), logs.join('\n'))
assert.ok(logs.some(line => /report 42 skipped: no Report Reference/.test(line)), logs.join('\n'))
assert.ok(logs.some(line => /report 35 \(id 4\) carries no keys/.test(line)), logs.join('\n'))
assert.ok(logs.some(line => line.startsWith('report map 22: 0501')))
client.close()
})
}
test('client: one unusable report is skipped, and a device with no key report is refused with the reasons', async () => {
let client
const g = fakeGlasses(payload => client.accept(payload))
client = new KeyboardClient(g.send)
g.add(29, 0x2908, [1]) // a Report Reference of the wrong length
await client.enable(); await client.connect(1, new Uint8Array(6))
assert.deepEqual((await client.configure()).watched, [31])
g.add(33, 0x2908, [9,1]) // and one naming a report the map doesn't have
await assert.rejects(client.configure(), /No usable keyboard input report \(27: Report Reference 29 is 01; 31: input report id 9 is not in the Report Map\)/)
assert.equal(client.configuration, undefined)
// Not a HID device at all.
g.add(20, 0x2800, [0x0f,0x18])
await assert.rejects(client.configure(), /no HID service/)
client.close()
})
test('client: the link dropping during setup ends it, rather than being skipped over', async () => {
let client
const g = fakeGlasses(payload => client.accept(payload))
client = new KeyboardClient(g.send)
await client.enable(); await client.connect(1, new Uint8Array(6))
const send = g.send
g.send = (record) => {
// The keyboard goes away as the first Report Reference is read.
if (record[3] === 10 && u16(record, 8) === 29) { g.close(); return true }
return send(record)
}
client = new KeyboardClient(record => g.send(record))
await client.query()
await assert.rejects(client.configure(), /stream gap|link changed/)
client.close()
})
test('client: an unreachable keyboard fails the connect when the glasses give up, not by timeout', async () => {
let client
const g = fakeGlasses(payload => client.accept(payload)); g.reachable = false
client = new KeyboardClient(g.send)
await client.enable()
const pending = client.connect(1, new Uint8Array(6))
await settle(); g.close()
await assert.rejects(pending, /didn't answer/)
client.close()
})
test('client: firmware errors carry their code, and a dead link rejects at once', async () => {
let client
const g = fakeGlasses(payload => client.accept(payload))
client = new KeyboardClient(g.send)
await client.enable(); await client.connect(1, new Uint8Array(6))
await assert.rejects(client.command(4, [1,0,0,0,0,0,0]), e => e instanceof KeyboardClientError && e.code === 3)
g.up = false
await assert.rejects(client.query(), /aren't ready/)
client.close()
await assert.rejects(client.query(), /closed/)
})
function bridgeSetup(saved = null) {
const host = { keys: [], gone: 0, changes: 0, logs: [], prompts: [], saved, reconnect: true }
let bridge
const g = fakeGlasses(payload => bridge.accept(payload))
bridge = new KeyboardBridge({
send: g.send,
loadSaved: () => host.saved,
storeSaved: value => { host.saved = value },
onKeys: events => host.keys.push(...events),
onKeyboardGone: () => { host.gone++ },
onChanged: () => {
host.changes++
const pairing = bridge.snapshot().pairing
if (pairing && host.prompts.at(-1) !== pairing) host.prompts.push(pairing)
},
log: line => host.logs.push(line),
randomPasskey: () => 123456,
shouldReconnect: () => host.reconnect,
})
return { bridge, g, host }
}
const K380 = { address: 'aa:bb:cc:dd:ee:01', addressType: 1, name: 'K380' }
const advertOf = (lastByte, ad) => [1, lastByte,0xee,0xdd,0xcc,0xbb,0xaa, 0xc4, 0, ad.length, ...ad]
test('bridge: scan, pick, pair by typing the displayed passkey, type, forget', async () => {
const { bridge, g, host } = bridgeSetup()
assert.equal(bridge.snapshot().state, 'unavailable')
await assert.rejects(bridge.scan(), /Connect to G2 glasses/)
bridge.linkReady()
g.adverts = [
advertOf(2, [2,1,6]), // some other device
advertOf(1, [2,1,6, 3,3,0x12,0x18]), // the keyboard's advertisement
advertOf(1, [5,9,0x4b,0x33,0x38,0x30]), // and its scan response, with the name
]
const found = await bridge.scan()
assert.deepEqual(found.map(a => [a.address, a.name, a.hid]), [[K380.address,'K380',true],['aa:bb:cc:dd:ee:02','',false]])
assert.equal(bridge.snapshot().state, 'idle')
g.pairing = 'display'
await bridge.connect(K380)
// The passkey went up for the user to type, and to the glasses as the answer.
assert.deepEqual(host.prompts, [{ kind: 'display', pin: 123456 }])
assert.deepEqual(g.pins, [123456])
assert.equal(bridge.snapshot().state, 'connected'); assert.equal(bridge.snapshot().pairing, null)
assert.deepEqual(host.saved, K380); assert.ok(bridge.isConnected())
g.input(27, [2,0,4,0,0,0,0,0])
assert.deepEqual(host.keys.map(k => [k.usage, k.down]), [[0xe1,true],[4,true]])
await bridge.forget()
assert.equal(host.saved, null); assert.equal(host.gone, 1); assert.equal(g.conn, 0); assert.equal(g.enabled, 0)
assert.equal(bridge.snapshot().state, 'idle')
bridge.linkLost()
})
test('bridge: numeric comparison waits for the answer; declining fails the pairing', async () => {
const { bridge, g } = bridgeSetup()
bridge.linkReady(); g.pairing = 'compare'
const pending = bridge.connect(K380)
await settle()
assert.deepEqual(bridge.snapshot().pairing, { kind: 'compare', value: 123456 })
assert.equal(bridge.snapshot().state, 'pairing')
await bridge.answerCompare(false)
await assert.rejects(pending, /Pairing with the keyboard failed/)
assert.equal(bridge.snapshot().state, 'error'); assert.deepEqual(g.compares, [0])
await assert.rejects(bridge.answerCompare(true), /No pairing comparison/)
bridge.linkLost()
})
test('bridge: a keyboard that shows a code is paired with the code typed in', async () => {
const { bridge, g } = bridgeSetup()
bridge.linkReady(); g.pairing = 'entry'
const pending = bridge.connect(K380)
await settle()
assert.deepEqual(bridge.snapshot().pairing, { kind: 'entry' })
await bridge.answerPasskey(42)
await pending
assert.deepEqual(g.pins, [42]); assert.equal(bridge.snapshot().state, 'connected')
bridge.linkLost()
})
test('bridge: the remembered keyboard comes back with the link, and again after it drops', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] })
const { bridge, g, host } = bridgeSetup(K380)
g.bonded = true
bridge.linkReady()
assert.equal(bridge.snapshot().waiting, true)
t.mock.timers.tick(1000); await settle()
assert.equal(bridge.snapshot().state, 'connected'); assert.equal(g.connected, 1)
// The keyboard goes to sleep: held keys are dropped, and it is looked for again.
g.input(27, [0,0,4,0,0,0,0,0])
g.close(); await settle()
assert.equal(host.gone, 1); assert.equal(bridge.snapshot().state, 'idle'); assert.equal(bridge.snapshot().waiting, true)
g.reachable = false
t.mock.timers.tick(2000); await settle()
assert.equal(bridge.snapshot().state, 'connecting')
g.close(); await settle()
// Asleep is the ordinary case, not an error in front of the user.
assert.equal(bridge.snapshot().state, 'idle'); assert.equal(bridge.snapshot().error, '')
g.reachable = true
t.mock.timers.tick(2000); await settle()
assert.equal(bridge.snapshot().state, 'connected')
// Disconnecting by hand stops the retries until asked again.
await bridge.disconnect()
assert.equal(bridge.snapshot().waiting, false); assert.equal(g.enabled, 0)
t.mock.timers.tick(60000); await settle()
assert.equal(bridge.snapshot().state, 'idle'); assert.equal(g.connected, 0)
bridge.linkLost()
})
test('bridge: the glasses kept the keyboard through a phone-side drop, so only discovery is redone', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] })
const { bridge, g, host } = bridgeSetup(K380)
g.bonded = true
bridge.linkReady(); t.mock.timers.tick(1000); await settle()
assert.equal(bridge.snapshot().state, 'connected')
const epoch = g.epoch
bridge.linkLost()
assert.equal(bridge.snapshot().state, 'unavailable'); assert.equal(host.gone, 1)
g.ops.length = 0
bridge.linkReady(); t.mock.timers.tick(1000); await settle()
assert.equal(bridge.snapshot().state, 'connected')
assert.equal(g.epoch, epoch, 'no reconnect of the keyboard itself')
assert.ok(!g.ops.includes(4) && !g.ops.includes(2))
g.input(27, [0,0,7,0,0,0,0,0])
assert.deepEqual([host.keys.at(-1).usage, host.keys.at(-1).down], [7, true])
bridge.linkLost()
})
test('bridge: a scan started by hand takes over from an attempt in flight, and nothing retries while charging', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] })
const { bridge, g, host } = bridgeSetup(K380)
g.reachable = false
bridge.linkReady(); t.mock.timers.tick(1000); await settle()
assert.equal(bridge.snapshot().state, 'connecting'); assert.equal(g.conn, 3)
g.adverts = [advertOf(1, [3,3,0x12,0x18])]
const scan = bridge.scan()
await settle(); t.mock.timers.tick(200); await settle()
assert.equal((await scan).length, 1)
assert.equal(g.conn, 0, 'the pending connection was released first')
assert.equal(bridge.snapshot().state, 'idle'); assert.equal(bridge.snapshot().busy, false)
// Reconnecting waits for the glasses to be in use.
host.reconnect = false
bridge.linkLost(); bridge.linkReady(); g.ops.length = 0
t.mock.timers.tick(1000); await settle()
t.mock.timers.tick(120000); await settle()
assert.deepEqual(g.ops, [])
// A bridge left enabled by an attempt is switched off for the wait, so the
// firmware's timer and its once-a-second status stop.
host.reconnect = true; g.reachable = false
bridge.retryNow(); t.mock.timers.tick(0); await settle()
assert.equal(g.enabled, 1); assert.equal(bridge.snapshot().state, 'connecting')
g.close(); await settle()
host.reconnect = false
t.mock.timers.tick(2000); await settle()
assert.equal(g.enabled, 0)
g.ops.length = 0
t.mock.timers.tick(120000); await settle()
assert.deepEqual(g.ops, [])
// The display woke: no waiting out the rest of the backoff.
host.reconnect = true; g.reachable = true; g.bonded = true
bridge.retryNow()
t.mock.timers.tick(0); await settle()
assert.equal(bridge.snapshot().state, 'connected')
// With the keyboard in use, or none remembered, there is nothing to retry.
g.ops.length = 0
bridge.retryNow(); t.mock.timers.tick(0); await settle()
assert.deepEqual(g.ops, [])
bridge.linkLost()
})
test('bridge: leaving on purpose tells the glasses to let the keyboard go', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] })
const { bridge, g } = bridgeSetup(K380)
g.bonded = true
bridge.linkReady(); t.mock.timers.tick(1000); await settle()
assert.equal(g.connected, 1)
bridge.linkClosing(); bridge.linkLost()
assert.equal(g.enabled, 0); assert.equal(g.conn, 0)
// With no keyboard in use there is nothing to say.
const idle = bridgeSetup()
idle.bridge.linkReady(); idle.bridge.linkClosing(); idle.bridge.linkLost()
assert.deepEqual(idle.g.ops, [])
})
test('bridge: a keyboard forgotten while the glasses were away is released when they return', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] })
const { bridge, g, host } = bridgeSetup(K380)
g.bonded = true
bridge.linkReady(); t.mock.timers.tick(1000); await settle()
assert.equal(g.connected, 1)
bridge.linkLost()
await bridge.forget()
assert.equal(host.saved, null); assert.equal(g.connected, 1, 'out of reach, so still attached')
bridge.linkReady(); await settle()
assert.equal(g.enabled, 0); assert.equal(g.conn, 0)
t.mock.timers.tick(60000); await settle()
assert.equal(bridge.snapshot().state, 'idle'); assert.equal(bridge.snapshot().waiting, false)
bridge.linkLost()
})
+157
View File
@@ -0,0 +1,157 @@
const test = require('node:test')
const assert = require('node:assert/strict')
const { KeyTranslator, translateUsage, navigationGestureForKey } = require('../.test-build/app/g2/keyboard/keys.js')
const { encodeTerminalKey, terminalScrollbackKey } = require('../.test-build/app/apps/terminal/terminal-keys.js')
const K = 7
const down = (usage, page = K) => ({ page, usage, down: true })
const up = (usage, page = K) => ({ page, usage, down: false })
const SHIFT = 225, RSHIFT = 229, CTRL = 224, ALT = 226, META = 227, CAPS = 57
const A = 4, ONE = 30, ENTER = 40, SLASH = 56
function translator() {
const events = [], timers = new Map()
let nextTimer = 1, now = 1000
const t = new KeyTranslator({
emit: e => events.push(e),
now: () => now,
setTimer: (callback, delayMs) => { timers.set(nextTimer, { callback, at: now + delayMs }); return nextTimer++ },
clearTimer: handle => timers.delete(handle),
})
const advance = ms => {
const end = now + ms
for (;;) {
const due = [...timers].filter(([, timer]) => timer.at <= end).sort((a, b) => a[1].at - b[1].at)[0]
if (!due) break
timers.delete(due[0]); now = due[1].at; due[1].callback()
}
now = end
}
return { t, events, timers, advance }
}
const key = (overrides = {}) => ({
phase: 'down', key: 'a', code: 'KeyA', text: 'a', repeat: false, timestampMs: 0,
...overrides, modifiers: { shift: false, ctrl: false, alt: false, meta: false, ...overrides.modifiers },
})
test('US layout: letters, digits, punctuation, keypad, function and consumer keys', () => {
assert.deepEqual(translateUsage(K, A, false, false), { key: 'a', code: 'KeyA', text: 'a' })
assert.deepEqual(translateUsage(K, A, true, false), { key: 'A', code: 'KeyA', text: 'A' })
assert.deepEqual(translateUsage(K, A, true, true), { key: 'a', code: 'KeyA', text: 'a' })
assert.deepEqual(translateUsage(K, ONE, true, true), { key: '!', code: 'Digit1', text: '!' })
assert.deepEqual(translateUsage(K, SLASH, true, false), { key: '?', code: 'Slash', text: '?' })
assert.deepEqual(translateUsage(K, 44, false, false), { key: ' ', code: 'Space', text: ' ' })
assert.deepEqual(translateUsage(K, 89, false, false), { key: '1', code: 'Numpad1', text: '1' })
assert.deepEqual(translateUsage(K, 88, false, false), { key: 'Enter', code: 'NumpadEnter' })
assert.deepEqual(translateUsage(K, 69, false, false), { key: 'F12', code: 'F12' })
assert.deepEqual(translateUsage(K, 104, false, false), { key: 'F13', code: 'F13' })
assert.deepEqual(translateUsage(12, 0xe9, false, false), { key: 'AudioVolumeUp', code: 'AudioVolumeUp' })
assert.equal(translateUsage(K, 200, false, false).key, 'Unidentified')
})
test('modifiers follow the stream, on either side, and chords carry no text', () => {
const { t, events } = translator()
t.handle([down(SHIFT), down(A)])
assert.deepEqual(events.map(e => [e.phase, e.key, e.text]), [['down', 'Shift', undefined], ['down', 'A', 'A']])
assert.equal(events[1].modifiers.shift, true)
// The other Shift takes over; releasing the first leaves it held.
t.handle([down(RSHIFT), up(SHIFT), up(A), down(A)])
assert.equal(events.at(-1).key, 'A')
t.handle([up(RSHIFT), up(A), down(CTRL), down(A)])
assert.deepEqual([events.at(-1).key, events.at(-1).text, events.at(-1).modifiers.ctrl], ['a', undefined, true])
t.handle([up(CTRL), up(A), down(ALT), down(A)])
assert.equal(events.at(-1).text, undefined)
t.handle([up(ALT), up(A), down(META), down(A)])
assert.equal(events.at(-1).text, undefined)
// A duplicate report changes nothing.
const count = events.length; t.handle([down(A)]); assert.equal(events.length, count)
t.handle([up(200)]); assert.equal(events.length, count)
})
test('Caps Lock toggles letters only', () => {
const { t, events } = translator()
t.handle([down(CAPS), up(CAPS), down(A), up(A), down(ONE), up(ONE), down(SHIFT), down(A)])
const typed = events.filter(e => e.phase === 'down' && e.text).map(e => e.text)
assert.deepEqual(typed, ['A', '1', 'a'])
})
test('a held key repeats until it is released; the newest key is the one that repeats', () => {
const { t, events, timers, advance } = translator()
t.handle([down(A)])
advance(399); assert.equal(events.length, 1)
advance(1); assert.deepEqual([events.at(-1).key, events.at(-1).repeat], ['a', true])
advance(100); assert.equal(events.filter(e => e.repeat).length, 3)
t.handle([down(ONE)]); advance(400)
assert.deepEqual([events.at(-1).key, events.at(-1).repeat], ['1', true])
// Releasing the older key leaves the newer one repeating.
t.handle([up(A)]); const before = events.length; advance(50)
assert.equal(events.length, before + 1)
t.handle([up(ONE)]); const after = events.length; advance(1000)
assert.equal(events.length, after); assert.equal(timers.size, 0)
// Modifiers never repeat.
t.handle([down(SHIFT)]); advance(2000); assert.equal(events.filter(e => e.key === 'Shift').length, 1)
})
test('reset forgets held keys and modifiers without emitting, and stops the repeat', () => {
const { t, events, timers, advance } = translator()
t.handle([down(SHIFT), down(CAPS), down(A)])
const count = events.length
t.reset(); advance(5000)
assert.equal(events.length, count); assert.equal(timers.size, 0)
t.handle([down(A)])
assert.deepEqual([events.at(-1).key, events.at(-1).modifiers.shift], ['a', false])
})
test('navigation keys stand in for ring gestures; everything else does nothing', () => {
const gesture = (k, extra = {}) => navigationGestureForKey(key({ key: k, text: undefined, ...extra }))
assert.equal(gesture('ArrowUp'), 'scroll-up'); assert.equal(gesture('ArrowDown'), 'scroll-down')
assert.equal(gesture('Enter'), 'click'); assert.equal(gesture('ArrowRight'), 'click')
assert.equal(gesture('Escape'), 'double-click'); assert.equal(gesture('ArrowLeft'), 'double-click')
// Holding an arrow keeps scrolling; holding Enter or Escape acts once.
assert.equal(gesture('ArrowDown', { repeat: true }), 'scroll-down')
assert.equal(gesture('Enter', { repeat: true }), null); assert.equal(gesture('Escape', { repeat: true }), null)
assert.equal(gesture('Enter', { phase: 'up' }), null)
assert.equal(gesture('Enter', { modifiers: { ctrl: true } }), null)
assert.equal(gesture('a'), null); assert.equal(gesture(' '), null); assert.equal(gesture('Backspace'), null)
})
test('terminal: printable keys, Enter, Tab, Backspace, Escape', () => {
const enc = (overrides, appCursor = false) => encodeTerminalKey(key(overrides), appCursor)
assert.equal(enc({}), 'a')
assert.equal(enc({ key: 'A', text: 'A', modifiers: { shift: true } }), 'A')
assert.equal(enc({ key: 'Enter', text: undefined }), '\r')
assert.equal(enc({ key: 'Tab', text: undefined }), '\t')
assert.equal(enc({ key: 'Tab', text: undefined, modifiers: { shift: true } }), '\x1b[Z')
assert.equal(enc({ key: 'Backspace', text: undefined }), '\x7f')
assert.equal(enc({ key: 'Backspace', text: undefined, modifiers: { ctrl: true } }), '\x08')
assert.equal(enc({ key: 'Escape', text: undefined }), '\x1b')
assert.equal(enc({ key: ' ', text: ' ' }), ' ')
assert.equal(enc({ phase: 'up' }), null)
assert.equal(enc({ key: 'Shift', code: 'ShiftLeft', text: undefined, modifiers: { shift: true } }), null)
assert.equal(enc({ key: 'AudioVolumeUp', text: undefined }), null)
assert.equal(enc({ modifiers: { meta: true }, text: undefined }), null)
// A repeat types again.
assert.equal(enc({ repeat: true }), 'a')
})
test('terminal: Ctrl chords are control characters, Alt prefixes ESC', () => {
const enc = (k, modifiers) => encodeTerminalKey(key({ key: k, text: undefined, modifiers }), false)
assert.equal(enc('c', { ctrl: true }), '\x03'); assert.equal(enc('C', { ctrl: true, shift: true }), '\x03')
assert.equal(enc('z', { ctrl: true }), '\x1a'); assert.equal(enc('[', { ctrl: true }), '\x1b')
assert.equal(enc(' ', { ctrl: true }), '\x00'); assert.equal(enc('/', { ctrl: true }), '\x7f')
assert.equal(enc('=', { ctrl: true }), null)
assert.equal(enc('f', { alt: true }), '\x1bf'); assert.equal(enc('F', { alt: true, shift: true }), '\x1bF')
assert.equal(enc('c', { ctrl: true, alt: true }), '\x1b\x03')
assert.equal(enc('Enter', { alt: true }), '\x1b\r'); assert.equal(enc('Backspace', { alt: true }), '\x1b\x7f')
})
test('terminal: cursor keys follow DECCKM; modified ones and function keys use the xterm forms', () => {
const enc = (k, modifiers, appCursor = false) => encodeTerminalKey(key({ key: k, text: undefined, modifiers }), appCursor)
assert.equal(enc('ArrowUp'), '\x1b[A'); assert.equal(enc('ArrowUp', {}, true), '\x1bOA')
assert.equal(enc('ArrowLeft', { ctrl: true }), '\x1b[1;5D'); assert.equal(enc('ArrowLeft', { ctrl: true }, true), '\x1b[1;5D')
assert.equal(enc('ArrowRight', { shift: true, alt: true }), '\x1b[1;4C')
assert.equal(enc('Home'), '\x1b[H'); assert.equal(enc('End', {}, true), '\x1bOF')
assert.equal(enc('PageUp'), '\x1b[5~'); assert.equal(enc('Delete'), '\x1b[3~'); assert.equal(enc('Delete', { ctrl: true }), '\x1b[3;5~')
assert.equal(enc('F1'), '\x1bOP'); assert.equal(enc('F4', { shift: true }), '\x1b[1;2S')
assert.equal(enc('F5'), '\x1b[15~'); assert.equal(enc('F12'), '\x1b[24~'); assert.equal(enc('F13'), null)
})
test('terminal: Shift+PageUp and Shift+PageDown page the scrollback instead', () => {
const page = (k, modifiers, phase = 'down') => terminalScrollbackKey(key({ key: k, text: undefined, modifiers, phase }))
assert.equal(page('PageUp', { shift: true }), -1); assert.equal(page('PageDown', { shift: true }), 1)
assert.equal(page('PageUp', {}), null); assert.equal(page('PageUp', { shift: true, ctrl: true }), null)
assert.equal(page('PageUp', { shift: true }, 'up'), null); assert.equal(page('ArrowUp', { shift: true }), null)
})
@@ -855,4 +855,62 @@ class GlassesSessionCoreTest {
s.core.close()
}
}
@Test
fun keyboardControlsGoToTheRightArmAndKeyboardRecordsReachTheirListenerOnly() {
val s = Session()
val records = ArrayList<ByteArray>()
val lock = s.platform.createLock()
val listener = object : FaceclawKeyboardEventListener {
override fun onKeyboardEvent(body: ByteArray?) { lock.withLock { records.add(body!!) } }
}
s.core.addKeyboardEventListener(listener)
// ['K','B',1,QUERY, request 7, epoch 0]
val control = byteArrayOf(75, 66, 1, 0, 7, 0, 0, 0)
try {
assertFalse(s.core.sendFaceclawKeyboardControl(control, "query"), "refused before the session is up")
s.startAndAwaitLayout()
assertFalse(s.core.sendFaceclawKeyboardControl(null, "none"))
assertFalse(s.core.sendFaceclawKeyboardControl(byteArrayOf(75, 66, 1), "short"))
assertTrue(s.core.sendFaceclawKeyboardControl(control, "query"))
fun controls() = s.link.writes.filter { it.sid == BleProtocol.SID_UI_SETTING && it.pb.containsSequence(control) }
assertTrue(waitUntil(5_000) { controls().isNotEmpty() })
// One copy, down the right arm: a second one would run the control twice.
assertEquals(listOf(RIGHT), controls().map { it.address })
assertContentEquals(
BleProtocol.encodeVarintField(1, 1) + BleProtocol.encodeVarintField(2, 0) +
BleProtocol.encodeBytesField(BleProtocol.FACECLAW_KEYBOARD_CONTROL_FIELD, control),
controls().single().pb,
)
// A field-131 record: ['K','B',1,STATUS, seq 1, epoch 0, request 7, ...] with a 10-byte body.
val record = byteArrayOf(75, 66, 1, 1, 1, 0, 0, 0, 0, 0, 7, 0, 0, 0, 0, 0, 10, 0, 0, 0, 1, 2, 3, 4) + ByteArray(10)
fun push(address: String, body: ByteArray, flag: Int) = s.core.onNotification(address, BleProtocol.NOTIFY_CHAR_UUID,
BleProtocol.framePb(
BleProtocol.encodeVarintField(1, 3) + BleProtocol.encodeVarintField(2, 0) +
BleProtocol.encodeBytesField(BleProtocol.FACECLAW_KEYBOARD_EVENT_FIELD, body),
BleProtocol.SID_UI_SETTING, flag, 33)[0])
val eventsBefore = s.listener.events.size
val activityBefore = s.core.monitor.withLock { s.core.lastConnectionOrInputAtMs }
s.platform.offsetMs += 5_000
push(RIGHT, record, BleProtocol.FLAG_NOTIFY)
// Whichever temple hosts the keyboard reports it, and the flag doesn't matter.
push(LEFT, record, BleProtocol.FLAG_REQUEST)
assertEquals(2, lock.withLock { records.size })
assertContentEquals(record, lock.withLock { records[0] })
// Not glasses input, not user activity, and not an ACK for anything.
assertEquals(eventsBefore, s.listener.events.size)
assertEquals(activityBefore, s.core.monitor.withLock { s.core.lastConnectionOrInputAtMs })
assertFalse(s.host.hasLog("unexpected ack"), s.host.logs().takeLast(5).toString())
// Too short to hold the fixed header, or not a keyboard record: left to the normal path.
push(RIGHT, record.copyOf(23), BleProtocol.FLAG_NOTIFY)
push(RIGHT, byteArrayOf(77, 67) + ByteArray(30), BleProtocol.FLAG_NOTIFY)
assertEquals(2, lock.withLock { records.size })
s.core.removeKeyboardEventListener(listener)
push(RIGHT, record, BleProtocol.FLAG_NOTIFY)
assertEquals(2, lock.withLock { records.size })
} finally {
s.core.close()
}
}
}
+36
View File
@@ -157,3 +157,39 @@ test('the columns keep the padding suggested for each window edge, and scroll ri
const lit = (y) => { for (let x = 180; x < 560; x++) if (image.getPixel(x, y) > 40) return true; return false; };
assert.ok([0, 1, 2, 3, 4, 5, 6, 7].some(lit), 'rows show in the top padding once scrolled');
});
test('a hidden section comes and goes while the panel stays open', async () => {
let hidden = true;
const selected = [];
const item = (label) => ({ label, onSelect: () => selected.push(label) });
const layer = new SettingsPanelLayer([
{ label: 'Display', items: [item('Brightness')] },
{ label: 'Keyboard', items: [item('Pair')], hidden: () => hidden },
{ label: 'About', items: [item('License')] },
]);
const ctx = { stack: { getBaseSize: () => bordered(576, 260), isFocused: () => true } };
const input = (type) => layer.handleInput({ type, timestampMs: 0 }, ctx);
const enter = async () => { await input('click'); await input('click'); await input('double-click'); };
// Hidden: the row below Display is About.
await input('scroll-down'); await enter();
assert.deepEqual(selected, ['License']);
layer.focusSection('Keyboard');
await enter();
assert.deepEqual(selected, ['License', 'License'], 'a hidden section is no deep-link target either');
// Shown, with no new panel: the highlight stays on About, and Keyboard is the row above it.
hidden = false;
layer.paint(ctx);
await enter();
assert.deepEqual(selected.slice(2), ['License']);
await input('scroll-up'); await enter();
assert.deepEqual(selected.slice(3), ['Pair']);
// Hidden again from inside it: focus comes back out to the top of the list.
await input('click');
hidden = true;
layer.paint(ctx);
await enter();
assert.deepEqual(selected.slice(4), ['Brightness']);
});
+6
View File
@@ -16,6 +16,12 @@
"../app/remote/protocol.ts",
"../app/remote/listeners.ts",
"../app/g2/ancs-client.ts",
"../app/g2/keyboard/protocol.ts",
"../app/g2/keyboard/hid.ts",
"../app/g2/keyboard/client.ts",
"../app/g2/keyboard/bridge.ts",
"../app/g2/keyboard/keys.ts",
"../app/apps/terminal/terminal-keys.ts",
"../app/phone-ui/ble-bandwidth-meter.ts",
"../app/apps/terminal/hub-header.ts",
"../app/g2/ios-peripheral-identity.ts",