@openmouse/protocol 0.1.0

package/dist/drivers/gearhub/hid.d.ts

@@ -0,0 +1,191 @@
+import type { MouseStatus } from "../mouse-types.ts";
+import { type LiftOffLevel } from "@openmouse/protocol/gearhub";
+/**
+ * GearHub-V5 WebHID driver (VID 0x3151). Owns the 2.4 GHz relay handshake and
+ * the feature-report I/O; packet shapes and the device catalog live in the
+ * `@openmouse/protocol/gearhub` codec.
+ *
+ * One driver claims the shared receiver VID:PID and then identifies the model
+ * from the GET_USB_VERSION device id: 2285 = Lingbao M5 Pro, 1893 = Attack
+ * Shark R2, anything else = the M5 Pro fallback. The product id only settles
+ * transport.
+ *
+ * ── Transport ────────────────────────────────────────────────────────────
+ * USB interface 2, vendor usage page 0xFFFF, usage 0x02, one unnumbered
+ * 64-byte feature report. Commands are 9 bytes zero-padded into that report.
+ *
+ * ── Checksum ("Bit7", GearHub's own name) ────────────────────────────────
+ * byte[7] = 255 - (sum(bytes 0..6) & 0xFF). Without it the device ACKs the
+ * SET_FEATURE and answers 64 zero bytes — silently, no error.
+ *
+ * ── 2.4 GHz is a relay, not a pipe ───────────────────────────────────────
+ * The receiver does not forward a command just because one was written to it.
+ * A read over 2.4 GHz is a four-step exchange, and the receiver's OWN commands
+ * are raw — they carry no checksum:
+ *
+ *   1. 0xF6 0x05   select the paired mouse as the target
+ *   2. 0xF7        poll receiver status until it reports ready
+ *   3. <command>   the checksummed 9-byte command
+ *   4. 0xFC        "notice read", then read the feature report back
+ *
+ * Omit any of 1/2/4 and every reply is 64 zeros — indistinguishable from a
+ * device that does not speak the protocol at all.
+ *
+ * Step 2 is a real gate. An idle mouse drops off its receiver within a few
+ * minutes; `mouseOnline` then goes false and every command goes unanswered
+ * until the mouse is moved. `readStatus()` surfaces that as its own error so
+ * it is never mistaken for a protocol mismatch.
+ *
+ * Plugged in by cable the mouse enumerates as PID 0x4026 and skips the relay
+ * entirely: send the checksummed command, read the reply straight back.
+ */
+export interface GearHubDongleStatus {
+    canRead: boolean;
+    canSend: boolean;
+    keyboardOnline: boolean;
+    mouseOnline: boolean;
+    keyboardBattery: number;
+    mouseBattery: number;
+}
+export interface GearHubDpiStage {
+    x: number;
+    y: number;
+    rgb: number;
+}
+export declare class GearHubHidClient {
+    device: HIDDevice;
+    currentProfile: number;
+    /** What the product id tells us before we connect: the transport. */
+    private readonly transportEntry;
+    /** Model identity, resolved from the device id on the first readStatus(). */
+    private resolvedProfile;
+    private targetSelected;
+    /**
+     * The relay is stateful — select target, poll ready, send, notice-read,
+     * read — so two exchanges in flight at once interleave and corrupt each
+     * other. Every public operation is chained through here so only one runs at
+     * a time, the same way GearHub serialises through its own send queue.
+     */
+    private queue;
+    private enqueue;
+    constructor(device: HIDDevice);
+    static isSupported(device: HIDDevice): boolean;
+    /** Whether reads go through the 2.4 GHz relay or straight to the device. */
+    get transport(): "dongle" | "direct";
+    get supportedPollingRates(): number[];
+    /**
+     * DPI stops worth offering, capped at the resolved model's sensor ceiling.
+     * These sensors step in 50 DPI increments; the UI offers the round values.
+     * Before the first readStatus() this uses the fallback (M5 Pro) ceiling.
+     */
+    getDpiOptions(): number[];
+    open(): Promise<void>;
+    close(): Promise<void>;
+    private rawSend;
+    private rawRead;
+    /**
+     * Poll the receiver for link state and battery. A receiver command, so no
+     * checksum. Measured layout, live: `01 00 2D 01 00 01` — ready to read,
+     * no keyboard, mouse at 0x2D = 45%, keyboard offline, mouse online, ready
+     * to send.
+     */
+    readDongleStatus(): Promise<GearHubDongleStatus>;
+    /** Unqueued: callers already holding the queue slot use this. */
+    private pollStatus;
+    private selectMouse;
+    private waitReady;
+    /**
+     * Run one command and return its reply, rejecting a reply that is not an
+     * answer. Most reads echo the command id in byte 0; an unrelayed or
+     * unchecksummed command comes back as 64 zeros, which must never be mistaken
+     * for data. `GET_KEYMATRIX` is the exception — its reply is pure matrix data
+     * with no echo byte — so `echoes: false` keeps only the all-zero guard.
+     */
+    command(bytes: readonly number[], opts?: {
+        echoes?: boolean;
+    }): Promise<Uint8Array>;
+    private exchange;
+    private verifyReply;
+    /** Device id — the key GearHub looks its model table up by. M5 Pro answers 2285. */
+    getDeviceId(): Promise<number>;
+    /** Firmware revision: byte 2 high, byte 1 low. M5 Pro answers 0x0303. */
+    getFirmwareVersion(): Promise<number>;
+    /**
+     * Read the 64-byte OPTIONPARAM0 block — report rate (byte 9), debounce
+     * (10), lift-off (52), sleep, sensitivity. GearHub reads and writes this
+     * whole; the driver picks out the fields it exposes.
+     */
+    getOptionParam0(): Promise<Uint8Array>;
+    getReportRate(): Promise<number>;
+    /** The lift-off stops this model offers, ascending; empty when unknown. */
+    private liftOffLevels;
+    /** Every DPI stage of the active profile, plus which one is selected. */
+    getDpi(): Promise<{
+        stages: GearHubDpiStage[];
+        activeIndex: number;
+    }>;
+    /**
+     * Change fields in OPTIONPARAM0 by read-modify-write. GearHub's settings
+     * only take effect when the whole 64-byte block is written back, so every
+     * byte not in `overrides` is carried over from the current read. Bytes
+     * 17/18 are stamped the way GearHub's own writer stamps them.
+     */
+    private patchOptionParam0;
+    setReportRate(hz: number): Promise<number>;
+    /** Set the lift-off distance. Levels come from `liftOffLevels()`. */
+    setLiftOffDistance(level: LiftOffLevel): Promise<LiftOffLevel>;
+    /** Debounce (button click filter), 0..10 ms — GearHub's "Debounce" slider. */
+    getDebounceMaxMs(): number;
+    /** The exact debounce values to offer (0..10 ms), so the UI never presents
+     *  a value the firmware would clamp. */
+    getDebounceOptions(): number[];
+    setDebounceTime(ms: number): Promise<number>;
+    /** Standby-time stops, seconds; 0 = never. GearHub's "Sleep Settings". */
+    getSleepOptions(): number[];
+    /**
+     * Idle seconds before standby. GearHub keeps a 2.4 GHz timer and a Bluetooth
+     * timer; OpenMouse has one control, so both are set to the same value.
+     */
+    setSleepTimeout(seconds: number): Promise<number>;
+    /** "Straight Correction" — GearHub's angle-snapping / line-repair toggle. */
+    setAngleSnapping(enabled: boolean): Promise<boolean>;
+    /** "Ripple Correction" — bit 2 of the OPTIONPARAM0 flags word. */
+    setRippleControl(enabled: boolean): Promise<boolean>;
+    /**
+     * Raw keymatrix reply for a profile: 14 slots x 4 bytes, no echo byte. Read
+     * late in `readStatus` after several other relay exchanges, so it retries
+     * once — the relay is more likely to miss its ready window under load.
+     */
+    getKeyMatrix(profile?: number): Promise<Uint8Array>;
+    private buttonMappingsFrom;
+    /** Every action `setButtonMapping` accepts, in display order. */
+    getButtonOptions(): string[];
+    /** Reassign one physical button. `button` is a `GEARHUB_BUTTONS` name. */
+    setButtonMapping(button: string, action: string): Promise<void>;
+    /**
+     * Replace one DPI stage's resolution. SET_DPI carries the whole stage table,
+     * so the other stages — and every stage's indicator colour — are read back
+     * and echoed unchanged rather than zeroed.
+     */
+    setDpiForStage(x: number, y: number, index: number): Promise<number>;
+    /**
+     * Recolour one DPI stage's indicator LED. Same whole-table write as
+     * `setDpiForStage`, changing `rgb` instead of the resolution. `color` is
+     * `#rrggbb`; returns it normalised.
+     */
+    setDpiStageColor(index: number, color: string): Promise<string>;
+    /**
+     * Switch which DPI stage the mouse is on. SET_DPI's byte 2 is the active
+     * index; re-send the unchanged table with it moved.
+     */
+    setActiveDpiStage(index: number): Promise<number>;
+    /** Encode the full stage table into one SET_DPI report and send it. */
+    private writeDpiTable;
+    /** A write takes the same relay path as a read, minus the read-back. */
+    private sendWrite;
+    private writeThrough;
+    readStatus(): Promise<MouseStatus>;
+    setDpi(dpi: number, dpiY?: number): Promise<number>;
+    setPollingRate(rate: number): Promise<number>;
+}
+//# sourceMappingURL=hid.d.ts.map

