269 lines
11 KiB
TypeScript
269 lines
11 KiB
TypeScript
/**
|
|
* 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. The keyboard/keypad page (7) and the
|
|
* consumer page (12) produce keys. A mouse's or touchpad's report (buttons,
|
|
* relative X/Y, wheel) is read by reportPointer.
|
|
* 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;
|
|
/** Reports a change since the last report (a mouse's axes and wheel), not a state. */
|
|
relative: 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), relative: !!(v & 4),
|
|
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 fields are padding.
|
|
if (!(v & 1)) 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.relative && (f.usages.some(isKeyPage) || (f.range !== undefined && isKeyPage(f.range[0]))));
|
|
}
|
|
|
|
/** One field's `index`th value, sign-extended when the field is signed. Bits past the data read as zero. */
|
|
function fieldValue(f: Field, index: number, data: Uint8Array): number {
|
|
let value = 0;
|
|
for (let j = 0; j < f.size; j++) {
|
|
const bit = f.bit + index * f.size + j;
|
|
if ((data[bit >>> 3] ?? 0) & (1 << (bit & 7))) value += 2 ** j;
|
|
}
|
|
if (f.min < 0 && value >= 2 ** (f.size - 1)) value -= 2 ** f.size;
|
|
return value;
|
|
}
|
|
|
|
/** What one report from a mouse or touchpad says. */
|
|
export type HidPointerSample = {
|
|
/** Buttons held, bit 0 for button 1 (left), bit 1 for button 2 (right), bit 2 for button 3 (middle). */
|
|
buttons: number;
|
|
/** Movement since the last report, in the device's counts; +x right, +y down. */
|
|
dx: number;
|
|
dy: number;
|
|
/** Wheel detents since the last report; positive is away from the user ("up"). */
|
|
wheel: number;
|
|
/** Horizontal wheel (AC Pan); positive is right. */
|
|
pan: number;
|
|
};
|
|
|
|
const HID_PAGE_GENERIC_DESKTOP = 1;
|
|
const HID_PAGE_BUTTON = 9;
|
|
const USAGE_X = 0x30;
|
|
const USAGE_Y = 0x31;
|
|
const USAGE_WHEEL = 0x38;
|
|
const USAGE_AC_PAN = 0x238;
|
|
/** Buttons past this are not tracked; a mouse with more is rare and has nothing to bind them to anyway. */
|
|
const MAX_POINTER_BUTTONS = 8;
|
|
|
|
/** Which part of a pointer sample a field's usage feeds, if any. */
|
|
function pointerRole(f: Field, u: HidUsage | undefined): "button" | "dx" | "dy" | "wheel" | "pan" | null {
|
|
if (!u || !f.variable) return null;
|
|
if (u.page === HID_PAGE_BUTTON) return !f.relative && u.usage >= 1 && u.usage <= MAX_POINTER_BUTTONS ? "button" : null;
|
|
if (!f.relative) return null; // an absolute X/Y is a touchscreen or a digitizer, not a mouse
|
|
if (u.page === HID_PAGE_GENERIC_DESKTOP) {
|
|
if (u.usage === USAGE_X) return "dx";
|
|
if (u.usage === USAGE_Y) return "dy";
|
|
if (u.usage === USAGE_WHEEL) return "wheel";
|
|
}
|
|
if (u.page === HID_PAGE_CONSUMER && u.usage === USAGE_AC_PAN) return "pan";
|
|
return null;
|
|
}
|
|
|
|
/** Whether an input report carries a mouse's buttons, movement or wheel. */
|
|
export function reportHasPointer(report: HidReport): boolean {
|
|
return report.fields.some((f) => {
|
|
for (let i = 0; i < f.count; i++) if (pointerRole(f, usageAt(f, i))) return true;
|
|
return false;
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Read a mouse or touchpad report. Lenient about length, unlike reportKeys:
|
|
* some devices leave the wheel bytes off when there is nothing to say, and a
|
|
* missing byte is zero either way.
|
|
*/
|
|
export function reportPointer(report: HidReport, data: Uint8Array): HidPointerSample {
|
|
const sample: HidPointerSample = { buttons: 0, dx: 0, dy: 0, wheel: 0, pan: 0 };
|
|
for (const f of report.fields) {
|
|
for (let i = 0; i < f.count; i++) {
|
|
const u = usageAt(f, i);
|
|
const role = pointerRole(f, u);
|
|
if (!role) continue;
|
|
const value = fieldValue(f, i, data);
|
|
if (value < f.min || value > f.max) continue; // out of range: no reading
|
|
if (role === "button") {
|
|
if (value) sample.buttons |= 1 << (u!.usage - 1);
|
|
} else {
|
|
sample[role] += value;
|
|
}
|
|
}
|
|
}
|
|
return sample;
|
|
}
|
|
|
|
/** 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) {
|
|
// A relative field is a movement, not a key that is down.
|
|
if (f.relative) continue;
|
|
for (let i = 0; i < f.count; i++) {
|
|
const value = fieldValue(f, i, data);
|
|
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;
|
|
}
|
|
}
|