forked from Blendman974/faceclaw
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:
1 parent
9372b2742c
commit
fd3c26333f
46 files changed
+3867
-41
No files matched your search
@@ -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);
|
||||
}
|
||||
Reference in new issue
Block a user