@openmouse/protocol 0.1.0

package/dist/steelseries/aerox5-wireless.d.ts

@@ -0,0 +1,300 @@
+/**
+ * SteelSeries Aerox 5 Wireless configuration protocol — pure encode/decode helpers.
+ *
+ * Reconstructed from public open-source implementations, not vendor software:
+ *
+ * - rivalcfg `rivalcfg/devices/aerox5_wireless_wired.py` — the primary source
+ *   for every command byte, product id, and default here, for the mouse's
+ *   USB-cabled mode (`1038:1854`, plus the Destiny 2 / Diablo IV cosmetic
+ *   editions `0x185E`/`0x1862`).
+ * - rivalcfg `rivalcfg/devices/aerox5_wireless_wireless.py` — the 2.4 GHz
+ *   dongle mode (`1038:1852`, editions `0x185C`/`0x1860`). Read in full: it
+ *   is **not** a separate command set, it is `aerox5_wireless_wired.py`'s
+ *   settings dict comprehended through one `_patch_command` helper that (1)
+ *   ORs `0b01000000` into every command's first byte and (2) adds a 64-byte
+ *   `readback_length`. This module implements that same transform
+ *   (`applyWirelessFlag`) instead of hand-duplicating the wired-mode byte
+ *   tables, so the two PID groups can never drift out of sync the way a
+ *   copy-paste would risk.
+ * - rivalcfg `rivalcfg/devices/dpi/truemove_air.py` — same TrueMove Air
+ *   sensor table as the plain (non-wireless) Aerox 5 — imported from
+ *   `./rival3-wireless.ts`'s `TRUEMOVE_AIR_DPI_TO_BYTE`, not re-derived.
+ * - rivalcfg `rivalcfg/handlers/multidpi_range_choice.py` — `dpi_length_byte: 1`,
+ *   `first_preset: 0` (same as the plain Aerox 5 — **not** 1, unlike Aerox 3
+ *   and Rival 3 Wireless).
+ * - rivalcfg `rivalcfg/handlers/range.py` — `sleep_timer`/`dim_timer`: linear
+ *   range-to-range mapping, 3-byte little-endian output. Traced by hand:
+ *   `sleep_timer`'s `output_range` is `[0x000000, 0x124F80, 60000]` against
+ *   `input_range` `[0, 20, 1]` (minutes) — `0x124F80` is 1,200,000, i.e.
+ *   20 minutes × 60000 ms/min, so the output value is simply
+ *   `minutes * 60000` — and `dim_timer`'s `output_range` is the same
+ *   `[0x000000, 0x124F80, 1000]` against `input_range` `[0, 1200, 1]`
+ *   (seconds), i.e. `seconds * 1000`. Both encode little-endian, 3 bytes
+ *   (`range_length_byte: 3`), per `helpers.uint_to_little_endian_bytearray`.
+ * - rivalcfg `rivalcfg/handlers/rgbcolor.py` / `reactive_rgbcolor.py` — RGB
+ *   value encoding, same as `./aerox3.ts`/`./aerox5.ts`.
+ * - rivalcfg `rivalcfg/handlers/none.py` — `rainbow_effect` here is a
+ *   fixed-argument `[0x22, 0xFF]` command with `value_type: "none"` (just
+ *   enables the effect on all zones; disabled by writing a color instead),
+ *   unlike the plain Aerox 5's zone-bitmask `rainbow_effect`.
+ * - rivalcfg `rivalcfg/handlers/buttons/buttons.py` — 9 buttons + scroll
+ *   up/down, byte-identical layout to `./aerox5.ts`'s `AEROX5_BUTTONS` (same
+ *   ids and offsets, confirmed by direct comparison of the two device
+ *   files) — reused here as `AEROX5_WIRELESS_BUTTONS`, a structurally
+ *   identical constant, rather than re-derived from scratch, since the two
+ *   device files' `buttons_mapping` blocks are identical.
+ *
+ * ## Why wired-cable-mode and 2.4 GHz-dongle-mode share one module
+ *
+ * This is the common SteelSeries wireless pattern also seen in Rival 3
+ * Wireless's sibling `rival3_wireless_gen2.py` (not implemented here, out of
+ * scope): one physical mouse, multiple USB product ids depending on how the
+ * host currently sees it, all driven by the same command set modulo a fixed
+ * per-transport transform. Concretely: `aerox5_wireless_wireless.py`'s
+ * `_patch_command` ORs `0b01000000` (`0x40`) into `command[0]` of every
+ * setting, `battery_level`, and `save_command` inherited from
+ * `aerox5_wireless_wired.py`, and adds `readback_length: 64` (an expected
+ * reply length this module does not need to model — no function here reads
+ * or validates a readback payload; callers that care can check the response
+ * length themselves). Every command byte in `AEROX5_WIRELESS_COMMAND` below
+ * is the wired-mode value; `applyWirelessFlag` produces the 2.4 GHz-mode
+ * byte from it on demand, so there is exactly one place either byte can be
+ * gotten wrong.
+ *
+ * ## Why this is a separate protocol family from the plain Aerox 5
+ *
+ * Despite the shared "Aerox 5" name and several identical command bytes
+ * (`0x2D`/`0x2B`/`0x26`/`0x2A`/`0x27`), `aerox5_wireless_wired.py` is a
+ * genuinely different command layout from `./aerox5.ts`'s plain
+ * `aerox5.py`, confirmed by direct comparison rather than assumed from the
+ * shared name:
+ *
+ * - Polling command `0x2B` shares the byte but **not** the value mapping:
+ *   `{125:0x03, 250:0x02, 500:0x01, 1000:0x00}` here vs. the plain Aerox 5's
+ *   `{125:0x04, 250:0x03, 500:0x02, 1000:0x01}` — writing the plain Aerox 5's
+ *   byte to this device would select the wrong rate.
+ * - RGB zone commands are a different packing entirely:
+ *   `21 01 <zone-index 0/1/2> <r> <g> <b>` here (fixed 6-byte packet, no
+ *   bitmask, no zero-padding growth) vs. the plain Aerox 5's
+ *   `21 <bitmask> <padding> <r> <g> <b>` (`./aerox5.ts`'s
+ *   `steelseriesAerox5EncodeZoneColor`). Do not reuse that function here.
+ * - `rainbow_effect` is a fixed no-argument enable (`22 FF`) here vs. the
+ *   plain Aerox 5's zone-bitmask choice.
+ * - This device has `sleep_timer` (`0x29`) and `dim_timer` (`0x23 0F 01 00 00`)
+ *   settings the plain Aerox 5 profile does not define at all — note
+ *   `dim_timer`'s command also collides on its first byte (`0x23`) with the
+ *   plain Aerox 5's `led_brightness` command; they are unrelated settings on
+ *   unrelated devices, not the same control.
+ * - This device has a `battery_level` read (`0x92`, 2-byte reply) the plain
+ *   Aerox 5 profile has no equivalent of at all (write-only, no getters).
+ *
+ * PIDs are therefore registered under their own family (`"aerox5-wireless"`),
+ * never `"aerox5"`.
+ *
+ * No corroborating libratbag or OpenRGB source for any of these PIDs was
+ * available in this environment (no local libratbag checkout, and OpenRGB's
+ * SteelSeries controller files were not reachable this pass) — every command
+ * byte above is sourced from rivalcfg alone. This should be treated as
+ * unverified beyond rivalcfg until corroborated or hardware-tested.
+ *
+ * Every command is an HID output report, report id `0x00`, on the vendor
+ * configuration interface (`"endpoint": 3` for every model in both rivalcfg
+ * files). DPI presets, polling rate, zone colors, reactive color, sleep/dim
+ * timers, rainbow, default lighting, and buttons are write-only — neither
+ * rivalcfg file defines a getter for any of them. Battery level **is**
+ * readable (see below). Settings apply immediately; the save command
+ * (`11 00`, wireless-mode `51 00`) persists them to onboard flash. None of
+ * this has been verified on physical hardware by this project.
+ *
+ * ## Battery read
+ *
+ * `aerox5_wireless_wired.py` defines a `battery_level` block: an
+ * output-report write of `0x92` gets a 2-byte input-report reply, where
+ * `data[1] & 0b10000000` is the charging flag and
+ * `((data[1] & ~0b10000000) - 1) * 5` is the percentage (a coarse 0–100
+ * scale in steps of 5, `- 1` because the raw byte is 1-indexed). This module
+ * exposes `steelseriesAerox5WirelessBatteryQuery` /
+ * `steelseriesAerox5WirelessDecodeBattery` for both transports (2.4 GHz mode
+ * additionally needs `0x92 | 0x40 = 0xD2`, produced by
+ * `applyWirelessFlag`). This is a **different battery-response shape** from
+ * `./rival3-wireless.ts`'s `AA 01` / 3-byte-reply / plain-percentage-byte
+ * battery read — do not conflate the two devices' battery decoding.
+ */
+export declare const AEROX5_WIRELESS_REPORT_ID = 0;
+/** Wired-cable-mode command bytes; OR `WIRELESS_FLAG` into byte 0 for 2.4 GHz mode. */
+export declare const AEROX5_WIRELESS_COMMAND: {
+    readonly dpiPresets: readonly [45];
+    readonly pollingRate: readonly [43];
+    readonly zoneColor: readonly [33, 1];
+    readonly reactiveColor: readonly [38];
+    readonly sleepTimer: readonly [41];
+    readonly dimTimer: readonly [35, 15, 1, 0, 0];
+    readonly buttonsMapping: readonly [42];
+    readonly rainbowEffect: readonly [34, 255];
+    readonly defaultLighting: readonly [39];
+    readonly batteryLevel: readonly [146];
+};
+/** `11 00` wired-mode / `51 00` 2.4 GHz-mode — see `applyWirelessFlag`. */
+export declare const AEROX5_WIRELESS_SAVE_COMMAND: readonly [17, 0];
+/**
+ * `_patch_command`: OR `0b01000000` into the command's first byte. Pass the
+ * wired-mode command bytes from `AEROX5_WIRELESS_COMMAND` /
+ * `AEROX5_WIRELESS_SAVE_COMMAND`; returns the 2.4 GHz-mode equivalent.
+ */
+export declare function applyWirelessFlag(command: readonly number[]): number[];
+export declare const AEROX5_WIRELESS_POLLING_RATES: readonly [125, 250, 500, 1000];
+export declare const AEROX5_WIRELESS_DPI_MIN = 100;
+export declare const AEROX5_WIRELESS_DPI_MAX = 18000;
+export declare const AEROX5_WIRELESS_DPI_STEP = 100;
+export declare const AEROX5_WIRELESS_MAX_DPI_PRESETS = 5;
+export declare const AEROX5_WIRELESS_BATTERY_RESPONSE_LENGTH = 2;
+export declare class Aerox5WirelessProtocolError extends Error {
+}
+/** The 180 DPI values the shared TrueMove Air sensor table can express, ascending. */
+export declare function steelseriesAerox5WirelessDpiOptions(): number[];
+/**
+ * `2D <count> <selected> <v1>…<vN>` (or `6D …` in 2.4 GHz mode). One byte
+ * per DPI; `selectedIndex` is 0-based and encoded 0-based on the wire
+ * (`first_preset: 0`, same as the plain Aerox 5).
+ */
+export declare function steelseriesAerox5WirelessEncodeDpiPresets(presets: readonly number[], selectedIndex: number, wireless: boolean): Uint8Array;
+/** `2B <v>` (`6B` wireless) with 1000→0x00, 500→0x01, 250→0x02, 125→0x03. */
+export declare function steelseriesAerox5WirelessEncodePollingRate(pollingRateHz: number, wireless: boolean): Uint8Array;
+export type Aerox5WirelessZone = 1 | 2 | 3;
+/**
+ * `21 01 <zone-index> <r> <g> <b>` (`61 01 …` wireless) — a fixed 6-byte
+ * packet, **not** the plain Aerox 5's bitmask-plus-padding shape. Zone 1 =
+ * top LED, zone 2 = middle LED, zone 3 = bottom LED (strip order, per the
+ * source's CLI flag labels).
+ */
+export declare function steelseriesAerox5WirelessEncodeZoneColor(zone: Aerox5WirelessZone, r: number, g: number, b: number, wireless: boolean): Uint8Array;
+/**
+ * `26 00 00 00 00 00` when disabled, `26 01 00 <r> <g> <b>` when enabled
+ * (`66 …` wireless) — same shape as `./aerox3.ts`/`./aerox5.ts`.
+ */
+export declare function steelseriesAerox5WirelessEncodeReactiveColor(color: {
+    r: number;
+    g: number;
+    b: number;
+} | null, wireless: boolean): Uint8Array;
+/**
+ * `29 <ms LE24>` (`69 …` wireless) — idle minutes before sleep, `0` disables.
+ * Encoded as `minutes * 60000` milliseconds, little-endian 3 bytes (see
+ * module doc comment for the range-handler derivation).
+ */
+export declare function steelseriesAerox5WirelessEncodeSleepTimer(minutes: number, wireless: boolean): Uint8Array;
+/**
+ * `23 0F 01 00 00 <ms LE24>` (`63 …` wireless) — idle seconds before the LEDs
+ * dim, `0` disables. Encoded as `seconds * 1000` milliseconds, little-endian
+ * 3 bytes.
+ */
+export declare function steelseriesAerox5WirelessEncodeDimTimer(seconds: number, wireless: boolean): Uint8Array;
+/** `22 FF` (`62 FF` wireless) — enables the rainbow effect on all zones; a color write clears it. */
+export declare function steelseriesAerox5WirelessEncodeRainbowEffect(wireless: boolean): Uint8Array;
+/** Byte-identical to the plain Aerox 5's `AEROX5_DEFAULT_LIGHTING` table. */
+export declare const AEROX5_WIRELESS_DEFAULT_LIGHTING: {
+    readonly off: readonly [0, 0];
+    readonly reactive: readonly [0, 1];
+    readonly rainbow: readonly [1, 0];
+    readonly "reactive-rainbow": readonly [1, 1];
+};
+export type Aerox5WirelessDefaultLighting = keyof typeof AEROX5_WIRELESS_DEFAULT_LIGHTING;
+/** `27 <v1> <v2>` (`67 …` wireless) — what the mouse lights up as before a host ever connects. */
+export declare function steelseriesAerox5WirelessEncodeDefaultLighting(mode: Aerox5WirelessDefaultLighting, wireless: boolean): Uint8Array;
+/** `11 00` wired-mode / `51 00` 2.4 GHz-mode — commit the current settings to onboard flash. */
+export declare function steelseriesAerox5WirelessSaveCommand(wireless: boolean): Uint8Array;
+/** `92` wired-mode / `D2` 2.4 GHz-mode — the device answers with a two-byte input report. */
+export declare function steelseriesAerox5WirelessBatteryQuery(wireless: boolean): Uint8Array;
+export interface Aerox5WirelessBattery {
+    /** `((data[1] & ~0x80) - 1) * 5` in rivalcfg — a coarse 0–100 scale in steps of 5. */
+    level: number;
+    /** `bool(data[1] & 0b10000000)` in rivalcfg. */
+    isCharging: boolean;
+}
+/**
+ * Decode the two-byte battery response: `data[0]` is unused by rivalcfg's
+ * lambdas, `data[1]`'s top bit is the charging flag and the remaining 7 bits
+ * (1-indexed, hence `- 1`) scaled by 5 give the percentage.
+ */
+export declare function steelseriesAerox5WirelessDecodeBattery(payload: Uint8Array): Aerox5WirelessBattery;
+/**
+ * `buttons_mapping.buttons` from `aerox5_wireless_wired.py` — byte-identical
+ * ids/offsets to `./aerox5.ts`'s `AEROX5_BUTTONS`, confirmed by direct
+ * comparison of the two device files, defined separately here rather than
+ * imported so each family's button table stays self-contained.
+ */
+export declare const AEROX5_WIRELESS_BUTTONS: {
+    readonly button1: {
+        readonly id: 1;
+        readonly offset: 0;
+    };
+    readonly button2: {
+        readonly id: 2;
+        readonly offset: 5;
+    };
+    readonly button3: {
+        readonly id: 3;
+        readonly offset: 10;
+    };
+    readonly button4: {
+        readonly id: 4;
+        readonly offset: 15;
+    };
+    readonly button5: {
+        readonly id: 5;
+        readonly offset: 20;
+    };
+    readonly button6: {
+        readonly id: 6;
+        readonly offset: 25;
+    };
+    readonly button7: {
+        readonly id: 7;
+        readonly offset: 30;
+    };
+    readonly button8: {
+        readonly id: 8;
+        readonly offset: 35;
+    };
+    readonly button9: {
+        readonly id: 9;
+        readonly offset: 40;
+    };
+    readonly scrollUp: {
+        readonly id: 49;
+        readonly offset: 45;
+    };
+    readonly scrollDown: {
+        readonly id: 50;
+        readonly offset: 50;
+    };
+};
+export type Aerox5WirelessButtonName = keyof typeof AEROX5_WIRELESS_BUTTONS;
+/**
+ * One button's target. `scrollUp`/`scrollDown` cannot be remap *targets*
+ * (`button_scroll_up`/`button_scroll_down` are `None` in the source) — only
+ * sources, same rule as the plain Aerox 5.
+ */
+export type Aerox5WirelessButtonAction = {
+    type: "button";
+    target: Exclude<Aerox5WirelessButtonName, "scrollUp" | "scrollDown">;
+} | {
+    type: "disabled";
+} | {
+    type: "dpiSwitch";
+} | {
+    type: "keyboard";
+    code: number;
+} | {
+    type: "multimedia";
+    code: number;
+};
+/**
+ * `2A` (`6A` wireless) + one 55-byte (`11 buttons × 5-byte field length`)
+ * packet, zero-filled except where a mapping is given. Unmapped buttons are
+ * left as all-zero fields (rivalcfg instead fills in per-button defaults;
+ * this codec leaves that policy to the caller — pass every button
+ * explicitly for parity with rivalcfg's default profile).
+ */
+export declare function steelseriesAerox5WirelessEncodeButtonsMapping(mapping: Partial<Record<Aerox5WirelessButtonName, Aerox5WirelessButtonAction>>, wireless: boolean): Uint8Array;
+//# sourceMappingURL=aerox5-wireless.d.ts.map

package/dist/steelseries/aerox5-wireless.d.ts.map

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