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.
298 lines
10 KiB
TypeScript
298 lines
10 KiB
TypeScript
/**
|
|
* 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;
|
|
}
|