@openmouse/protocol 0.1.0

package/dist/steelseries/sensei-ten.d.ts

@@ -0,0 +1,283 @@
+/**
+ * SteelSeries Sensei TEN configuration protocol — pure encode/decode helpers.
+ *
+ * Reconstructed from public open-source implementations, not vendor software:
+ *
+ * - rivalcfg `rivalcfg/devices/sensei_ten.py` — the primary source for every
+ *   command byte, default, and product id here.
+ * - rivalcfg `rivalcfg/test/devices/old_specs/test_sensei_ten.py` — the
+ *   device-specific fixture test, which pins exact expected HID report bytes
+ *   for polling rate, sensitivity presets, logo/wheel color gradients,
+ *   buttons mapping, save, and the firmware query. Every byte sequence in
+ *   this module's own tests was cross-checked against that file rather than
+ *   re-derived solely from the handler source, since it is ground truth for
+ *   how rivalcfg actually serializes this device's settings.
+ * - rivalcfg `rivalcfg/handlers/range.py` (the `range` value type the
+ *   `multidpi_range` handler below builds on: linear input→output mapping,
+ *   rounded to the nearest step) and `rivalcfg/handlers/rgbgradient.py` (the
+ *   color/gradient wire format for `logo_color` and `wheel_color`).
+ * - `rivalcfg/devices/sensei_raw.py` and `rivalcfg/devices/sensei310.py` were
+ *   read to confirm they are unrelated protocols (different command bytes,
+ *   different DPI encodings) and were not a source for anything here.
+ *
+ * **Corroboration gap, flagged prominently per this rollout's instructions:**
+ * libratbag and the OpenRGB SteelSeries controller sources were not
+ * reachable from this environment (no network access to
+ * github.com/libratbag/libratbag or OpenRGB's SteelSeries controller files),
+ * so unlike some earlier SteelSeries clusters in this project, **nothing
+ * here has a second independent source** — rivalcfg (source + its own test
+ * fixture) is the only corroboration this module has. Treat every byte below
+ * as "rivalcfg says so", not "two independent projects agree".
+ *
+ * Every command is an HID **output report** (id `0x00`) except `logo_color`
+ * and `wheel_color`, which are HID **feature reports** — `sensei_ten.py`
+ * marks them `usbhid.HID_REPORT_TYPE_FEATURE` while every other setting is
+ * `HID_REPORT_TYPE_OUTPUT`. The functions here build the report *payload* —
+ * the bytes after the report id — unpadded, matching rivalcfg's `usbhid.py`
+ * writes (`_hid_write` always prepends `report_id = 0x00` and otherwise
+ * sends the payload as-is with no fixed packet length for this device).
+ *
+ * **This device is write-only except for firmware.** No public
+ * implementation has a getter for DPI, polling, or lighting/buttons; the
+ * single readable value is the two-byte firmware version behind `90 00`
+ * (`response_length: 2`, `report_type: OUTPUT`), the same shape as Rival 3
+ * Gen 1's `10 00` — see `steelseriesSenseiTenDecodeFirmware`, which reuses
+ * Rival 3's read-order-byte-join convention and the same byte-order caveat.
+ *
+ * Settings apply immediately; `save_command` (`59 00`) persists them to
+ * onboard flash — distinct from Rival 3 Gen 1's `09 00` and Aerox 3's
+ * `11 00`; do not reuse across families.
+ *
+ * ## Sensor / DPI encoding
+ *
+ * Unlike Rival 3 Gen 1 and Aerox 3 (TrueMove Core, a byte lookup table),
+ * Sensei TEN's `sensitivity` setting uses rivalcfg's plain `multidpi_range`
+ * handler with `input_range: [50, 18000, 50]` and `output_range: [1, 0x0168,
+ * 1]` — a **linear** mapping, not a table: `output = input / 50`, written as
+ * a 2-byte little-endian integer per preset (`dpi_length_byte: 2`). This
+ * matches SteelSeries marketing calling Sensei TEN's sensor a newer
+ * generation (TrueMove3+) than the TrueMove Core/Air families used by
+ * Rival 3 and Aerox 3/5 — confirmed here by the *shape* of the DPI handler
+ * (linear range vs. lookup table) rather than by an independent sensor-name
+ * source, which was not reachable (see corroboration gap above).
+ *
+ * `count_mode: "flag"` — like Aerox 3's `dpiPresets`, the on-wire preset
+ * count is a bitmask (`0b00000001` for 1 preset, `0b00001111` for 4, etc.),
+ * not a plain integer, unlike Rival 3 Gen 1's `count_mode: "number"`.
+ *
+ * ## RGB: `logo_color` / `wheel_color`
+ *
+ * Sensei TEN has two independently addressable RGB zones — the SteelSeries
+ * logo and the scroll-wheel light — both using rivalcfg's full `rgbgradient`
+ * value type (multi-stop animated gradients), not the simpler flat
+ * `rgbcolor`/zone-bitmask scheme Aerox 3 and Aerox 5 use. This module
+ * implements the complete gradient encoding (not just a solid-color special
+ * case), because the wire format is small and precisely pinned by
+ * `test_sensei_ten.py`'s `test_set_logo_color`/`test_set_wheel_color`
+ * fixtures, which this module's tests reproduce byte-for-byte.
+ *
+ * The packet layout, from `rgbgradient.py`'s `process_value` with Sensei
+ * TEN's `rgbgradient_header` (`header_length: 26`, `led_id_offsets: [0]`,
+ * `duration_offset: 1` (2 bytes, little-endian ms), `repeat_offset: 17`,
+ * `triggers_offset: 21`, `color_count_offset: 25`):
+ *
+ * ```
+ * 5B 00 <led_id> <duration_lo> <duration_hi> <14 zero bytes>
+ *       <repeat> <3 zero bytes> <triggers> <3 zero bytes> <color_count>
+ *       <initial_color r,g,b> <color1 r,g,b> <pos1> ... <colorN r,g,b> <posN>
+ * ```
+ *
+ * `led_id` is `0x00` for `logo_color`, `0x01` for `wheel_color` — the only
+ * difference between the two settings' commands. `repeat` is `0x01` for a
+ * solid color (no animation) or when the gradient has button triggers
+ * (`triggers` — not exposed by this module, always `0x00`, matching
+ * `sensei_ten.py`'s profile, which never sets it); `0x00` for an animated
+ * gradient with no trigger.
+ *
+ * **The per-stop `pos` byte is a *delta*, not an absolute position** — easy
+ * to get wrong reading `rgbgradient.py` casually, and this module's first
+ * draft did. Each stop's true 0–255 position is `Math.trunc(pos * 255 /
+ * 100)` (rivalcfg uses Python's `int()`, which truncates toward zero, not
+ * `round()`); the wire byte for that stop is the *difference* between this
+ * truncated position and the previous stop's, starting from 0. This was
+ * confirmed against `test_sensei_ten.py`'s `test_set_wheel_color` fixture:
+ * stops at 0/25/50/75/100% truncate to real positions 0/63/127/191/255, and
+ * the fixture's actual bytes are the deltas 0/63/64/64/64, not the absolute
+ * values — reproduced exactly by this module's own tests. rivalcfg
+ * auto-appends a final stop equal to the first color at pos 100 if the
+ * caller's last stop is not already at 100, "smoothing" the loop — this
+ * module requires the caller to pass every stop explicitly (including the
+ * closing one, if wanted) rather than silently appending one, to keep the
+ * encoder a pure function of its input.
+ *
+ * ## Buttons mapping — reduced scope, mirrors `aerox3.ts`
+ *
+ * `31 00` + one 40-byte (8 buttons × 5-byte field) packet, zero-filled
+ * except where a mapping is given — byte-identical field layout to Aerox 3's
+ * `buttons_mapping`, but Sensei TEN's `button_scroll_up`/`button_scroll_down`
+ * (`0x31`/`0x32`) are function **codes** a button's slot can hold (used when
+ * *another* button is remapped to act as a scroll action), unlike Aerox 3
+ * where `scrollUp`/`scrollDown` are physical button *sources* that cannot be
+ * remap targets. Sensei TEN has no such restriction — every one of its 8
+ * buttons is a valid remap target for another button's id (Button1–Button8,
+ * ids `0x01`–`0x08`). As with `aerox3.ts`, this module implements the exact
+ * packet shape and the mouse-button/disable/DPI-switch/scroll-up/scroll-down
+ * special actions, but does not re-implement rivalcfg's QWERTY/multimedia
+ * key-name tables — keyboard and multimedia targets are raw
+ * `{ type: "keyboard" | "multimedia", code }` scan-code bytes, matching
+ * `button_keyboard: 0x51` / `button_multimedia: 0x61` verbatim. The
+ * documented defaults (`test_set_buttons_mapping`'s `"default"` case) are
+ * exposed as `SENSEI_TEN_DEFAULT_BUTTONS_MAPPING` for callers/tests: Button6
+ * defaults to keyboard code `0x4E` (Page Down), Button7 to `0x4B` (Page Up),
+ * Button8 to DPI-switch — the rest map to themselves.
+ *
+ * None of this has been verified on physical Sensei TEN hardware by this
+ * project. The Sensei RAW (`sensei_raw.py`) and Sensei 310 (`sensei310.py`)
+ * use different, incompatible command sets and must not reuse this module.
+ */
+export declare const SENSEI_TEN_REPORT_ID = 0;
+/** Two-byte command prefixes; the payload is the prefix plus its arguments. */
+export declare const SENSEI_TEN_COMMAND: {
+    readonly buttonsMapping: readonly [49, 0];
+    readonly pollingRate: readonly [84, 0];
+    readonly sensitivity: readonly [85, 0];
+    readonly logoColor: readonly [91, 0];
+    readonly wheelColor: readonly [91, 0];
+    readonly save: readonly [89, 0];
+    readonly firmware: readonly [144, 0];
+};
+export declare const SENSEI_TEN_POLLING_RATES: readonly [125, 250, 500, 1000];
+export declare const SENSEI_TEN_DPI_MIN = 50;
+export declare const SENSEI_TEN_DPI_MAX = 18000;
+export declare const SENSEI_TEN_DPI_STEP = 50;
+export declare const SENSEI_TEN_MAX_DPI_PRESETS = 5;
+export declare const SENSEI_TEN_FIRMWARE_RESPONSE_LENGTH = 2;
+export declare class SenseiTenProtocolError extends Error {
+}
+/** Every DPI value the linear 50–18,000 (step 50) range can express, ascending. */
+export declare function steelseriesSenseiTenDpiOptions(): number[];
+/**
+ * `55 00 <count flag> <selected> <v1 lo,hi> ... <vN lo,hi>` — replaces the
+ * mouse's whole preset table. Each DPI is 2 bytes little-endian
+ * (`dpi_length_byte: 2`); `count` is a bitmask of the preset count
+ * (`count_mode: "flag"`), not a plain integer. `selectedIndex` is 0-based
+ * here and encoded 1-based on the wire (`first_preset: 1`).
+ */
+export declare function steelseriesSenseiTenEncodeDpiPresets(presets: readonly number[], selectedIndex: number): Uint8Array;
+/** `54 00 <v>` with 1000→0x01, 500→0x02, 250→0x03, 125→0x04. */
+export declare function steelseriesSenseiTenEncodePollingRate(pollingRateHz: number): Uint8Array;
+export type SenseiTenLed = "logo" | "wheel";
+/** One gradient stop: `pos` is a percentage 0–100. */
+export interface SenseiTenColorStop {
+    pos: number;
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * `5B 00 <led_id> ...` — encodes a color or animated gradient for the logo
+ * (`led: "logo"`) or scroll-wheel (`led: "wheel"`) LED. See the module doc
+ * comment for the full packet layout.
+ *
+ * - A single stop (`stops.length === 1`) is treated as a solid, non-animated
+ *   color: `repeat` is set to `0x01` regardless of that stop's `pos`
+ *   (matching `rgbgradient.py`'s `is_gradient = False` path for a bare color
+ *   string/tuple, which always uses `pos = 0` internally — pass `pos: 0`
+ *   here for parity, though the wire format ignores it for a single stop
+ *   since there is nothing to interpolate toward).
+ * - Two or more stops are encoded as an animated gradient at `durationMs`,
+ *   `repeat` `0x00`. Unlike rivalcfg's CLI parser, this function does **not**
+ *   auto-append a closing stop equal to the first color at pos 100 — pass it
+ *   explicitly if a smooth loop is wanted (see `test_set_logo_color`'s
+ *   fixture, which does include that stop as its 4th entry).
+ */
+export declare function steelseriesSenseiTenEncodeLedColor(led: SenseiTenLed, stops: readonly SenseiTenColorStop[], durationMs?: number): Uint8Array;
+/** `59 00` — commit the current settings to onboard flash. */
+export declare function steelseriesSenseiTenSaveCommand(): Uint8Array;
+/** `90 00` — the two-byte firmware version query, this device's only readable value. */
+export declare function steelseriesSenseiTenFirmwareQuery(): Uint8Array;
+export interface SenseiTenFirmware {
+    /** The two raw response bytes, in the order the device sent them. */
+    bytes: [number, number];
+    /** The bytes joined in read order, e.g. "37.0". */
+    display: string;
+}
+/**
+ * Decode the two-byte firmware response, reusing Rival 3 Gen 1's read-order
+ * join convention (`steelseriesRival3DecodeFirmware`) — the byte order is
+ * contested between public implementations for that family, and no
+ * corroborating source (libratbag, OpenRGB) was reachable for Sensei TEN
+ * specifically to settle it independently. Both raw bytes are returned.
+ */
+export declare function steelseriesSenseiTenDecodeFirmware(payload: Uint8Array): SenseiTenFirmware;
+/** `buttons_mapping.buttons` from `sensei_ten.py`, id + byte offset into the packet. */
+export declare const SENSEI_TEN_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;
+    };
+};
+export type SenseiTenButtonName = keyof typeof SENSEI_TEN_BUTTONS;
+/** One button's target — see the module doc comment for why scroll actions
+ * are function codes here, unlike Aerox 3's fixed scroll-source buttons. */
+export type SenseiTenButtonAction = {
+    type: "button";
+    target: SenseiTenButtonName;
+} | {
+    type: "disabled";
+} | {
+    type: "dpiSwitch";
+} | {
+    type: "scrollUp";
+} | {
+    type: "scrollDown";
+} | {
+    type: "keyboard";
+    code: number;
+} | {
+    type: "multimedia";
+    code: number;
+};
+/**
+ * `31 00` + one 40-byte (`8 buttons × 5-byte field length`) packet,
+ * zero-filled except where a mapping is given. Unmapped buttons are left as
+ * all-zero fields — pass every button explicitly for parity with rivalcfg's
+ * default profile (see `SENSEI_TEN_DEFAULT_BUTTONS_MAPPING`).
+ */
+export declare function steelseriesSenseiTenEncodeButtonsMapping(mapping: Partial<Record<SenseiTenButtonName, SenseiTenButtonAction>>): Uint8Array;
+/**
+ * `sensei_ten.py`'s documented default mapping (`test_set_buttons_mapping`'s
+ * `"default"` fixture): buttons 1–5 map to themselves, Button6 to keyboard
+ * Page Down (`0x4E`), Button7 to keyboard Page Up (`0x4B`), Button8 to the
+ * DPI switch.
+ */
+export declare const SENSEI_TEN_DEFAULT_BUTTONS_MAPPING: Record<SenseiTenButtonName, SenseiTenButtonAction>;
+//# sourceMappingURL=sensei-ten.d.ts.map

