@openmouse/protocol 0.1.0

package/dist/mchose/dock.js

@@ -0,0 +1,133 @@
+/**
+ * MCHOSE MagDock — the magnetic charging base, which carries the RGB the mouse
+ * itself does not have.
+ *
+ * It is a **separate device with a separate protocol**: product id `0x1012` on
+ * usage page `0xff00`, a WCH controller rather than the mouse's RealTek, and
+ * plain (non-inverted) frames on unnumbered output report 0:
+ *
+ *   [0] 0xaa start
+ *   [1] command
+ *   [2] command type — 0 request, 2 response
+ *   [3] frame sequence
+ *   [4] total frames
+ *   [5] parameter length
+ *   [6…] parameters
+ *
+ * Replies use the same layout, so a reply's payload begins at offset 6.
+ */
+export const MCHOSE_DOCK_PRODUCT_ID = 0x1012;
+export const MCHOSE_DOCK_USAGE_PAGE = 0xff00;
+export const MCHOSE_DOCK_USAGE = 0x0001;
+/** Unnumbered report: the id byte is 0. */
+export const MCHOSE_DOCK_REPORT_ID = 0;
+export const MCHOSE_DOCK_FRAME_LENGTH = 63;
+export const MCHOSE_DOCK_PAYLOAD_OFFSET = 6;
+const START = 0xaa;
+const REQUEST = 0;
+const RESPONSE = 2;
+export const MCHOSE_DOCK_COMMAND = {
+    readLighting: 7,
+    writeLighting: 39,
+};
+export function mchoseDockEncode(command, params = []) {
+    const frame = new Uint8Array(MCHOSE_DOCK_FRAME_LENGTH);
+    frame[0] = START;
+    frame[1] = command;
+    frame[2] = REQUEST;
+    frame[3] = 0;
+    frame[4] = 0;
+    frame[5] = params.length;
+    params.forEach((value, index) => { frame[MCHOSE_DOCK_PAYLOAD_OFFSET + index] = value & 0xff; });
+    return frame;
+}
+/** Payload of a reply to `command`, or null when this is not that reply. */
+export function mchoseDockPayload(raw, command) {
+    if (raw.length <= MCHOSE_DOCK_PAYLOAD_OFFSET)
+        return null;
+    if (raw[0] !== START || raw[1] !== command)
+        return null;
+    if (raw[2] !== RESPONSE && raw[2] !== REQUEST)
+        return null;
+    return raw.subarray(MCHOSE_DOCK_PAYLOAD_OFFSET);
+}
+/**
+ * Effect ids, from MCHOSE's own enum
+ * (`{static:0, breath:1, shiningBrightly:2, loop:3, goFlow:4, music:5}`).
+ */
+export const MCHOSE_DOCK_EFFECT = {
+    static: 0,
+    breathing: 1,
+    shining: 2,
+    cycling: 3,
+    flow: 4,
+    music: 5,
+};
+/**
+ * The shared `MouseLightingMode` union has no MCHOSE-specific names, so each
+ * effect is mapped to its nearest shared label. "Shining" and "music" have no
+ * exact counterpart — they are approximated by Spectrum and Reactive, which is
+ * how they read in the panel.
+ */
+export const MCHOSE_DOCK_MODE_LABELS = [
+    [MCHOSE_DOCK_EFFECT.static, "Static"],
+    [MCHOSE_DOCK_EFFECT.breathing, "Breathing single"],
+    [MCHOSE_DOCK_EFFECT.shining, "Spectrum"],
+    [MCHOSE_DOCK_EFFECT.cycling, "Cycling"],
+    [MCHOSE_DOCK_EFFECT.flow, "Wave"],
+    [MCHOSE_DOCK_EFFECT.music, "Reactive"],
+];
+/** Effects that actually use the base colour; the rest animate their own. */
+export const MCHOSE_DOCK_COLOR_MODES = ["Static", "Breathing single"];
+/** Brightness and speed are both 0-4 in the protocol. */
+export const MCHOSE_DOCK_LEVELS = [0, 1, 2, 3, 4];
+export function mchoseDockDecodeLighting(payload) {
+    if (payload.length < 30)
+        return null;
+    return {
+        enabled: payload[0] === 1,
+        effect: payload[1] ?? 0,
+        effectCount: payload[2] ?? 0,
+        speed: payload[3] ?? 0,
+        brightness: payload[4] ?? 0,
+        musicSync: payload[5] === 1,
+        color: [payload[6] ?? 0, payload[7] ?? 0, payload[8] ?? 0],
+        direction: payload[29] ?? 0,
+    };
+}
+/**
+ * The write takes every field at once — there is no partial update — so a
+ * caller changing one thing must supply the rest as they were.
+ */
+export function mchoseDockEncodeLighting(state) {
+    return mchoseDockEncode(MCHOSE_DOCK_COMMAND.writeLighting, [
+        state.enabled ? 1 : 0,
+        state.effect,
+        state.effectCount,
+        state.speed,
+        state.brightness,
+        state.musicSync ? 1 : 0,
+        state.color[0],
+        state.color[1],
+        state.color[2],
+        state.direction,
+    ]);
+}
+export function mchoseDockModeLabel(effect) {
+    return MCHOSE_DOCK_MODE_LABELS.find(([id]) => id === effect)?.[1] ?? "Static";
+}
+export function mchoseDockEffectFor(label) {
+    return MCHOSE_DOCK_MODE_LABELS.find(([, name]) => name === label)?.[0] ?? null;
+}
+const clampByte = (value) => Math.max(0, Math.min(255, Math.round(value)));
+export function mchoseDockColorToHex(color) {
+    return `#${color.map((c) => clampByte(c).toString(16).padStart(2, "0")).join("")}`;
+}
+export function mchoseDockColorFromHex(hex) {
+    const match = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!match)
+        return null;
+    const value = parseInt(match[1], 16);
+    return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+//# sourceMappingURL=dock.js.map