package/dist/drivers/gearhub/hid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid.d.ts","sourceRoot":"","sources":["../../../src/drivers/gearhub/hid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAmCL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;CACb;AAID,qBAAa,gBAAgB;IAC3B,MAAM,EAAE,SAAS,CAAC;IAClB,cAAc,SAAK;IAEnB,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAC9D,6EAA6E;IAC7E,OAAO,CAAC,eAAe,CAA+B;IAEtD,OAAO,CAAC,cAAc,CAAS;IAE/B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAuC;IAEpD,OAAO,CAAC,OAAO;gBAMH,MAAM,EAAE,SAAS;IAK7B,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;IAY9C,4EAA4E;IAC5E,IAAI,SAAS,IAAI,QAAQ,GAAG,QAAQ,CAEnC;IAED,IAAI,qBAAqB,IAAI,MAAM,EAAE,CAKpC;IAED;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IASnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,OAAO;YAUP,OAAO;IASrB;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAItD,iEAAiE;YACnD,UAAU;YAcV,WAAW;YAOX,SAAS;IAavB;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,CAAC;YAI/E,QAAQ;IAuBtB,OAAO,CAAC,WAAW;IAqBnB,oFAAoF;IAC9E,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAKpC,yEAAyE;IACnE,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAK3C;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;IAItC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAWtC,2EAA2E;IAC3E,OAAO,CAAC,aAAa;IAKrB,yEAAyE;IACnE,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAwB3E;;;;;OAKG;YACW,iBAAiB;IAgBzB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWhD,qEAAqE;IAC/D,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IASpE,8EAA8E;IAC9E,gBAAgB,IAAI,MAAM;IAI1B;4CACwC;IACxC,kBAAkB,IAAI,MAAM,EAAE;IAIxB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMlD,0EAA0E;IAC1E,eAAe,IAAI,MAAM,EAAE;IAI3B;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWvD,6EAA6E;IACvE,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1D,kEAAkE;IAC5D,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1D;;;;OAIG;IACG,YAAY,CAAC,OAAO,SAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IAQpD,OAAO,CAAC,kBAAkB;IAS1B,iEAAiE;IACjE,gBAAgB,IAAI,MAAM,EAAE;IAI5B,0EAA0E;IACpE,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE;;;;OAIG;IACG,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ1E;;;;OAIG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWrE;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQvD,uEAAuE;YACzD,aAAa;IAkB3B,wEAAwE;YAC1D,SAAS;YAIT,YAAY;IAmBpB,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAwHlC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMhD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGpD"}