@openmouse/protocol 0.1.0

package/dist/atk/index.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Pure ATK (A9 family) and VXE R1 (Beken) codecs, unit-tested without WebHID.
+ *
+ * ATK shares the Endgame Gear WE framing (see endgame-gear-we.ts): feature
+ * command 0x08 reads an EEPROM address, 0x07 writes one, every frame and every
+ * value/checksum pair sums to 0x55. Only the DPI stage encoding differs — ATK
+ * packs a mode nibble per axis so newer sensors reach 42,000 DPI.
+ *
+ * VXE R1 SE/SE+ ("Wireless mouse -1k dongle", 0x373b:0x1085, Beken MCU) uses
+ * the same framing and the same DPI/advanced registers as the A9 family, but
+ * stores the polling rate in a live-settings row at 0x0070 keyed by a selector
+ * byte. The mapping below comes from the OpenVXE tracker (BuSd777/OpenVXE),
+ * the only reverse-engineering project that targets this exact receiver PID.
+ */
+export type AtkSensor = "PAW3950Ultra" | "PAW3950" | "PAW3950DM" | "PAW3395Ultra" | "PAW3395" | "PAW3395SE" | "CORE26K" | "PAW3955Master";
+export type AtkDpiFamily = "ultra" | "step50" | "paw3395se" | "paw3955master";
+export interface AtkSensorProfile {
+    family: AtkDpiFamily;
+    minDpi: number;
+    maxDpi: number;
+}
+/** Limits and encoding families transcribed from ATK HUB 3.2.21. */
+export declare const ATK_SENSORS: Record<AtkSensor, AtkSensorProfile>;
+/**
+ * Per-axis mode nibble: bits 2-3 extend the value byte, bit 1 selects the
+ * 50-DPI step range above 10,000, bit 0 doubles the result above 30,000.
+ */
+export declare function atkEncodeDpiAxis(dpi: number): {
+    byte: number;
+    nibble: number;
+};
+export declare function atkDecodeDpiAxis(byte: number, nibble: number): number;
+/** One DPI stage: [x, y, packed nibbles, checksum]. */
+export declare function atkPackDpiStage(x: number, y: number): number[];
+export declare function atkUnpackDpiStage(data: Uint8Array | readonly number[]): {
+    x: number;
+    y: number;
+} | null;
+/** Byte length of one DPI stage row for this sensor: 6 for PAW3955 Master, 4 otherwise. */
+export declare function atkDpiStageLength(sensor: AtkSensor | null): number;
+export declare function atkPackDpiStageForSensor(sensor: AtkSensor | null, x: number, y: number): number[] | null;
+export declare function atkUnpackDpiStageForSensor(sensor: AtkSensor | null, data: Uint8Array | readonly number[]): {
+    x: number;
+    y: number;
+} | null;
+export declare function atkDpiOptionsForSensor(sensor: AtkSensor): number[];
+/** Register holds tenths of a millimetre offset by 6 (code 1 = 0.7 mm). */
+export declare function atkDecodeLiftOff(code: number): number | null;
+export declare const ATK_LIFT_OFF_MIN_CODE = 1;
+export declare const ATK_LIFT_OFF_MAX_CODE = 11;
+export declare function atkEncodeLiftOff(millimetres: number): number;
+/**
+ * Address of the R1's live-settings row. It carries several settings as
+ * [selector, value, 0x00, checksum], so a write must always include the
+ * selector byte. Applying an entry over the row updates that setting live
+ * without rewriting the persisted EEPROM.
+ */
+export declare const ATK_VXE_R1_SETTINGS_REGISTER = 112;
+/** Selector for the angle-snapping flag (value 0x10 on, 0x00 off). */
+export declare const ATK_VXE_R1_ANGLE_SELECTOR = 1;
+/** Selector for the debounce entry (value is milliseconds, 1-20). */
+export declare const ATK_VXE_R1_DEBOUNCE_SELECTOR = 2;
+/** Selector for the lift-off level (value 1 low, 2 high). */
+export declare const ATK_VXE_R1_LOD_SELECTOR = 3;
+/** Selector for the 250/500/1000 Hz polling-rate entry. */
+export declare const ATK_VXE_R1_POLLING_SELECTOR = 11;
+/** Rates the R1 SE/SE+ offers on its stock 1K receiver. */
+export declare const ATK_VXE_R1_POLLING_RATES: readonly number[];
+/** Build the 4-byte live-settings row for a given selector/value pair. */
+export declare function atkPackVxeR1LiveSetting(selector: number, value: number): number[];
+/** Build the 4-byte live-settings polling row, or null for an unsupported rate. */
+export declare function atkPackVxeR1PollingSetting(pollingRateHz: number): number[] | null;
+/** Decode the value byte of an R1 polling row, or null if unrecognised. */
+export declare function atkDecodeVxeR1PollingCode(code: number): number | null;
+/** Command ids used by the COMPX configuration transport. */
+export declare const ATK_COMPX_COMMAND: {
+    readonly getWirelessMouseOnline: 3;
+    readonly setWirelessDonglePair: 5;
+    readonly getWirelessDonglePairResult: 6;
+    readonly restoreFactory: 9;
+    readonly enterUsbUpgradeMode: 13;
+    readonly getCurrentConfig: 14;
+    readonly setCurrentConfig: 15;
+    readonly dongleExitPair: 19;
+    readonly getDongleVersion: 29;
+    readonly reportMouseUpgradeError: 90;
+    readonly reportMouseUpgradeStatus: 91;
+};
+/** The R1 HUB profile picker exposes four firmware-managed configuration banks. */
+export declare const ATK_R1_PROFILE_COUNT = 4;
+export declare function atkDecodeCurrentProfile(data: Uint8Array | readonly number[]): number | null;
+/** Build SetCurrentConfig with the vendor's length byte and zero-based bank. */
+export declare function atkBuildSetCurrentProfile(profile: number): Uint8Array;
+/** Build SetWirelessDonglePair for one exact mouse model identity. */
+export declare function atkBuildReceiverPairRequest(cid: number, mid: number): Uint8Array;
+export declare const ATK_R1_BUTTONS: readonly [{
+    readonly id: "left";
+    readonly label: "Left button";
+    readonly address: 96;
+}, {
+    readonly id: "right";
+    readonly label: "Right button";
+    readonly address: 100;
+}, {
+    readonly id: "middle";
+    readonly label: "Middle button";
+    readonly address: 104;
+}, {
+    readonly id: "back";
+    readonly label: "Back button";
+    readonly address: 108;
+}, {
+    readonly id: "forward";
+    readonly label: "Forward button";
+    readonly address: 112;
+}, {
+    readonly id: "bottom";
+    readonly label: "Bottom button";
+    readonly address: 116;
+}];
+export declare const ATK_R1_SHORTCUT_BASE = 256;
+export declare const ATK_R1_SHORTCUT_SLOT_LENGTH = 32;
+export declare const ATK_R1_MACRO_BASE = 768;
+export declare const ATK_R1_MACRO_SLOT_LENGTH = 384;
+export declare const ATK_R1_MACRO_SLOT_COUNT = 12;
+export type AtkR1ButtonId = (typeof ATK_R1_BUTTONS)[number]["id"];
+/** Four-byte EEPROM button assignment: class, value 1, value 2, checksum. */
+export interface AtkButtonAssignment {
+    keyClass: number;
+    value1: number;
+    value2: number;
+    checksum: number;
+    checksumValid: boolean;
+    label: string;
+    raw: string;
+}
+export declare const ATK_BUTTON_CLASS: {
+    readonly disabled: 0;
+    readonly mouse: 1;
+    readonly dpi: 2;
+    readonly horizontalScroll: 3;
+    readonly firepower: 4;
+    readonly shortcut: 5;
+    readonly macro: 6;
+    readonly reportRate: 7;
+    readonly lighting: 8;
+    readonly profile: 9;
+    readonly dpiLock: 10;
+    readonly wheel: 11;
+};
+/** Describe only action values whose meaning is present in the vendor enum. */
+export declare function atkDescribeButtonAction(keyClass: number, value1: number, value2: number): string;
+export declare function atkDecodeButtonAssignment(data: Uint8Array | readonly number[]): AtkButtonAssignment | null;
+export interface AtkReceiverStatus {
+    online: boolean;
+    status: number;
+    /** RF id in the firmware's rfId1/rfId2/rfId3 display order. */
+    rfId: string;
+}
+export declare function atkDecodeReceiverStatus(data: Uint8Array | readonly number[]): AtkReceiverStatus | null;
+export interface AtkPairingStatus {
+    status: number;
+    secondsRemaining: number;
+}
+export declare function atkDecodePairingStatus(data: Uint8Array | readonly number[]): AtkPairingStatus | null;
+export declare const ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET = 8192;
+export declare const ATK_COMPX_FIRMWARE_HEADER_LENGTH = 720;
+export interface AtkFirmwareEndpoint {
+    vendorId: number;
+    productId: number;
+    path: string;
+}
+export interface AtkCompxFirmwareInfo {
+    headerCrc: number;
+    headerLength: number;
+    firmwareLength: number;
+    nextFileAddress: number;
+    version: string;
+    deviceType: number;
+    cid: number;
+    mid: number;
+    fileId: string;
+    icName: string;
+    sensorName: string;
+    productName: string;
+    bootInput: AtkFirmwareEndpoint;
+    bootOutput: AtkFirmwareEndpoint;
+    normalInput: AtkFirmwareEndpoint;
+    normalOutput: AtkFirmwareEndpoint;
+    resetCommand: Uint8Array;
+    prepareCommand: Uint8Array;
+    downloadCommand: Uint8Array;
+    payloadCrc: number;
+    payloadCrcValid: boolean;
+}
+/** CRC-32 register state used by COMPX packages: init 0xffffffff, no final xor. */
+export declare function atkCompxPayloadCrc(data: Uint8Array): number;
+/** Parse and integrity-check the first firmware image in a COMPX package. */
+export declare function atkParseCompxFirmware(data: Uint8Array): AtkCompxFirmwareInfo;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/atk/index.js