package/dist/steelseries/sensei-ten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensei-ten.d.ts","sourceRoot":"","sources":["../../src/steelseries/sensei-ten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwIG;AAEH,eAAO,MAAM,oBAAoB,IAAO,CAAC;AAEzC,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB;;;;;;;;CAQrB,CAAC;AAEX,eAAO,MAAM,wBAAwB,gCAAiC,CAAC;AASvE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAErD,qBAAa,sBAAuB,SAAQ,KAAK;CAAG;AAEpD,mFAAmF;AACnF,wBAAgB,8BAA8B,IAAI,MAAM,EAAE,CAMzD;AAgBD;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,aAAa,EAAE,MAAM,GACpB,UAAU,CAkBZ;AAED,gEAAgE;AAChE,wBAAgB,qCAAqC,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAMvF;AAID,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAI5C,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,UAAU,SAAO,GAChB,UAAU,CAqCZ;AAED,8DAA8D;AAC9D,wBAAgB,+BAA+B,IAAI,UAAU,CAE5D;AAED,wFAAwF;AACxF,wBAAgB,iCAAiC,IAAI,UAAU,CAE9D;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAMzF;AASD,wFAAwF;AACxF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CASyB,CAAC;AAEzD,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAUlE;4EAC4E;AAC5E,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,wCAAwC,CACtD,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC,GACnE,UAAU,CAsDZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,EAAE,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CASjG,CAAC"}