/** * 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, reportHasPointer, reportPointer, type HidKeyEvent, type HidPointerSample, 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; /** * One report from the keyboard's touchpad or mouse: the buttons now held * (across all its pointer reports) and the movement and wheel since the * last one. Also sent with everything zero when a gap forces a release. */ pointer?(sample: HidPointerSample): 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: those that carry keys, or a pointer's buttons and movement. */ watched: number[]; /** Whether any of them is a pointer's (a touchpad, mouse buttons, a wheel). */ pointer: boolean; 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; }; type Waiter = { test: () => boolean; resolve: () => void; reject: (e: Error) => void; timer: ReturnType }; type Input = { report: HidReport; id: number; service: number; keys: boolean; pointer: boolean }; 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(); private readonly waiters = new Set(); private readonly keys = new HidKeys(); /** Pointer buttons held, by the report that says so (as HidKeys does for keys). */ private readonly pointerButtons = new Map(); private inputs = new Map(); 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; } if (input.keys) { 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)); } } if (input.pointer) { const sample = reportPointer(input.report, r.data); this.pointerButtons.set(r.handle, sample.buttons); this.events.pointer?.({ ...sample, buttons: this.heldButtons() }); } } private heldButtons(): number { let buttons = 0; for (const held of this.pointerButtons.values()) buttons |= held; return buttons; } /** Nothing is held any more, as far as anyone can tell: say so. */ private release(): void { const events = this.keys.reset(); if (events.length) this.events.keys?.(events); const buttons = this.heldButtons(); this.pointerButtons.clear(); if (buttons) this.events.pointer?.({ buttons: 0, dx: 0, dy: 0, wheel: 0, pan: 0 }); } 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 { if (this.closed) return Promise.reject(new KeyboardClientError("Keyboard client closed")); if (test()) return Promise.resolve(); return new Promise((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 { 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((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 { await this.command(KeyboardOp.enable); } /** Disconnect the keyboard and stop the bridge; the bond stays. */ async disable(): Promise { 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 { 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 { 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 { 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 { await this.command(KeyboardOp.disconnect); this.release(); } /** Answer a pending passkey prompt. */ async authenticate(pin: number): Promise { 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 { await this.command(KeyboardOp.compare, [accept ? 1 : 0]); } private async att(op: number, body: readonly number[]): Promise { 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 { 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 { 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 { 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 { 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 { 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 * carry keys or a pointer's buttons and movement. Needs an encrypted link. * No handle is assumed. * * Only what input needs is required of the device: a Report Map that * parses, and at least one such 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 { 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[] = []; let pointerFound = false; 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) => { 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"); const keys = reportHasKeys(layout); const pointer = reportHasPointer(layout); if (keys || pointer) watched.push(report); else log(`report ${a.handle} (id ${id}) carries no keys or pointer; not subscribed`); if (pointer) { pointerFound = true; log(`report ${a.handle} (id ${id}) is a pointer's${keys ? ", with keys" : ""}`); } } 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 or a pointer"})` : "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), pointer: pointerFound, 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(); 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, keys: reportHasKeys(report), pointer: reportHasPointer(report) }); } 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); }