@@ -0,0 +1,480 @@
+/**
+ * Pure ATK (A9 family) and VXE R1 (Beken) codecs, unit-tested without WebHID.
+ *
+ * ATK shares the Endgame Gear WE framing (see endgame-gear-we.ts): feature
+ * command 0x08 reads an EEPROM address, 0x07 writes one, every frame and every
+ * value/checksum pair sums to 0x55. Only the DPI stage encoding differs — ATK
+ * packs a mode nibble per axis so newer sensors reach 42,000 DPI.
+ *
+ * VXE R1 SE/SE+ ("Wireless mouse -1k dongle", 0x373b:0x1085, Beken MCU) uses
+ * the same framing and the same DPI/advanced registers as the A9 family, but
+ * stores the polling rate in a live-settings row at 0x0070 keyed by a selector
+ * byte. The mapping below comes from the OpenVXE tracker (BuSd777/OpenVXE),
+ * the only reverse-engineering project that targets this exact receiver PID.
+ */
+const CHECKSUM_TOTAL = 0x55;
+/** Limits and encoding families transcribed from ATK HUB 3.2.21. */
+export const ATK_SENSORS = {
+    PAW3950Ultra: { family: "ultra", minDpi: 10, maxDpi: 42000 },
+    PAW3950: { family: "step50", minDpi: 50, maxDpi: 36000 },
+    PAW3950DM: { family: "step50", minDpi: 50, maxDpi: 36000 },
+    PAW3395Ultra: { family: "step50", minDpi: 100, maxDpi: 30000 },
+    PAW3395: { family: "step50", minDpi: 100, maxDpi: 30000 },
+    PAW3395SE: { family: "paw3395se", minDpi: 200, maxDpi: 18000 },
+    CORE26K: { family: "step50", minDpi: 50, maxDpi: 26000 },
+    PAW3955Master: { family: "paw3955master", minDpi: 50, maxDpi: 40000 },
+};
+const PAW3395SE_INVALID_CODES = new Set([
+    7, 13, 20, 26, 33, 40, 46, 53, 60, 66, 73, 80, 86, 93, 100, 106, 113,
+    120, 126, 133, 140, 146, 153, 160, 166, 173, 180, 186, 193, 200, 206,
+    213, 220, 226, 233,
+]);
+const PAW3395SE_CODES = Array.from({ length: 235 }, (_, index) => index + 1)
+    .filter((code) => !PAW3395SE_INVALID_CODES.has(code));
+/**
+ * Per-axis mode nibble: bits 2-3 extend the value byte, bit 1 selects the
+ * 50-DPI step range above 10,000, bit 0 doubles the result above 30,000.
+ */
+export function atkEncodeDpiAxis(dpi) {
+    let value = dpi;
+    let doubled = 0;
+    if (value > 30000) {
+        doubled = 1;
+        value = Math.round(value / 2);
+    }
+    if (value <= 10000) {
+        const code = Math.floor(value / 10) - 1;
+        return { byte: code & 0xff, nibble: ((code >> 8) << 2) | doubled };
+    }
+    const code = Math.floor((value - 10050) / 50);
+    return { byte: code & 0xff, nibble: ((code >> 8) << 2) | 2 | doubled };
+}
+export function atkDecodeDpiAxis(byte, nibble) {
+    const code = (((nibble >> 2) & 0x03) << 8) | (byte & 0xff);
+    const base = (nibble & 2) !== 0 ? 10050 + code * 50 : (code + 1) * 10;
+    return (nibble & 1) !== 0 ? base * 2 : base;
+}
+/** One DPI stage: [x, y, packed nibbles, checksum]. */
+export function atkPackDpiStage(x, y) {
+    const encodedX = atkEncodeDpiAxis(x);
+    const encodedY = atkEncodeDpiAxis(y);
+    const mode = ((encodedY.nibble & 0x0f) << 4) | (encodedX.nibble & 0x0f);
+    const sum = (encodedX.byte + encodedY.byte + mode) & 0xff;
+    return [encodedX.byte, encodedY.byte, mode, (CHECKSUM_TOTAL - sum) & 0xff];
+}
+export function atkUnpackDpiStage(data) {
+    if (data.length < 4)
+        return null;
+    const sum = (data[0] + data[1] + data[2] + data[3]) & 0xff;
+    if (sum !== CHECKSUM_TOTAL)
+        return null;
+    return {
+        x: atkDecodeDpiAxis(data[0], data[2] & 0x0f),
+        y: atkDecodeDpiAxis(data[1], (data[2] >> 4) & 0x0f),
+    };
+}
+function atkEncodeDpiAxisStep50(dpi) {
+    const doubled = dpi > 30000;
+    const count = Math.round(dpi / (doubled ? 100 : 50)) - 1;
+    return { byte: count & 0xff, nibble: (((count >> 8) & 0x03) << 2) | (doubled ? 1 : 0) };
+}
+function atkDecodeDpiAxisStep50(byte, nibble) {
+    const count = (byte & 0xff) | (((nibble >> 2) & 0x03) << 8);
+    const dpi = (count + 1) * 50;
+    return (nibble & 1) !== 0 ? dpi * 2 : dpi;
+}
+function atkEncodeDpiAxisPaw3395Se(dpi) {
+    const doubled = dpi > 10000;
+    const baseDpi = doubled ? dpi / 2 : dpi;
+    if (!Number.isInteger(baseDpi) || baseDpi < 50 || baseDpi > 10000 || baseDpi % 50 !== 0)
+        return null;
+    const code = PAW3395SE_CODES[baseDpi / 50 - 1];
+    return code === undefined ? null : { byte: code, nibble: doubled ? 2 : 0 };
+}
+function atkDecodeDpiAxisPaw3395Se(byte, nibble) {
+    if ((nibble & ~2) !== 0)
+        return null;
+    const index = PAW3395SE_CODES.indexOf(byte & 0xff);
+    if (index < 0)
+        return null;
+    const baseDpi = (index + 1) * 50;
+    if ((nibble & 2) !== 0)
+        return baseDpi > 5000 ? baseDpi * 2 : null;
+    return baseDpi;
+}
+function atkEncodeDpiAxisPaw3955Master(dpi) {
+    if (!Number.isInteger(dpi) || dpi < 1 || dpi > 40000)
+        return null;
+    const base = dpi - 1;
+    return { lo: base & 0xff, hi: (base >> 8) & 0xff };
+}
+function atkDecodeDpiAxisPaw3955Master(lo, hi, doubled) {
+    const dpi = (lo | (hi << 8)) + 1;
+    return doubled ? dpi * 2 : dpi;
+}
+function atkPackDpiStagePaw3955Master(x, y) {
+    const encodedX = atkEncodeDpiAxisPaw3955Master(x);
+    const encodedY = atkEncodeDpiAxisPaw3955Master(y);
+    if (!encodedX || !encodedY)
+        return null;
+    const row = [encodedX.lo, encodedX.hi, encodedY.lo, encodedY.hi, 0];
+    const sum = row.reduce((total, byte) => total + byte, 0) & 0xff;
+    return [...row, (CHECKSUM_TOTAL - sum) & 0xff];
+}
+function atkUnpackDpiStagePaw3955Master(data) {
+    if (data.length < 6)
+        return null;
+    const sum = (data[0] + data[1] + data[2] + data[3] + data[4] + data[5]) & 0xff;
+    if (sum !== CHECKSUM_TOTAL)
+        return null;
+    const flags = data[4];
+    return {
+        x: atkDecodeDpiAxisPaw3955Master(data[0], data[1], (flags & 0x01) !== 0),
+        y: atkDecodeDpiAxisPaw3955Master(data[2], data[3], (flags & 0x10) !== 0),
+    };
+}
+/** Byte length of one DPI stage row for this sensor: 6 for PAW3955 Master, 4 otherwise. */
+export function atkDpiStageLength(sensor) {
+    return sensor && ATK_SENSORS[sensor].family === "paw3955master" ? 6 : 4;
+}
+export function atkPackDpiStageForSensor(sensor, x, y) {
+    if (sensor) {
+        const options = atkDpiOptionsForSensor(sensor);
+        if (!options.includes(x) || !options.includes(y))
+            return null;
+    }
+    const family = sensor ? ATK_SENSORS[sensor].family : "ultra";
+    if (family === "paw3955master")
+        return atkPackDpiStagePaw3955Master(x, y);
+    const encode = family === "paw3395se"
+        ? atkEncodeDpiAxisPaw3395Se
+        : family === "step50"
+            ? atkEncodeDpiAxisStep50
+            : atkEncodeDpiAxis;
+    const encodedX = encode(x);
+    const encodedY = encode(y);
+    if (!encodedX || !encodedY)
+        return null;
+    const mode = ((encodedY.nibble & 0x0f) << 4) | (encodedX.nibble & 0x0f);
+    const sum = (encodedX.byte + encodedY.byte + mode) & 0xff;
+    return [encodedX.byte, encodedY.byte, mode, (CHECKSUM_TOTAL - sum) & 0xff];
+}
+export function atkUnpackDpiStageForSensor(sensor, data) {
+    const family = sensor ? ATK_SENSORS[sensor].family : "ultra";
+    if (family === "paw3955master")
+        return atkUnpackDpiStagePaw3955Master(data);
+    if (data.length < 4 || (data[0] + data[1] + data[2] + data[3]) % 0x100 !== CHECKSUM_TOTAL)
+        return null;
+    const decode = family === "paw3395se"
+        ? atkDecodeDpiAxisPaw3395Se
+        : family === "step50"
+            ? atkDecodeDpiAxisStep50
+            : atkDecodeDpiAxis;
+    const x = decode(data[0], data[2] & 0x0f);
+    const y = decode(data[1], (data[2] >> 4) & 0x0f);
+    return x === null || y === null ? null : { x, y };
+}
+export function atkDpiOptionsForSensor(sensor) {
+    const profile = ATK_SENSORS[sensor];
+    if (profile.family === "ultra") {
+        const options = [];
+        for (let dpi = profile.minDpi; dpi <= 10000; dpi += 10)
+            options.push(dpi);
+        for (let dpi = 10050; dpi <= 30000; dpi += 50)
+            options.push(dpi);
+        for (let dpi = 30100; dpi <= profile.maxDpi; dpi += 100)
+            options.push(dpi);
+        return options;
+    }
+    if (profile.family === "paw3395se") {
+        const options = [];
+        for (let dpi = profile.minDpi; dpi <= 10000; dpi += 50)
+            options.push(dpi);
+        for (let dpi = 10100; dpi <= profile.maxDpi; dpi += 100)
+            options.push(dpi);
+        return options;
+    }
+    if (profile.family === "paw3955master") {
+        const options = [];
+        for (let dpi = profile.minDpi; dpi <= profile.maxDpi; dpi += 10)
+            options.push(dpi);
+        if (options[options.length - 1] !== profile.maxDpi)
+            options.push(profile.maxDpi);
+        return options;
+    }
+    const options = [];
+    for (let dpi = profile.minDpi; dpi <= Math.min(profile.maxDpi, 30000); dpi += 50)
+        options.push(dpi);
+    for (let dpi = 30100; dpi <= profile.maxDpi; dpi += 100)
+        options.push(dpi);
+    return options;
+}
+/** Register holds tenths of a millimetre offset by 6 (code 1 = 0.7 mm). */
+export function atkDecodeLiftOff(code) {
+    return code ? (code + 6) / 10 : null;
+}
+export const ATK_LIFT_OFF_MIN_CODE = 1;
+export const ATK_LIFT_OFF_MAX_CODE = 11;
+export function atkEncodeLiftOff(millimetres) {
+    return Math.round(millimetres * 10) - 6;
+}
+// ── VXE R1 SE/SE+ live-settings polling ────────────────────────────────────
+/**
+ * Address of the R1's live-settings row. It carries several settings as
+ * [selector, value, 0x00, checksum], so a write must always include the
+ * selector byte. Applying an entry over the row updates that setting live
+ * without rewriting the persisted EEPROM.
+ */
+export const ATK_VXE_R1_SETTINGS_REGISTER = 0x0070;
+/** Selector for the angle-snapping flag (value 0x10 on, 0x00 off). */
+export const ATK_VXE_R1_ANGLE_SELECTOR = 0x01;
+/** Selector for the debounce entry (value is milliseconds, 1-20). */
+export const ATK_VXE_R1_DEBOUNCE_SELECTOR = 0x02;
+/** Selector for the lift-off level (value 1 low, 2 high). */
+export const ATK_VXE_R1_LOD_SELECTOR = 0x03;
+/** Selector for the 250/500/1000 Hz polling-rate entry. */
+export const ATK_VXE_R1_POLLING_SELECTOR = 0x0b;
+/** Rates the R1 SE/SE+ offers on its stock 1K receiver. */
+export const ATK_VXE_R1_POLLING_RATES = [250, 500, 1000];
+const VXE_POLLING_CODES = [
+    [0x03, 250],
+    [0x02, 500],
+    [0x01, 1000],
+];
+/** Build the 4-byte live-settings row for a given selector/value pair. */
+export function atkPackVxeR1LiveSetting(selector, value) {
+    return [selector, value, 0x00, (CHECKSUM_TOTAL - value) & 0xff];
+}
+/** Build the 4-byte live-settings polling row, or null for an unsupported rate. */
+export function atkPackVxeR1PollingSetting(pollingRateHz) {
+    const rate = VXE_POLLING_CODES.find(([, hertz]) => hertz === pollingRateHz);
+    if (!rate)
+        return null;
+    return atkPackVxeR1LiveSetting(ATK_VXE_R1_POLLING_SELECTOR, rate[0]);
+}
+/** Decode the value byte of an R1 polling row, or null if unrecognised. */
+export function atkDecodeVxeR1PollingCode(code) {
+    return VXE_POLLING_CODES.find(([value]) => (value & 0xff) === (code & 0xff))?.[1] ?? null;
+}
+// ── COMPX command and stored-profile inspection ────────────────────────────
+/** Command ids used by the COMPX configuration transport. */
+export const ATK_COMPX_COMMAND = {
+    getWirelessMouseOnline: 0x03,
+    setWirelessDonglePair: 0x05,
+    getWirelessDonglePairResult: 0x06,
+    restoreFactory: 0x09,
+    enterUsbUpgradeMode: 0x0d,
+    getCurrentConfig: 0x0e,
+    setCurrentConfig: 0x0f,
+    dongleExitPair: 0x13,
+    getDongleVersion: 0x1d,
+    reportMouseUpgradeError: 0x5a,
+    reportMouseUpgradeStatus: 0x5b,
+};
+/** The R1 HUB profile picker exposes four firmware-managed configuration banks. */
+export const ATK_R1_PROFILE_COUNT = 4;
+export function atkDecodeCurrentProfile(data) {
+    const profile = data[0];
+    return profile !== undefined && profile < ATK_R1_PROFILE_COUNT ? profile : null;
+}
+/** Build SetCurrentConfig with the vendor's length byte and zero-based bank. */
+export function atkBuildSetCurrentProfile(profile) {
+    if (!Number.isInteger(profile) || profile < 0 || profile >= ATK_R1_PROFILE_COUNT) {
+        throw new Error(`ATK profile must be between 0 and ${ATK_R1_PROFILE_COUNT - 1}.`);
+    }
+    const payload = new Uint8Array(16);
+    payload[0] = ATK_COMPX_COMMAND.setCurrentConfig;
+    payload[4] = 1;
+    payload[5] = profile;
+    const sum = 0x08 + payload.subarray(0, 15).reduce((total, byte) => total + byte, 0);
+    payload[15] = (CHECKSUM_TOTAL - (sum & 0xff)) & 0xff;
+    return payload;
+}
+/** Build SetWirelessDonglePair for one exact mouse model identity. */
+export function atkBuildReceiverPairRequest(cid, mid) {
+    if (![cid, mid].every((value) => Number.isInteger(value) && value >= 0 && value <= 0xff)) {
+        throw new Error("ATK receiver pairing CID and MID must be bytes.");
+    }
+    const payload = new Uint8Array(16);
+    payload[0] = ATK_COMPX_COMMAND.setWirelessDonglePair;
+    payload[4] = 2;
+    payload[5] = cid;
+    payload[6] = mid;
+    const sum = 0x08 + payload.subarray(0, 15).reduce((total, byte) => total + byte, 0);
+    payload[15] = (CHECKSUM_TOTAL - (sum & 0xff)) & 0xff;
+    return payload;
+}
+export const ATK_R1_BUTTONS = [
+    { id: "left", label: "Left button", address: 0x0060 },
+    { id: "right", label: "Right button", address: 0x0064 },
+    { id: "middle", label: "Middle button", address: 0x0068 },
+    { id: "back", label: "Back button", address: 0x006c },
+    { id: "forward", label: "Forward button", address: 0x0070 },
+    { id: "bottom", label: "Bottom button", address: 0x0074 },
+];
+export const ATK_R1_SHORTCUT_BASE = 0x0100;
+export const ATK_R1_SHORTCUT_SLOT_LENGTH = 32;
+export const ATK_R1_MACRO_BASE = 0x0300;
+export const ATK_R1_MACRO_SLOT_LENGTH = 384;
+export const ATK_R1_MACRO_SLOT_COUNT = 12;
+export const ATK_BUTTON_CLASS = {
+    disabled: 0x00,
+    mouse: 0x01,
+    dpi: 0x02,
+    horizontalScroll: 0x03,
+    firepower: 0x04,
+    shortcut: 0x05,
+    macro: 0x06,
+    reportRate: 0x07,
+    lighting: 0x08,
+    profile: 0x09,
+    dpiLock: 0x0a,
+    wheel: 0x0b,
+};
+const BUTTON_CLASS_LABELS = {
+    [ATK_BUTTON_CLASS.disabled]: "Disabled",
+    [ATK_BUTTON_CLASS.mouse]: "Mouse button",
+    [ATK_BUTTON_CLASS.dpi]: "DPI control",
+    [ATK_BUTTON_CLASS.horizontalScroll]: "Horizontal scroll",
+    [ATK_BUTTON_CLASS.firepower]: "Fire key",
+    [ATK_BUTTON_CLASS.shortcut]: "Shortcut",
+    [ATK_BUTTON_CLASS.macro]: "Macro",
+    [ATK_BUTTON_CLASS.reportRate]: "Polling rate",
+    [ATK_BUTTON_CLASS.lighting]: "Lighting control",
+    [ATK_BUTTON_CLASS.profile]: "Profile control",
+    [ATK_BUTTON_CLASS.dpiLock]: "DPI lock",
+    [ATK_BUTTON_CLASS.wheel]: "Wheel",
+};
+const MOUSE_ACTION_LABELS = {
+    0x00: "Disabled",
+    0x01: "Left click",
+    0x02: "Right click",
+    0x04: "Middle click",
+    0x08: "Back",
+    0x10: "Forward",
+};
+const DPI_ACTION_LABELS = {
+    0x01: "DPI cycle",
+    0x02: "DPI up",
+    0x03: "DPI down",
+};
+function hexByte(value) {
+    return value.toString(16).padStart(2, "0");
+}
+/** Describe only action values whose meaning is present in the vendor enum. */
+export function atkDescribeButtonAction(keyClass, value1, value2) {
+    if (keyClass === ATK_BUTTON_CLASS.disabled)
+        return "Disabled";
+    if (keyClass === ATK_BUTTON_CLASS.mouse)
+        return MOUSE_ACTION_LABELS[value1] ?? `Mouse button 0x${hexByte(value1)}`;
+    if (keyClass === ATK_BUTTON_CLASS.dpi)
+        return DPI_ACTION_LABELS[value1] ?? `DPI control 0x${hexByte(value1)}`;
+    if (keyClass === ATK_BUTTON_CLASS.horizontalScroll) {
+        return value1 === 1 ? "Horizontal scroll left" : value1 === 2 ? "Horizontal scroll right" : `Horizontal scroll 0x${hexByte(value1)}`;
+    }
+    if (keyClass === ATK_BUTTON_CLASS.wheel) {
+        return value1 === 1 ? "Wheel up" : value1 === 2 ? "Wheel down" : `Wheel 0x${hexByte(value1)}`;
+    }
+    const kind = BUTTON_CLASS_LABELS[keyClass] ?? `Unknown class 0x${hexByte(keyClass)}`;
+    return `${kind} (0x${hexByte(value1)}, 0x${hexByte(value2)})`;
+}
+export function atkDecodeButtonAssignment(data) {
+    if (data.length < 4)
+        return null;
+    const [keyClass, value1, value2, checksum] = data;
+    const raw = [keyClass, value1, value2, checksum].map(hexByte).join(" ");
+    return {
+        keyClass: keyClass,
+        value1: value1,
+        value2: value2,
+        checksum: checksum,
+        checksumValid: (keyClass + value1 + value2 + checksum) % 0x100 === CHECKSUM_TOTAL,
+        label: atkDescribeButtonAction(keyClass, value1, value2),
+        raw,
+    };
+}
+export function atkDecodeReceiverStatus(data) {
+    if (data.length < 4)
+        return null;
+    return {
+        online: data[0] === 1,
+        status: data[0],
+        rfId: [data[3], data[2], data[1]].map(hexByte).join("").toUpperCase(),
+    };
+}
+export function atkDecodePairingStatus(data) {
+    return data.length < 2 ? null : { status: data[0], secondsRemaining: data[1] };
+}
+// ── COMPX firmware package inspection ──────────────────────────────────────
+export const ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET = 8192;
+export const ATK_COMPX_FIRMWARE_HEADER_LENGTH = 720;
+const ATK_FIRMWARE_FIELD_LENGTH = 64;
+const ATK_FIRMWARE_FIELD_BASE = 23;
+function firmwareField(data, index) {
+    const start = ATK_FIRMWARE_FIELD_BASE + index * ATK_FIRMWARE_FIELD_LENGTH;
+    return data.subarray(start, start + ATK_FIRMWARE_FIELD_LENGTH);
+}
+function asciiField(data, index) {
+    const field = firmwareField(data, index);
+    const end = field.indexOf(0);
+    return new TextDecoder("ascii").decode(end < 0 ? field : field.subarray(0, end));
+}
+function firmwareEndpoint(path) {
+    const match = /(?:^|&)vid_([0-9a-f]+)&pid_([0-9a-f]+)(?:&|$)/i.exec(path);
+    if (!match)
+        throw new Error(`Invalid COMPX firmware endpoint: ${path || "empty"}.`);
+    return { vendorId: Number.parseInt(match[1], 16), productId: Number.parseInt(match[2], 16), path };
+}
+/** CRC-32 register state used by COMPX packages: init 0xffffffff, no final xor. */
+export function atkCompxPayloadCrc(data) {
+    let crc = 0xffffffff;
+    for (const byte of data) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1)
+            crc = (crc >>> 1) ^ ((crc & 1) === 0 ? 0 : 0xedb88320);
+    }
+    return crc >>> 0;
+}
+function commandField(data, index) {
+    return new Uint8Array(firmwareField(data, index));
+}
+/** Parse and integrity-check the first firmware image in a COMPX package. */
+export function atkParseCompxFirmware(data) {
+    if (data.length < ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET)
+        throw new Error("COMPX firmware package is shorter than its header area.");
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const headerLength = view.getUint32(4, true);
+    const firmwareLength = view.getUint32(8, true);
+    if (headerLength !== ATK_COMPX_FIRMWARE_HEADER_LENGTH)
+        throw new Error(`Unsupported COMPX header length ${headerLength}.`);
+    if (firmwareLength < 1 || ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET + firmwareLength > data.length) {
+        throw new Error("COMPX firmware payload length exceeds the package.");
+    }
+    const prepareCommand = commandField(data, 7);
+    const payloadCrc = new DataView(prepareCommand.buffer, prepareCommand.byteOffset, prepareCommand.byteLength).getUint32(19, false);
+    const payload = data.subarray(ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET, ATK_COMPX_FIRMWARE_PAYLOAD_OFFSET + firmwareLength);
+    return {
+        headerCrc: view.getUint32(0, true),
+        headerLength,
+        firmwareLength,
+        nextFileAddress: view.getUint32(12, true),
+        version: view.getUint32(16, true).toString(16),
+        deviceType: view.getUint8(20),
+        cid: view.getUint8(21),
+        mid: view.getUint8(22),
+        fileId: asciiField(data, 0),
+        icName: asciiField(data, 1),
+        bootInput: firmwareEndpoint(asciiField(data, 2)),
+        bootOutput: firmwareEndpoint(asciiField(data, 3)),
+        normalInput: firmwareEndpoint(asciiField(data, 4)),
+        normalOutput: firmwareEndpoint(asciiField(data, 5)),
+        resetCommand: commandField(data, 6),
+        prepareCommand,
+        downloadCommand: commandField(data, 8),
+        sensorName: asciiField(data, 9),
+        productName: asciiField(data, 10),
+        payloadCrc,
+        payloadCrcValid: atkCompxPayloadCrc(payload) === payloadCrc,
+    };
+}
+//# sourceMappingURL=index.js.map