package/dist/mchose/dock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock.js","sourceRoot":"","sources":["../../src/mchose/dock.ts"],"names":[],"mappings":"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"}

package/dist/mchose/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Pure MCHOSE codecs, unit-tested without WebHID.
+ *
+ * Reverse-engineered from MCHOSE's own M HUB web driver and verified against an
+ * A7 V2 Ultra+ on its 2.4 GHz receiver; see docs/mchose-protocol.md for the
+ * capture notes and the dead ends.
+ *
+ * Transport: feature reports on the `0xff01` vendor collection. Report `0x11`
+ * carries the short (20-byte) command set, report `0x12` the long (64-byte)
+ * one. The distinguishing quirk is that **the whole command body is sent
+ * bit-inverted, and replies come back inverted too**:
+ *
+ *   sendFeatureReport(0x11, [~cmd, ~arg0, …])
+ *   receiveFeatureReport(0x11) -> [reportId, ~cmd, ~payload0, …]
+ *
+ * Only the bytes the vendor actually spells out are inverted; the rest of the
+ * report is zero-padded, which is why replies carry unrelated trailing bytes —
+ * the firmware leaves stale scratch data past the meaningful fields.
+ */
+export declare const MCHOSE_VENDOR_ID = 14391;
+/** Vendor configuration collection. */
+export declare const MCHOSE_CONFIG_USAGE_PAGE = 65281;
+export declare const MCHOSE_CONFIG_USAGE = 1;
+/** Short command channel: command + 19 argument bytes. */
+export declare const MCHOSE_SHORT_REPORT_ID = 17;
+export declare const MCHOSE_SHORT_TOKENS = 20;
+/** Long command channel: command + 63 argument bytes. */
+export declare const MCHOSE_LONG_REPORT_ID = 18;
+export declare const MCHOSE_LONG_TOKENS = 64;
+export declare const MCHOSE_REPORT_LENGTH = 64;
+export declare const MCHOSE_COMMAND: {
+    /** Receiver identity: bond flag, ids, link state. */
+    readonly identity: 3;
+    /** Firmware version, as a length-prefixed ASCII string. */
+    readonly version: 4;
+    /** Mouse identity plus battery level and charge state. */
+    readonly battery: 6;
+    /** Whole configuration blob: DPI stages, per-link indices, debounce, sleep. */
+    readonly config: 103;
+    /** Writes the same blob back, one command byte in front of the same layout. */
+    readonly writeConfig: 87;
+    /** Switches the active onboard profile; takes a single 0-based index. */
+    readonly setProfile: 88;
+    /** Reassigns one button: `[buttonIndex, reserved, type, value u24 BE]`. */
+    readonly setButton: 82;
+    /** Reads one button's name, which is where a macro's name lives. */
+    readonly readButtonName: 99;
+    /** Reads one profile's name: `[index]`, replying index + ASCII. */
+    readonly readProfileName: 104;
+    /** Sets the auto-sleep timer: `[enabled, minutes]`. */
+    readonly setSleep: 10;
+    /**
+     * Performance block: `[lod, ripple, line, motionSync, _, _, mode,
+     * rotateOpen, rotateVal]`.
+     */
+    readonly setPerformance: 66;
+};
+/**
+ * The config blob's `sensor` byte (offset 17) is a bitfield holding lift-off
+ * distance *and* the three processing toggles. Every one of these is written
+ * through the performance command rather than the config write, and read back
+ * out of this byte. Mapped bit by bit on hardware:
+ *
+ *   0x80 -> 0x90  motion sync on        (bit 4)
+ *   0x90 -> 0x94  ripple control on     (bit 2)
+ *   0x94 -> 0x9c  linear correction on  (bit 3)
+ *
+ * Bits 6-7 are the performance mode — see `MCHOSE_SENSOR_MODE_MASK` below. An
+ * earlier reading of this byte took bit 7 alone to be a boolean "game mode",
+ * which is wrong: M HUB offers three modes, and bit 6 is the other half.
+ *
+ * Lift-off therefore occupies only **bits 0-1**; treating it as three bits
+ * would read ripple as part of the level. Bit 5 is still unexplained, so
+ * writers must preserve the rest of the byte rather than assign it.
+ */
+export declare const MCHOSE_LOD_MASK = 3;
+export declare const MCHOSE_SENSOR_RIPPLE = 4;
+export declare const MCHOSE_SENSOR_LINEAR = 8;
+export declare const MCHOSE_SENSOR_MOTION_SYNC = 16;
+/**
+ * Bits 6-7 hold the **performance mode**, which M HUB presents as a three-way
+ * choice rather than a switch. Mapped on hardware by writing each value:
+ *
+ *   field 7 = 1 -> bits 00 -> Performance
+ *   field 7 = 2 -> bits 10 -> eSports
+ *   field 7 = 3 -> bits 11 -> Ultra
+ *
+ * Note the gap: the stored bit pattern is the mode number except for
+ * Performance, which stores 0 rather than 1.
+ */
+export declare const MCHOSE_SENSOR_MODE_MASK = 192;
+export declare const MCHOSE_MODES: readonly string[];
+/** Decode bits 6-7 into a 1-based mode number. */
+export declare function mchoseDecodeMode(sensor: number): number;
+export declare function mchoseModeName(sensor: number): string;
+export declare function mchoseModeNumber(name: string): number | null;
+/**
+ * Angle tuning, in the config blob at offset 49. M HUB offers -30 to +30
+ * degrees; the byte is stored as-is, so negatives are two's complement. The
+ * firmware does not validate the value — it stored 0xf1 and 0x8f unchanged —
+ * so the range has to be enforced here.
+ *
+ * M HUB flags this control with "update the mouse firmware", so older firmware
+ * may ignore it.
+ */
+export declare const MCHOSE_ANGLE_TUNING_OFFSET = 49;
+export declare const MCHOSE_ANGLE_TUNING_MIN = -30;
+export declare const MCHOSE_ANGLE_TUNING_MAX = 30;
+export declare function mchoseDecodeAngleTuning(raw: number): number;
+export declare function mchoseEncodeAngleTuning(degrees: number): number;
+export declare function mchoseDecodeLiftOffIndex(sensor: number): number;
+export interface MchoseProcessing {
+    /** MCHOSE calls this "linear correction"; it is angle snapping. */
+    angleSnapping: boolean;
+    rippleControl: boolean;
+    motionSync: boolean;
+}
+export declare function mchoseDecodeProcessing(sensor: number): MchoseProcessing;
+/**
+ * Build the performance write.
+ *
+ * Lift-off must be supplied every time, because index 0 is a real level and so
+ * cannot double as "unchanged" the way the toggles' 0 does. Pass only the
+ * toggles being changed and the rest are left as they are.
+ */
+export declare function mchoseEncodePerformance(liftOffIndex: number, changes?: Partial<MchoseProcessing> & {
+    mode?: number;
+    angleTuning?: number;
+}): number[];
+/** Lift-off on its own, leaving every processing toggle untouched. */
+export declare function mchoseEncodeLiftOff(index: number): number[];
+/** The shared three-stop labels, positioned by how many steps a model offers. */
+export type MchoseLiftOffLabel = "Low" | "Medium" | "High";
+export declare function mchoseLiftOffLabels(steps: number): MchoseLiftOffLabel[];
+/**
+ * Auto-sleep is stored in whole minutes at offset 19 of the config blob, and
+ * written with its own command rather than through the config write. Confirmed
+ * on hardware: sending `0x0a 01 09` moved that byte from 0 to 9.
+ *
+ * The device is slower to apply this than a config write — it needs roughly a
+ * second before the new value reads back.
+ */
+export declare const MCHOSE_SLEEP_MAX_MINUTES = 255;
+/** Sleep timeouts offered in the UI, in seconds; 0 disables the timer. */
+export declare const MCHOSE_SLEEP_OPTIONS: readonly number[];
+/** Longest debounce the firmware accepts, in milliseconds. */
+export declare const MCHOSE_DEBOUNCE_MAX_MS = 20;
+export declare function mchoseEncodeSleep(minutes: number): number[];
+/**
+ * Onboard profiles, 0-based on the wire. The mouse holds three, each with its
+ * own DPI stage table and its own per-link rate/stage pair — confirmed by
+ * switching an A7 V2 Ultra+ through all three and reading each back.
+ *
+ * `0x67` has no profile argument: it always answers for whichever profile is
+ * active, so reading another one means switching to it first.
+ */
+export declare const MCHOSE_PROFILE_COUNT = 3;
+/** Build the `0x58` payload. `index` is 0-based, as the firmware expects. */
+export declare function mchoseEncodeSetProfile(index: number): number[];
+/**
+ * Build a feature-report body. `tokens` is the command byte followed by its
+ * arguments, exactly as the vendor spells them; everything given is inverted
+ * and the remainder of the report stays zero.
+ */
+export declare function mchoseEncodeCommand(tokens: readonly number[], tokenCount: number): Uint8Array<ArrayBuffer>;
+export interface MchoseReply {
+    command: number;
+    payload: Uint8Array;
+}
+/**
+ * Decode a feature-report read. `raw` is the buffer as returned by
+ * `receiveFeatureReport`, whose first byte is the report id.
+ */
+export declare function mchoseDecodeReply(raw: Uint8Array): MchoseReply | null;
+export interface MchoseIdentity {
+    bonded: boolean;
+    vendorId: number;
+    productId: number;
+    connected: boolean;
+    gameMode: number;
+}
+export declare function mchoseDecodeIdentity(payload: Uint8Array): MchoseIdentity | null;
+/** Length-prefixed ASCII, e.g. `08 "5.46.2.4"`. */
+export declare function mchoseDecodeVersion(payload: Uint8Array): string | null;
+export interface MchoseBattery {
+    vendorId: number;
+    /** The mouse's own product id, even when read through the receiver. */
+    productId: number;
+    firmwareVersion: number;
+    connectMode: number;
+    connected: boolean;
+    batteryPercent: number;
+    charging: boolean;
+}
+export declare function mchoseDecodeBattery(payload: Uint8Array): MchoseBattery | null;
+export declare const MCHOSE_DPI_STAGES = 6;
+export interface MchoseConfig {
+    profileIndex: number;
+    /** Active DPI stage and polling index on the 2.4 GHz link. */
+    wirelessDpiIndex: number;
+    wirelessRateIndex: number;
+    /** Active DPI stage and polling index on the wired link. */
+    wiredDpiIndex: number;
+    wiredRateIndex: number;
+    /** Six DPI stages, little-endian uint16 each. */
+    dpiStages: number[];
+    stageCount: number;
+    sensor: number;
+    /** Lift-off step, decoded out of the low bits of `sensor`. */
+    liftOffIndex: number;
+    /** Processing toggles, decoded out of the same `sensor` byte. */
+    processing: MchoseProcessing;
+    keyDebounce: number;
+    sleep: number;
+    /** Angle-tuning degrees at offset 49; 0 is no correction. */
+    angleTuning: number;
+    /** Performance mode name, from bits 6-7 of `sensor`. */
+    mode: string;
+}
+/**
+ * Note the reserved byte at offset 3: the DPI stages start at offset 4, not
+ * immediately after the two index bytes.
+ *
+ * MCHOSE ships two schemas for this payload and they contradict each other.
+ * The layout below is the one the hardware actually uses, confirmed on an
+ * A7 V2 Ultra+ by reading it at two known settings:
+ *
+ *   125 Hz / 1600 DPI -> byte2 0x00   (rate index 0, stage 0)
+ *   1000 Hz / 1600 DPI -> byte2 0x20  (rate index 2, stage 0)
+ *
+ * So the **wired** byte comes first, the **rate** is the high nibble, and the
+ * rate is a plain index into the model's rate list with no skipped value. That
+ * matches the vendor's write schema; its read schema has both the byte order
+ * and the nibble order backwards. Do not "correct" this to match the latter.
+ */
+export declare function mchoseDecodeConfig(payload: Uint8Array): MchoseConfig | null;
+/** Pack a link's rate/stage pair back into its byte: rate high, stage low. */
+export declare function mchosePackLinkByte(rateIndex: number, dpiIndex: number): number;
+/**
+ * Build the `0x57` write payload from a payload previously read with `0x67`.
+ *
+ * The write layout is exactly the read layout with a command byte in front, so
+ * a change is applied by echoing every other byte back untouched — which is
+ * what keeps button mappings, macros and DPI values from being wiped by a
+ * partial write.
+ */
+export declare function mchoseEncodeConfigWrite(readPayload: Uint8Array, changes?: {
+    wiredRateIndex?: number;
+    wiredDpiIndex?: number;
+    wirelessRateIndex?: number;
+    wirelessDpiIndex?: number;
+    dpiStages?: readonly number[];
+    keyDebounce?: number;
+    stageCount?: number;
+}): number[];
+/**
+ * PIDs shared by the whole A7 V2 family, so they identify a link rather than a
+ * model. The receiver is the endpoint the host talks to; the mouse reports its
+ * own model-specific id inside the battery reply.
+ */
+export declare const MCHOSE_LINK_PRODUCT_IDS: {
+    readonly receiver: 4107;
+    readonly bluetooth: 4106;
+    readonly receiver8k: 4128;
+};
+export interface MchoseProduct {
+    name: string;
+    /** The mouse's own product id, model-specific. */
+    productId: number;
+    dpiMax: number;
+    /** Lift-off steps in millimetres, in firmware index order. */
+    liftOffDistances: readonly number[];
+    /** Highest polling rate on a wired or 2.4 GHz link. */
+    maxPollingRate: number;
+}
+/** The A7 V2 family, from the M HUB bundle's own model table. */
+export declare const MCHOSE_PRODUCTS: readonly MchoseProduct[];
+/** Rate lists the firmware exposes, keyed by the model's maximum rate. */
+export declare const MCHOSE_POLLING_RATES: Readonly<Record<number, readonly number[]>>;
+/**
+ * Identify the model. The id inside the battery reply is decisive; the host-
+ * facing PID is shared across the family, so the product string is the only
+ * fallback, and an unrecognised one yields null rather than a wrong DPI ceiling.
+ */
+export declare function mchoseFindProduct(mouseProductId: number | null, productName?: string | null): MchoseProduct | null;
+/** Polling rates available on the link this host-facing product id represents. */
+export declare function mchosePollingRates(product: MchoseProduct, hostProductId: number): readonly number[];
+export * from "./buttons.ts";
+export * from "./dock.ts";
+export * from "./a5-gen1.ts";
+export * from "./v3.ts";
+/**
+ * Profile names, read one at a time with `0x12 0x68 <index>`. The reply is the
+ * profile index followed by a NUL-terminated ASCII name — the test hardware
+ * answered "Config 1", "Config 2", "Config 3".
+ */
+export declare function mchoseEncodeReadProfileName(index: number): number[];
+export declare function mchoseDecodeProfileName(payload: Uint8Array): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/mchose/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mchose/index.ts"],"names":[],"mappings":"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"}