From 708c916f9c10d55a316b86711da502599d362423 Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:26:32 +0700 Subject: [PATCH 1/6] feat(instant): add A825 protocol and read-only driver - Added @openmouse/protocol/instant: report-7 framing, 16-bit block read/write, status decode, and the vendor's 23-value DPI table. - Added a read-only A825 WebHID client exposing firmware/build and the stored configuration image. - Documented the hardware-verified transport, the 80-entry configuration record table, and the DevDock HID function map. - Registered VID 0x30FA / PIDs 0x1440, 0x1E01, 0x7F7F on usage page 0xFF01. --- docs/a825-config-records.md | 88 +++++++ docs/devdock-functions.md | 98 ++++++++ docs/instant-a825.md | 206 ++++++++++++++++ package.json | 4 + src/drivers/instant/a825-hid.test.ts | 117 +++++++++ src/drivers/instant/a825-hid.ts | 248 ++++++++++++++++++++ src/drivers/mouse-types.ts | 2 +- src/drivers/registry.ts | 6 +- src/drivers/vendors.ts | 13 + src/instant/index.ts | 1 + src/instant/protocol.test.ts | 117 +++++++++ src/instant/protocol.ts | 339 +++++++++++++++++++++++++++ 12 files changed, 1237 insertions(+), 2 deletions(-) create mode 100644 docs/a825-config-records.md create mode 100644 docs/devdock-functions.md create mode 100644 docs/instant-a825.md create mode 100644 src/drivers/instant/a825-hid.test.ts create mode 100644 src/drivers/instant/a825-hid.ts create mode 100644 src/instant/index.ts create mode 100644 src/instant/protocol.test.ts create mode 100644 src/instant/protocol.ts diff --git a/docs/a825-config-records.md b/docs/a825-config-records.md new file mode 100644 index 0000000..b521389 --- /dev/null +++ b/docs/a825-config-records.md @@ -0,0 +1,88 @@ +# A825 configuration records + +Generated from Ghidra's decompilation of `A825_BuildConfigImage` (0x481400) +in `DevDock.exe` (SHA-256 `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`). +The map key is the byte offset in the configuration image. + +| Offset | Value | +| --- | --- | +| `0x000` | `0x5a` | +| `0x001` | `(-(cVar20 != '\0') & 3U) + (*(byte *)((int)this + 0x74c) & 3) * ' '` | +| `0x002` | `0xa5` | +| `0x003` | `(byte)*(undefined4 *)((int)this + 0x8068)` | +| `0x004` | `(byte)(*(int *)((int)this + 0x8068) + (*(int *)((int)this + 0x8068) >> 0x1f & 0xffU) >> 8)` | +| `0x005` | `(byte)*(undefined4 *)((int)this + 0x8064)` | +| `0x006` | `(byte)(*(int *)((int)this + 0x8064) + (*(int *)((int)this + 0x8064) >> 0x1f & 0xffU) >> 8)` | +| `0x007` | `*(byte *)((int)this + 0x802c)` | +| `0x008` | `*(byte *)((int)this + 0x802d)` | +| `0x009` | `*(byte *)((int)this + 0x802e)` | +| `0x00A` | `*(byte *)((int)this + 0x802f)` | +| `0x00B` | `*(byte *)((int)this + 0x8030)` | +| `0x00C` | `*(byte *)((int)this + 0x8031)` | +| `0x00D` | `*(byte *)((int)this + 0x8032)` | +| `0x00E` | `*(byte *)((int)this + 0x8033)` | +| `0x00F` | `*(byte *)((int)this + 0x8034)` | +| `0x010` | `0` | +| `0x012` | `0` | +| `0x013` | `(((((*(byte *)((int)this + 0x7a7) >> 4 & 1) * '\x02' + (*(byte *)((int)this + 0x7a6) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a5) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a4) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a3) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a2) >> 4 & 1)` | +| `0x014` | `(((*(byte *)((int)this + 0x8104) & 3) * '\x02' + (*(byte *)((int)this + 0x8298) & 1)) * '\x02' + (*(byte *)((int)this + 0x829d) & 1)) * '\x02' + (*(byte *)((int)this + 0x829c) & 1) ` | +| `0x015` | `*(char *)((int)this + 0x7a4) * '\x10' + (*(byte *)((int)this + 0x7a5) & 0xf)` | +| `0x016` | `*(char *)((int)this + 0x7a6) * '\x10' + (*(byte *)((int)this + 0x7a7) & 0xf)` | +| `0x017` | `*(byte *)((int)this + 0x750) & 7` | +| `0x018` | `*(byte *)((int)this + 0x82a0) & 0x3f` | +| `0x019` | `(byte)iVar25` | +| `0x01B` | `(byte)(iVar25 + (iVar25 >> 0x1f & 0xffU) >> 8)` | +| `0x01C` | `((*(char *)((int)this + 0x82a6) * '\b' + (*(byte *)((int)this + 0x829e) & 7)) * '\x02' + *(char *)((int)this + 0x82a5)) * '\b' + (local_2cd & 7)` | +| `0x01D` | `*(byte *)((int)this + 0x7a8)` | +| `0x01E` | `0` | +| `0x020` | `(byte)*(undefined4 *)((int)this + 0x758) & 0xf` | +| `0x021` | `(byte)*(undefined4 *)((int)this + 0x75c) & 0xf` | +| `0x022` | `(byte)*(undefined4 *)((int)this + 0x760) & 0xf` | +| `0x023` | `(byte)*(undefined4 *)((int)this + 0x764) & 0xf` | +| `0x024` | `(byte)*(undefined4 *)((int)this + 0x768) & 0xf` | +| `0x025` | `(byte)*(undefined4 *)((int)this + 0x76c) & 0xf` | +| `0x026` | `(byte)*(undefined4 *)((int)this + 0x770) & 0xf` | +| `0x027` | `(byte)*(undefined4 *)((int)this + 0x774) & 0xf` | +| `0x028` | `(byte)*(undefined4 *)((int)this + 0x778) & 0xf` | +| `0x029` | `(byte)*(undefined4 *)((int)this + 0x77c) & 0xf` | +| `0x02A` | `(byte)*(undefined4 *)((int)this + 0x780) & 0xf` | +| `0x02B` | `(byte)*(undefined4 *)((int)this + 0x784) & 0xf` | +| `0x02C` | `(byte)*(undefined4 *)((int)this + 0x788) & 0xf` | +| `0x02D` | `(byte)*(undefined4 *)((int)this + 0x78c) & 0xf` | +| `0x02E` | `(byte)*(undefined4 *)((int)this + 0x790) & 0xf` | +| `0x02F` | `(byte)*(undefined4 *)((int)this + 0x794) & 0xf` | +| `0x030` | `(byte)*(undefined4 *)((int)this + 0x798) & 0xf` | +| `0x031` | `0` | +| `0x032` | `0` | +| `0x033` | `0` | +| `0x035` | `0` | +| `0x036` | `0` | +| `0x037` | `0` | +| `0x038` | `0` | +| `0x039` | `0` | +| `0x03A` | `*(byte *)((int)this + 0x8035)` | +| `0x03B` | `*(byte *)((int)this + 0x8036)` | +| `0x03C` | `*(byte *)((int)this + 0x8037)` | +| `0x03D` | `0` | +| `0x03E` | `0` | +| `0x03F` | `((*(char *)((int)this + 0x810c) * '\x04' + *(char *)((int)this + 0x8114)) * '\x04' + *(char *)((int)this + 0x8115)) * '\b' + *(char *)((int)this + 0x82ec)` | +| `0x040` | `(*(char *)((int)this + 0x82b4) * '\x02' + *(char *)((int)this + 0x82bc)) * ' ' + *(char *)((int)this + 0x82c4)` | +| `0x042` | `(*(char *)((int)this + 0x82b8) * '\x02' + *(char *)((int)this + 0x82c0)) * ' ' + *(char *)((int)this + 0x82c8)` | +| `0x043` | `(((*(char *)((int)this + 0x80fc) * '\x02' + *(char *)((int)this + 0x82f0)) * '\x02' + *(char *)((int)this + 0x82f4)) * '\x02' + *(char *)((int)this + 0x80f4)) * '\x10' + cVar20` | +| `0x044` | `(*(char *)((int)this + 0x908) * '\x02' + *(char *)((int)this + 0x86c)) * ' ' + *(char *)((int)this + 0x803a)` | +| `0x045` | `(*(char *)((int)this + 0x909) * '\x02' + *(char *)((int)this + 0x870)) * ' ' + *(char *)((int)this + 0x803b)` | +| `0x046` | `(*(char *)((int)this + 0x90a) * '\x02' + *(char *)((int)this + 0x874)) * ' ' + *(char *)((int)this + 0x803c)` | +| `0x047` | `(*(char *)((int)this + 0x90b) * '\x02' + *(char *)((int)this + 0x878)) * ' ' + *(char *)((int)this + 0x803d)` | +| `0x048` | `((char)*(undefined4 *)((int)this + 0x87c) + *(char *)((int)this + 0x90c) * '\x02') * ' ' + *(char *)((int)this + 0x803e)` | +| `0x049` | `((char)*(undefined4 *)((int)this + 0x880) + *(char *)((int)this + 0x90d) * '\x02') * ' ' + *(char *)((int)this + 0x803f)` | +| `0x04A` | `((char)*(undefined4 *)((int)this + 0x884) + *(char *)((int)this + 0x90e) * '\x02') * ' ' + *(char *)((int)this + 0x8040)` | +| `0x04B` | `((char)*(undefined4 *)((int)this + 0x88c) + *(char *)((int)this + 0x910) * '\x02') * ' ' + *(char *)((int)this + 0x8042)` | +| `0x04D` | `((char)*(undefined4 *)((int)this + 0x890) + *(char *)((int)this + 0x911) * '\x02') * ' ' + *(char *)((int)this + 0x8043)` | +| `0x04E` | `((char)*(undefined4 *)((int)this + 0x894) + *(char *)((int)this + 0x912) * '\x02') * ' ' + *(char *)((int)this + 0x8044)` | +| `0x04F` | `((char)*(undefined4 *)((int)this + 0x89c) + *(char *)((int)this + 0x914) * '\x02') * ' ' + *(char *)((int)this + 0x8048)` | +| `0x051` | `((char)*(undefined4 *)((int)this + 0x8a0) + *(char *)((int)this + 0x915) * '\x02') * ' ' + *(char *)((int)this + 0x8049)` | +| `0x052` | `((char)*(undefined4 *)((int)this + 0x8a4) + *(char *)((int)this + 0x916) * '\x02') * ' ' + *(char *)((int)this + 0x804a)` | +| `0x053` | `((char)*(undefined4 *)((int)this + 0x8ac) + *(char *)((int)this + 0x918) * '\x02') * ' ' + *(char *)((int)this + 0x804c)` | +| `0x055` | `((char)*(undefined4 *)((int)this + 0x8b0) + *(char *)((int)this + 0x919) * '\x02') * ' ' + *(char *)((int)this + 0x804d)` | +| `0x056` | `((char)*(undefined4 *)((int)this + 0x8b4) + *(char *)((int)this + 0x91a) * '\x02') * ' ' + *(char *)((int)this + 0x804e)` | +| `0x057` | `((char)*(undefined4 *)((int)this + 0x8bc) + *(char *)((int)this + 0x91c) * '\x02') * ' ' + *(char *)((int)this + 0x8050)` | diff --git a/docs/devdock-functions.md b/docs/devdock-functions.md new file mode 100644 index 0000000..752a4d5 --- /dev/null +++ b/docs/devdock-functions.md @@ -0,0 +1,98 @@ +# DevDock function map (Sades Kaze A825) + +Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from +`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. + +The analysis database used the names below; the addresses are the evidence. + +| Address | Name | Role | +| --- | --- | --- | +| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | +| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | +| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | +| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | +| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` packs `byte[0x8104] & 3` above three flags; writing it did not change the measured report cadence. | +| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | +| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | +| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | +| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | +| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | +| `0x486FA0` | apply state collector | Collect UI state into the device object. | +| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | +| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | +| `0x460A60` | `MacroSenderThread` | Macro playback thread. | +| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | +| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | +| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | + +## Block write + +`A825_BlockWrite(this, handle, address, data, length)`: + +``` +07 18 03 +``` + +one frame per byte, then: + +``` +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Addresses are little-endian. The wait between the finish and commit frames is +12 ms. + +## Read + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → feature report byte 1 +07 18 00 00 00 00 +``` + +## Block mode + +`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then +`07 18 00 00 00 00 00 00`. + +## DPI frames + +`A825_LiveDpiAndButtons`: + +``` +07 12 mode 0 +07 12 other modes +07 11 +07 09 × 4 +``` + +The four `09` frames use: + +``` +byte2 = ((map >> 4) << 6) + profile +byte3 = (map << 4) + 8 + index +byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 +``` + +where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the +flags are `byte[0x79C..0x79F]`. + +## Configuration image + +`A825_BuildConfigImage` collects records with numeric ids: + +| Id | Value | +| --- | --- | +| 0 | `0x5A` | +| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | +| 2 | `0xA5` | +| 3 | `byte[0x8068]` | +| 4 | `byte[0x8068] >> 8` | +| 5 | `byte[0x8064]` | +| 6 | `byte[0x8064] >> 8` | +| 7 | `byte[0x802C]` (key map byte 0) | +| 8+ | lighting and stage fields | + +The record-to-image-address mapping is not resolved. diff --git a/docs/instant-a825.md b/docs/instant-a825.md new file mode 100644 index 0000000..e503496 --- /dev/null +++ b/docs/instant-a825.md @@ -0,0 +1,206 @@ +# Instant A825 / Sades Kaze protocol + +This document describes what is known about the Instant A825 control protocol +as used by the Sades Kaze. It separates behaviour observed on the device from +behaviour read out of the vendor binary. + +## Device + +- Vendor: Wuxi Instant Microelectronics (A825 chipset). +- Sades model: Kaze, `Sades Kaze (Instant A825)`. +- USB: VID `0x30FA`, PID `0x1440` (tested unit); vendor configuration also + lists PID `0x1E01`. Public A825 research lists PID `0x7F7F`. +- Product string: `USB GAMING MOUSE`; manufacturer string: `INSTANT`. +- Control collection: usage page `0xFF01`, usage `0x01`, interface 1. +- The collection exposes one feature report, report ID `0x07`. Windows reports + a feature report length of 8 bytes. +- The same report returns a 32-byte status block; the device accepts + `HidD_GetFeature` with a 32-byte buffer and fills the first 19 bytes. + +The A825 datasheet states: 32 KB storage, six CPI levels selected from 23 +values (`200 … 12800`), four configuration groups, report rates +125/250/500/1000 Hz, and ten backlight effects. + +## Transport + +Commands are 8-byte feature reports: + +``` +07 +``` + +Status read on report 7 returns: + +``` +07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... +``` + +`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed marker +`24 5A A5`. `state` and `n` change with device activity. + +## Block access + +Command `0x18` accesses a 16-bit, little-endian addressed configuration +memory. Writing a block: + +``` +07 18 03 +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Reading a block: + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → reply byte 1 +07 18 00 00 00 00 +``` + +`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a +save. + +Verified on the Kaze: the byte at `0x3A` read as `0x0B`; a block write set it +to `0x0A`; a read returned `0x0A`; restoring `0x0B` read back `0x0B`. + +## Stored configuration image + +`0x0000-0x0FFF` was read byte by byte. Non-empty regions: + +- `0x0000-0x008F` — device configuration (see below). +- `0x0400-0x04FF` — repeated 32-byte records beginning + `01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`. +- `0x0500-0x0FFF` — `FF` fill with `00 00` at every `0x100` boundary. + +The tested unit's `0x0000-0x008F`: + +``` +0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 +0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 +0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF +0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 +0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 +0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 +0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 +0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 +0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 +``` + +The vendor app's saved-image writer (`0x480B00`, named +`A825_WriteLightingConfig` in the analysis database) writes these blocks: + +| Address | Length | Meaning (from code) | +| --- | --- | --- | +| `0x0000` | 2 | Header | +| `0x0007` | 25 | Key map | +| `0x001C` | 2 | Stage-enable mask and flags | +| `0x0020` | 8 | Stage colours A | +| `0x0028` | 8 | Stage colours B | +| `0x0030` | 4 | Sensor options | +| `0x003A` | 1 | Lighting direction/symmetry | +| `0x003E` | 2 | Lighting | +| `0x0F80` | 2 | Trailer | + +`0x3A` holds +`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. +It is not the polling rate. + +## Polling rate + +The full configuration builder (`0x481400`, `A825_BuildConfigImage`) assembles +records keyed by their byte offset. Record `0x14` is: + +``` +(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 + + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) +``` + +The top two bits (`byte[0x8104] & 3`) are a 2-bit field. Writing all four +values to `0x14` read back correctly, but the measured report cadence stayed +at ~125 Hz for every value, so this field is **not confirmed** as the polling +rate; it may be applied only on save/reconnect or be a different setting. + +The complete 80-entry record table is in +[a825-config-records.md](./a825-config-records.md). + +## DPI + +`A825_LiveDpiAndButtons` (`0x486630`) sends: + +``` +07 12 00 00 00 00 00 when mode == 0 +07 12 … otherwise +07 11 00 00 00 00 00 00 commit +07 09 … four button-map frames +``` + +The 23 DPI gears are: + +``` +200 400 600 800 1000 1200 1400 1600 1800 2000 +2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 +10400 11200 12800 +``` + +Sending `0x12` on the Kaze did not change the stored image or the status +block. The six-stage CPI table was not found in `0x0000-0x0FFF`. + +## Lighting + +`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` +fields. `A825_ApplyLighting` (`0x469EB0`) collects `light_color`, +`light_color_en`, `light_brightness`, `light_speed`, `light_symmetry` and +`light_direction` from the vendor profile and calls the writer. + +The vendor app's Apply also sends `07 13 7F 00 00 20 07` from the +profile switch (`0x402700`). + +## Vendor Apply capture + +The Apply button writes 32-byte blocks from `0x0000` to `0x02C0`, then +`0x0F80`, then enters/leaves block mode: + +``` +0000: 5A 03 +0007: 00 21 22 23 24 25 26 20 15 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 01 00 +0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF 10 10 FF 3F 00 00 00 00 00 00 0B ... +0040..02C0: 32-byte blocks +0F80: 00 00 +07 18 10 00 00 00 00 00 +07 18 00 00 00 00 00 00 +``` + +## Evidence status + +| Claim | Evidence | +| --- | --- | +| VID/PID, collection, report ID 7, 8-byte feature reports | Device + Windows HID caps | +| 8-byte command frames accepted | Device | +| Block read/write framing and read-back | Device | +| Stored image contents `0x0000-0x0FFF` | Device | +| `0x3A` lighting fields | Vendor code (`0x480B00`) | +| Rate field `byte[0x831A] & 3` | Vendor code (`0x481400`) | +| DPI `0x12` encoding | Vendor code (`0x486630`) | +| Apply block sequence | Captured from the vendor app | + +## Devices + +The A825 is a chipset, not a model. The vendor's generic reference build is +`Instant A825 Gaming Mouse` (`instant-sys.com`, 2025-07-16) and is the same +`New825Tab` codebase as the Sades OEM build. Public listings of A825 mice: + +- Sades Kaze (Instant A825) — tested unit. +- Ant Esports GM320 — public reverse-engineering project. +- AJAZZ NJ08. +- Kreo Harpy. +- Cybeart Ghost. + +The protocol in this document is the vendor reference implementation, so it +applies to the same firmware family rather than only the Kaze. + +## Open questions + +- Record-to-address mapping in `A825_BuildConfigImage`, including record 7. +- The six-stage CPI table location. +- Button-map and lighting encodings beyond the frames listed here. diff --git a/package.json b/package.json index a360811..5921372 100644 --- a/package.json +++ b/package.json @@ -214,6 +214,10 @@ "types": "./dist/ryunix/index.d.ts", "import": "./dist/ryunix/index.js" }, + "./instant": { + "types": "./dist/instant/index.d.ts", + "import": "./dist/instant/index.js" + }, "./amkette": { "types": "./dist/amkette/index.d.ts", "import": "./dist/amkette/index.js" diff --git a/src/drivers/instant/a825-hid.test.ts b/src/drivers/instant/a825-hid.test.ts new file mode 100644 index 0000000..b0fbf6a --- /dev/null +++ b/src/drivers/instant/a825-hid.test.ts @@ -0,0 +1,117 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + INSTANT_REPORT_ID, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, +} from "@openmouse/protocol/instant"; +import { InstantA825HidClient } from "./a825-hid.ts"; + +function report(reportId: number): HIDReportInfo { + return { reportId, items: [] } as unknown as HIDReportInfo; +} + +function controlCollection(): HIDCollectionInfo { + return { + usagePage: INSTANT_USAGE_PAGE, + usage: INSTANT_USAGE, + type: 1, + children: [], + featureReports: [report(INSTANT_REPORT_ID)], + inputReports: [], + outputReports: [], + } as unknown as HIDCollectionInfo; +} + +const STATUS = Uint8Array.of( + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +); + +function fakeDevice(options: { + rate?: number; + productId?: number; +} = {}) { + let rate = options.rate ?? 0x0b; + let statusRead = false; + let readSetup = false; + const sent: Uint8Array[] = []; + let pendingWrite: { address: number; data: number[] } | null = null; + let writeFinished = false; + + const device = { + vendorId: INSTANT_VENDOR_ID, + productId: options.productId ?? 0x1440, + productName: "USB GAMING MOUSE", + opened: false, + collections: [controlCollection()], + async open() { + this.opened = true; + }, + async close() { + this.opened = false; + }, + async sendFeatureReport(_reportId: number, data: BufferSource) { + const view = ArrayBuffer.isView(data) + ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) + : new Uint8Array(data as ArrayBuffer); + const frame = Uint8Array.of(INSTANT_REPORT_ID, ...view); + sent.push(frame); + const address = frame[4]! | (frame[5]! << 8); + if (frame[1] === 0x18 && frame[2] === 0x03) { + readSetup = true; + if (frame[7] === 0) { + pendingWrite = { address, data: [frame[6]!] }; + } else if (pendingWrite?.address === address) { + pendingWrite.data[frame[3]!] = frame[6]!; + } + } + if (frame[1] === 0x18 && frame[2] === 0x09) { + writeFinished = true; + } + if (frame[1] === 0x18 && frame[2] === 0x00 && writeFinished) { + if (pendingWrite?.address === 0x3a) rate = pendingWrite.data[0]!; + pendingWrite = null; + writeFinished = false; + } + }, + async receiveFeatureReport(_reportId: number) { + if (readSetup) { + readSetup = false; + return new DataView(Uint8Array.of(INSTANT_REPORT_ID, rate, 0, 0, 0, 0, 0, 0).buffer); + } + statusRead = true; + return new DataView(STATUS.slice().buffer); + }, + } as unknown as HIDDevice; + + return { device, sent, get rate() { return rate; } }; +} + +test("A825 identifies the Sades Kaze control collection", () => { + const { device } = fakeDevice(); + assert.equal(InstantA825HidClient.isSupported(device), true); + assert.equal( + InstantA825HidClient.isSupported({ ...device, productId: 0x1234 } as HIDDevice), + false, + ); + assert.equal(InstantA825HidClient.isSupported({ ...device, vendorId: 0x1234 } as HIDDevice), false); +}); + +test("readStatus decodes firmware and stays read-only", async () => { + const { device } = fakeDevice({ rate: 0x0b }); + const client = new InstantA825HidClient(device); + const status = await client.readStatus(); + assert.equal(status.brand, "Sades"); + assert.equal(status.connectionType, "Wired"); + assert.equal(status.pollingRateHz, 0); + assert.equal(status.supportedPollingRates?.join(","), "125,250,500,1000"); + assert.equal(status.activeProfile, null); + assert.equal(status.dpi, 0); + assert.deepEqual(status.firmware, ["Build 0x0954"]); + assert.equal(status.ui?.settingsReady, false); + assert.equal(status.ui?.family, "sades-a825"); +}); diff --git a/src/drivers/instant/a825-hid.ts b/src/drivers/instant/a825-hid.ts new file mode 100644 index 0000000..bf4d235 --- /dev/null +++ b/src/drivers/instant/a825-hid.ts @@ -0,0 +1,248 @@ +import type { MouseStatus } from "../mouse-types.ts"; +import { + decodeInstantConfig, + decodeInstantStatus, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantFrame, + INSTANT_BLOCK, + INSTANT_COMMAND, + INSTANT_CONFIG_LENGTH, + INSTANT_DPI_GEARS, + INSTANT_POLLING_RATES, + INSTANT_PRODUCT_IDS, + INSTANT_REPORT_ID, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, + instantDpiFrames, + type InstantConfigImage, +} from "@openmouse/protocol/instant"; + +function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { + return collections.some( + (collection) => + (collection.usagePage === INSTANT_USAGE_PAGE && + collection.usage === INSTANT_USAGE && + collection.featureReports.some( + (report) => report.reportId === INSTANT_REPORT_ID, + )) || + hasConfigCollection(collection.children), + ); +} + +function statusBytes(view: DataView, reportId: number): Uint8Array { + const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); + return bytes[0] === reportId ? bytes.slice(1) : bytes.slice(); +} + +/** + * Sades Kaze / Instant A825 control client. + * + * Reads the 32-byte status block and the stored configuration image. Settings + * framing is implemented in `@openmouse/protocol/instant`. The DPI command has + * no observable read-back on this firmware and the polling-rate field is not yet + * mapped, so the panel shows this device as read-only. + */ +export class InstantA825HidClient { + readonly device: HIDDevice; + private config: InstantConfigImage | null = null; + private status: Uint8Array | null = null; + private queue: Promise = Promise.resolve(); + private generation = 0; + private opening: Promise | null = null; + + constructor(device: HIDDevice) { + this.device = device; + } + + static isSupported(device: HIDDevice): boolean { + return ( + device.vendorId === INSTANT_VENDOR_ID && + INSTANT_PRODUCT_IDS.has(device.productId) && + hasConfigCollection(device.collections) + ); + } + + getDpiOptions(): number[] { + return [...INSTANT_DPI_GEARS]; + } + + getPollingRateOptions(): number[] { + return [...INSTANT_POLLING_RATES]; + } + + async open(): Promise { + if (!InstantA825HidClient.isSupported(this.device)) { + throw new Error("Unsupported A825 HID interface"); + } + if (this.opening) return this.opening; + if (this.device.opened) return; + const generation = this.generation; + const task = (async () => { + await this.device.open(); + if (generation !== this.generation) { + if (this.device.opened) await this.device.close(); + throw new Error("A825 disconnected while opening"); + } + })(); + this.opening = task; + try { + await task; + } finally { + if (this.opening === task) this.opening = null; + } + } + + async close(): Promise { + this.generation += 1; + this.config = null; + this.status = null; + this.queue = Promise.resolve(); + await this.opening?.catch(() => undefined); + if (this.device.opened) await this.device.close(); + } + + /** Raw 32-byte status report, including report ID 7. */ + getRawStatusReport(): Uint8Array | null { + return this.status?.slice() ?? null; + } + + /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ + getConfigImage(): InstantConfigImage | null { + return this.config + ? { + ...this.config, + bytes: this.config.bytes.slice(), + } + : null; + } + + private serialize(action: () => Promise): Promise { + const generation = this.generation; + const task = this.queue.then(() => { + if (generation !== this.generation) { + throw new Error("A825 disconnected before queued transfer"); + } + return action(); + }); + this.queue = task.then( + () => undefined, + () => undefined, + ); + return task; + } + + private async send(frame: Uint8Array): Promise { + await this.device.sendFeatureReport( + INSTANT_REPORT_ID, + frame.slice(1).buffer, + ); + } + + private async readStatusReport(): Promise { + const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); + return statusBytes(view, INSTANT_REPORT_ID); + } + + /** Read one byte from the configuration image, using the vendor read path. */ + private async readByte(address: number): Promise { + const setup = instantBlockReadFrames(address, 1); + for (const frame of setup) await this.send(frame); + await this.send(instantBlockReadByteFrame(address, 0, 1)); + const report = await this.readStatusReport(); + // The vendor closes the read window after every byte. + await this.send( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + address & 0xff, + (address >>> 8) & 0xff, + 0, + 0, + ]), + ); + const full = new Uint8Array(report.length + 1); + full[0] = INSTANT_REPORT_ID; + full.set(report, 1); + const value = full.length > 1 ? full[1] : null; + if (value == null) throw new Error("A825 config read returned no data"); + return value; + } + + /** + * Read the stored configuration image. This is 0x300 one-byte reads and is + * intentionally explicit: read a small range when only a few bytes matter. + */ + async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { + if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { + throw new RangeError(`Invalid A825 config length: ${length}`); + } + return this.serialize(async () => { + await this.open(); + const bytes = new Uint8Array(INSTANT_CONFIG_LENGTH); + for (let address = 0; address < length; address += 1) { + bytes[address] = await this.readByte(address); + } + this.config = decodeInstantConfig(bytes); + return this.getConfigImage()!; + }); + } + + async readStatus(): Promise { + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const report = await this.readStatusReport(); + this.status = new Uint8Array(report.length + 1); + this.status[0] = INSTANT_REPORT_ID; + this.status.set(report, 1); + const decoded = decodeInstantStatus(this.status); + + return { + brand: "Sades", + name: this.device.productName || "Sades Kaze", + ui: { + family: "sades-a825", + settingsReady: false, + valuesVerified: decoded !== null, + pollingReadOnly: true, + hideProcessingCard: true, + hideSignalCard: true, + hideSleepCard: true, + defaultDisplayName: "Sades Kaze", + statusNote: + "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", + }, + batteryPercent: null, + batteryState: "Unknown", + dpi: 0, + pollingRateHz: 0, + supportedPollingRates: [...INSTANT_POLLING_RATES], + activeProfile: null, + connectionType: "Wired", + connectionDetail: "USB", + liftOffDistance: null, + firmware: + decoded != null + ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] + : [], + }; + }); + } + + /** + * Send the vendor's live DPI command. Kept for protocol tooling; the panel + * does not expose it because this firmware gives no read-back for the value. + */ + async setLiveDpi(dpi: number, mode = 0): Promise { + return this.serialize(async () => { + await this.open(); + for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); + return dpi; + }); + } +} diff --git a/src/drivers/mouse-types.ts b/src/drivers/mouse-types.ts index b5e8e2b..42079ec 100644 --- a/src/drivers/mouse-types.ts +++ b/src/drivers/mouse-types.ts @@ -233,7 +233,7 @@ export interface MouseStatus { dynamicDpi: KeychronDynamicDpi | null; factoryReset: boolean; }; - brand: "RAWM" | "Motospeed" | "Logitech" | "Pulsar" | "Endgame Gear" | "WLMouse" | "G-Wolves" | "Lamzu" | "CRDRAKO" | "Attack Shark" | "LunaFury" | "Vancer" | "Orbital" | "Razer" | "Teevolution" | "ATK" | "VXE" | "VGN" | "VAXEE" | "Finalmouse" | "Keychron" | "moddoMOUSE" | "Ninjutso" | "Zaunkoenig" | "Fantech" | "Wooting" | "WALLHACK" | "SteelSeries" | "Glorious" | "MCHOSE" | "K-snake" | "Noir Gear" | "Lingbao" | "GearHub" | "AJAZZ" | "Corsair" | "Microsoft" | "Dareu" | "Redragon" | "Incott" | "HyperX" | "ASUS" | "Ryunix" | "Amkette" | "Delux" | "GravaStar" | "IPI" | "Rapoo" | "Fater" | "Cooler Master" | "AJAZZ" | "Scyrox" | "Hitscan" | "ROCCAT" | "Thermaltake" | "Redgear" | "AULA"; + brand: "RAWM" | "Motospeed" | "Logitech" | "Pulsar" | "Endgame Gear" | "WLMouse" | "G-Wolves" | "Lamzu" | "CRDRAKO" | "Attack Shark" | "LunaFury" | "Vancer" | "Orbital" | "Razer" | "Teevolution" | "ATK" | "VXE" | "VGN" | "VAXEE" | "Finalmouse" | "Keychron" | "moddoMOUSE" | "Ninjutso" | "Zaunkoenig" | "Fantech" | "Wooting" | "WALLHACK" | "SteelSeries" | "Glorious" | "MCHOSE" | "K-snake" | "Noir Gear" | "Lingbao" | "GearHub" | "AJAZZ" | "Corsair" | "Microsoft" | "Dareu" | "Redragon" | "Incott" | "HyperX" | "ASUS" | "Ryunix" | "Amkette" | "Delux" | "GravaStar" | "IPI" | "Rapoo" | "Fater" | "Cooler Master" | "AJAZZ" | "Scyrox" | "Hitscan" | "ROCCAT" | "Thermaltake" | "Redgear" | "AULA" | "Sades"; name: string; /** Optional LunaFury controls, populated only after successful device reads. */ lunafury?: import("../lamzu/lunafury.js").LunaFurySettings; diff --git a/src/drivers/registry.ts b/src/drivers/registry.ts index a245b65..e647fa6 100644 --- a/src/drivers/registry.ts +++ b/src/drivers/registry.ts @@ -104,9 +104,10 @@ import { AjazzAk820HidClient } from "./ajazz/ak820-hid.ts"; import { RoccatHidClient } from "./roccat/hid.ts"; import { HitscanHidClient } from "./hitscan/hid.ts"; import { HitscanXviHidClient } from "./hitscan/xvi-hid.ts"; +import { InstantA825HidClient } from "./instant/a825-hid.ts"; export type PulsarClient = PulsarHidClient | PulsarProHidClient | PulsarXs1HidClient; -export type SupportedClient = RawmHidClient | MotospeedHidClient | LogitechHidppClient | PulsarClient | EggOp1HidClient | EggOtHidClient | EggWeHidClient | FinalmouseHidClient | WLMouseHidClient | WLMouseBeastX4kHidClient | LamzuHidClient | LamzuAtlantisHidClient | OrbitalHidClient | RazerHidClient | RazerViperHidClient | RazerViperMiniHidClient | RazerViperV4ProHidClient | RazerCobraHidClient | TeevolutionHidClient | AtkHidClient | AtkBitmouseHidClient | VgnF2HidClient | VaxeeHidClient | Keychron8kHidClient | Keychron1kHidClient | Keychron4kHidClient | Keychron8kNordicHidClient | KeychronNapeHidClient | ModdoHidClient | NinjutsoHidClient | ZaunkoenigHidClient | CorsairHidClient | CorsairBragiHidClient | AttackSharkHidClient | FantechHidClient | GearHubHidClient | WootingHidClient | WallhackMouseHidClient | WallhackKeyboardHidClient | GWolvesHidClient | GWolvesXviHidClient | GWolvesXviNewHidClient | SteelSeriesRival3HidClient | SteelSeriesAerox3HidClient | SteelSeriesAerox3WirelessHidClient | SteelSeriesRival3WirelessHidClient | SteelSeriesAerox5HidClient | SteelSeriesAerox5WirelessHidClient | SteelSeriesRival650HidClient | SteelSeriesAerox9WirelessHidClient | SteelSeriesRival310HidClient | SteelSeriesPrimePlusHidClient | SteelSeriesPrimeMiniWirelessHidClient | SteelSeriesSenseiTenHidClient | SteelSeriesSenseiRivalProHidClient | SteelSeriesSensei310HidClient | SteelSeriesPrimeMiniHidClient | SteelSeriesRival5HidClient | SteelSeriesRival3Gen2HidClient | SteelSeriesRival3WirelessV2HidClient | SteelSeriesAerox3WirelessGen2HidClient | SteelSeriesRival600HidClient | SteelSeriesRival100HidClient | SteelSeriesRival110HidClient | SteelSeriesRival300HidClient | SteelSeriesSenseiRawHidClient | GloriousHidClient | GloriousClassicHidClient | GloriousCore2HidClient | GloriousSinowealthHidClient | MchoseHidClient | MchoseDockHidClient | MchoseA5ProMaxHidClient | KsnakeHidClient | MicrosoftHidClient | DareuHidClient | RedragonHidClient | RedragonM690ProHidClient | RedragonM719ProHidClient | IncottHidClient | HyperXHidClient | MchoseV3HidClient | AsusHidClient | KyuProMx1Client | AmketteXsHidClient | DeluxHidClient | BytechHidClient | RapooHidClient | FaterHidClient | CoolerMasterHidClient | AjazzHidClient | AjazzAj200pHidClient | AjazzAk820HidClient | ScyroxHidClient | HitscanHidClient | RoccatHidClient | ThermaltakeHidClient | RedgearX13HidClient | AulaSc380ProHidClient; +export type SupportedClient = RawmHidClient | MotospeedHidClient | LogitechHidppClient | PulsarClient | EggOp1HidClient | EggOtHidClient | EggWeHidClient | FinalmouseHidClient | WLMouseHidClient | WLMouseBeastX4kHidClient | LamzuHidClient | LamzuAtlantisHidClient | OrbitalHidClient | RazerHidClient | RazerViperHidClient | RazerViperMiniHidClient | RazerViperV4ProHidClient | RazerCobraHidClient | TeevolutionHidClient | AtkHidClient | AtkBitmouseHidClient | VgnF2HidClient | VaxeeHidClient | Keychron8kHidClient | Keychron1kHidClient | Keychron4kHidClient | Keychron8kNordicHidClient | KeychronNapeHidClient | ModdoHidClient | NinjutsoHidClient | ZaunkoenigHidClient | CorsairHidClient | CorsairBragiHidClient | AttackSharkHidClient | FantechHidClient | GearHubHidClient | WootingHidClient | WallhackMouseHidClient | WallhackKeyboardHidClient | GWolvesHidClient | GWolvesXviHidClient | GWolvesXviNewHidClient | SteelSeriesRival3HidClient | SteelSeriesAerox3HidClient | SteelSeriesAerox3WirelessHidClient | SteelSeriesRival3WirelessHidClient | SteelSeriesAerox5HidClient | SteelSeriesAerox5WirelessHidClient | SteelSeriesRival650HidClient | SteelSeriesAerox9WirelessHidClient | SteelSeriesRival310HidClient | SteelSeriesPrimePlusHidClient | SteelSeriesPrimeMiniWirelessHidClient | SteelSeriesSenseiTenHidClient | SteelSeriesSenseiRivalProHidClient | SteelSeriesSensei310HidClient | SteelSeriesPrimeMiniHidClient | SteelSeriesRival5HidClient | SteelSeriesRival3Gen2HidClient | SteelSeriesRival3WirelessV2HidClient | SteelSeriesAerox3WirelessGen2HidClient | SteelSeriesRival600HidClient | SteelSeriesRival100HidClient | SteelSeriesRival110HidClient | SteelSeriesRival300HidClient | SteelSeriesSenseiRawHidClient | GloriousHidClient | GloriousClassicHidClient | GloriousCore2HidClient | GloriousSinowealthHidClient | MchoseHidClient | MchoseDockHidClient | MchoseA5ProMaxHidClient | KsnakeHidClient | MicrosoftHidClient | DareuHidClient | RedragonHidClient | RedragonM690ProHidClient | RedragonM719ProHidClient | IncottHidClient | HyperXHidClient | MchoseV3HidClient | AsusHidClient | KyuProMx1Client | AmketteXsHidClient | DeluxHidClient | BytechHidClient | RapooHidClient | FaterHidClient | CoolerMasterHidClient | AjazzHidClient | AjazzAj200pHidClient | AjazzAk820HidClient | ScyroxHidClient | HitscanHidClient | RoccatHidClient | ThermaltakeHidClient | RedgearX13HidClient | AulaSc380ProHidClient | InstantA825HidClient; export interface DeviceDriver { brand: string; supports(device: HIDDevice): boolean; @@ -266,6 +267,9 @@ export const DEVICE_DRIVERS: readonly DeviceDriver[] = [ // Windows hides the config collection; the mouse interface still switches // profiles, and the keyboard interface alone is status only. { brand: "Thermaltake", supports: (device) => ThermaltakeHidClient.isSupported(device), create: (device) => new ThermaltakeHidClient(device), score: (device) => THERMALTAKE_CHANNEL_SCORE[thermaltakeChannel(device) ?? "none"] }, + // Instant A825 controls: VID 0x30FA with a report-7 feature collection on + // usage page 0xFF01. Sades sells several A825 mice under one driver. + { brand: "Sades", supports: (device) => InstantA825HidClient.isSupported(device), create: (device) => new InstantA825HidClient(device), score: () => 7 }, ]; const THERMALTAKE_CHANNEL_SCORE = { config: 7, short: 5, none: 2 } as const; diff --git a/src/drivers/vendors.ts b/src/drivers/vendors.ts index a2a9e36..6617f10 100644 --- a/src/drivers/vendors.ts +++ b/src/drivers/vendors.ts @@ -177,11 +177,18 @@ import { COOLERMASTER_VENDOR_ID, } from "@openmouse/protocol/coolermaster"; import { AJAZZ_AK820_WIRED_PID } from "../ajazz/ak820.ts"; +import { + INSTANT_PRODUCT_IDS, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, +} from "@openmouse/protocol/instant"; import { AJ200P_PRODUCTS, AJ200P_USAGE, AJ200P_USAGE_PAGE, AJ200P_VENDOR_ID } from "../ajazz/aj200p.ts"; export const VENDOR_ID = { ajazzAj200p: AJ200P_VENDOR_ID, redgear: REDGEAR_X13_VENDOR_ID, + sades: INSTANT_VENDOR_ID, coolermaster: COOLERMASTER_VENDOR_ID, ajazz: 0x1a2c, vaxee: VAXEE_VENDOR_ID, @@ -986,6 +993,12 @@ export const SUPPORTED_HID_FILTERS: HIDDeviceFilter[] = [ }, ...[...AJ200P_PRODUCTS.keys()].map((productId) => ({ vendorId: AJ200P_VENDOR_ID, productId, usagePage: AJ200P_USAGE_PAGE, usage: AJ200P_USAGE })), { vendorId: VENDOR_ID.redgear, productId: REDGEAR_X13_PRODUCT_ID, usagePage: REDGEAR_X13_USAGE_PAGE, usage: REDGEAR_X13_USAGE }, + ...[...INSTANT_PRODUCT_IDS].map((productId) => ({ + vendorId: INSTANT_VENDOR_ID, + productId, + usagePage: INSTANT_USAGE_PAGE, + usage: INSTANT_USAGE, + })), ...VAXEE_HID_FILTERS, ...ASUS_HID_FILTERS, ...DAREU_HID_FILTERS, diff --git a/src/instant/index.ts b/src/instant/index.ts new file mode 100644 index 0000000..498582f --- /dev/null +++ b/src/instant/index.ts @@ -0,0 +1 @@ +export * from "./protocol.js"; diff --git a/src/instant/protocol.test.ts b/src/instant/protocol.test.ts new file mode 100644 index 0000000..a354fed --- /dev/null +++ b/src/instant/protocol.test.ts @@ -0,0 +1,117 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + decodeInstantConfig, + decodeInstantReadByte, + decodeInstantStatus, + INSTANT_CONFIG, + INSTANT_DPI_GEARS, + INSTANT_REPORT_ID, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantBlockWriteFrames, + instantDpiFrames, + instantDpiGearIndex, + instantFrame, + instantModeFrames, +} from "./protocol.ts"; + +function hex(frame: Uint8Array): string { + return Buffer.from(frame).toString("hex"); +} + +test("instantFrame pads to an 8-byte report 7 frame", () => { + assert.equal(hex(instantFrame(0x18, [0x03, 0])), "0718030000000000"); + assert.equal(instantFrame(0x18).length, 8); + assert.equal(instantFrame(0x18)[0], INSTANT_REPORT_ID); + assert.throws(() => instantFrame(0x18, [1, 2, 3, 4, 5, 6, 7]), RangeError); +}); + +test("block write matches the vendor's captured Apply frames", () => { + const frames = instantBlockWriteFrames(0x0000, [0x5a, 0x03]); + assert.deepEqual(frames.map(hex), [ + "0718030000005a01", + "0718030100000301", + "0718090000000001", + "0718000000000000", + ]); + const high = instantBlockWriteFrames(0x003a, [0x0b]); + assert.equal(hex(high[0]!), "071803003a000b00"); + assert.equal(hex(high[1]!), "071809003a000000"); +}); + +test("block read uses little-endian addresses and a final commit", () => { + const frames = instantBlockReadFrames(0x003a, 2); + assert.equal(frames.length, 3); + assert.equal(hex(frames[0]!), "071803003a000001"); + assert.equal(hex(frames[1]!), "071803013a000001"); + assert.equal(hex(frames[2]!), "071800003a000000"); + assert.equal(hex(instantBlockReadByteFrame(0x003a, 1, 2)), "071805013a000001"); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07, 0x0b])), 0x0b); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07])), null); +}); + +test("DPI frames match the vendor's 0x12 encoding", () => { + assert.deepEqual(instantDpiFrames(800).map(hex), [ + "0712640000000000", + "0711000000000000", + ]); + assert.deepEqual(instantDpiFrames(1600, 1).map(hex), [ + "0712006400000000", + "0711000000000000", + ]); + assert.throws(() => instantDpiFrames(300, 1), RangeError); + assert.throws(() => instantDpiFrames(123), RangeError); +}); + +test("mode frames enter and leave block mode", () => { + assert.equal(hex(instantModeFrames(true)[0]!), "0718100000000000"); + assert.equal(hex(instantModeFrames(false)[0]!), "0718000000000000"); +}); + +test("config decode keeps the lighting byte raw", () => { + // Ghidra: 0x3A packs light_direction/light_symmetry, not the polling rate. + const config = decodeInstantConfig(new Uint8Array([...new Uint8Array(0x3a), 0x0b])); + assert.equal(config.lightingDirectionByte, 0x0b); + assert.equal(config.bytes[0x3a], 0x0b); +}); + +test("DPI table is the vendor's 23-value table", () => { + assert.equal(INSTANT_DPI_GEARS.length, 23); + assert.equal(instantDpiGearIndex(200), 1); + assert.equal(instantDpiGearIndex(12800), 23); + assert.equal(instantDpiGearIndex(300), null); +}); + +test("status decode keeps the vendor block markers", () => { + const report = new Uint8Array([ + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + ]); + assert.deepEqual(decodeInstantStatus(report), { + firmware: 0x0954, + state: 0x00, + sensorCpi: 0x0626, + magicOk: true, + }); + assert.equal(decodeInstantStatus(new Uint8Array(8)), null); + const broken = report.slice(); + broken[16] = 0x00; + assert.equal(decodeInstantStatus(broken)?.magicOk, false); +}); + +test("config address map is the vendor's Apply layout", () => { + assert.deepEqual(INSTANT_CONFIG, { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, + }); +}); diff --git a/src/instant/protocol.ts b/src/instant/protocol.ts new file mode 100644 index 0000000..dd28469 --- /dev/null +++ b/src/instant/protocol.ts @@ -0,0 +1,339 @@ +/** + * Instant Microelectronics A825 configuration protocol. + * + * Reverse-engineered from the vendor control app shipped for the Sades Kaze + * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` + * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a + * Sades Kaze on VID 0x30FA / PID 0x1440. + * + * Transport + * --------- + * The control collection is usage page 0xFF01, usage 1, on interface 1. Its + * only feature report is report ID 7. The vendor app and the device both use + * 8-byte feature reports: + * + * [0x07, command, a, b, c, d, e, f] + * + * The same report also carries a 32-byte status block that the device returns + * from a feature read; only the first eight bytes are used for command replies. + * + * Block access (command 0x18) + * --------------------------- + * The device exposes a 16-bit, little-endian addressed configuration memory. + * A block is written as one frame per byte, then finished and committed: + * + * 07 18 03 + * 07 18 09 00 00 + * 07 18 00 00 00 00 + * + * A byte is read by issuing the same address/length setup and then one frame + * per byte: + * + * 07 18 03 00 00 + * 07 18 00 00 00 00 + * 07 18 05 00 → reply byte 1 + * 07 18 00 00 00 00 + * + * Verified on hardware: writing the byte at 0x3A and reading it back returns + * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not + * the polling rate. The 0x0000-0x0FFF image is readable with + * `instantBlockReadFrames`. + * + * Direct commands + * --------------- + * The vendor app also writes a DPI value and a button map directly: + * + * 07 12 00 00 00 00 00 (mode 0) + * 07 12 ... (other modes) + * 07 11 00 ... commit + * 07 09 ... button map + * 07 17 ... 16-bit key/function code + * 07 13 ... lighting/mode + * + * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the + * 0x0F80 trailer). The direct commands above are read from the vendor code; + * sending 0x12 on the tested unit changed neither the stored image nor the + * status block. + */ + +export const INSTANT_VENDOR_ID = 0x30fa; + +/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ +export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ + 0x1440, 0x1e01, 0x7f7f, +]); + +export const INSTANT_USAGE_PAGE = 0xff01; +export const INSTANT_USAGE = 0x01; +export const INSTANT_INTERFACE = 1; + +export const INSTANT_REPORT_ID = 0x07; +export const INSTANT_FRAME_LENGTH = 8; +/** Status block returned by a feature read on report 7. */ +export const INSTANT_STATUS_LENGTH = 32; + +export const INSTANT_COMMAND = { + block: 0x18, + dpi: 0x12, + apply: 0x11, + buttonMap: 0x09, + keyCode: 0x17, + notice: 0x13, +} as const; + +export const INSTANT_BLOCK = { + write: 0x03, + read: 0x05, + finish: 0x09, + commit: 0x00, + mode: 0x10, +} as const; + +/** + * Configuration image addresses written by the vendor app's + * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes + * between blocks are untouched. + */ +export const INSTANT_CONFIG = { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, +} as const; + +/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ +export const INSTANT_CONFIG_LENGTH = 0x1000; + +/** + * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array + * index + 1 is the on-wire gear index (the value the vendor app stores in a + * DPI stage); the second number in the INI is a separate firmware code. + */ +export const INSTANT_DPI_GEARS: readonly number[] = [ + 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, + 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, +]; + +export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; + +export function instantDpiGearIndex(dpi: number): number | null { + const index = INSTANT_DPI_GEARS.indexOf(dpi); + return index < 0 ? null : index + 1; +} + +function byte(value: number, name: string): number { + if (!Number.isInteger(value) || value < 0 || value > 0xff) { + throw new RangeError(`${name} is not a byte: ${value}`); + } + return value; +} + +/** Build one 8-byte report. `params` fills bytes 2..7. */ +export function instantFrame( + command: number, + params: readonly number[] = [], +): Uint8Array { + if (params.length > 6) { + throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); + } + const frame = new Uint8Array(INSTANT_FRAME_LENGTH); + frame[0] = INSTANT_REPORT_ID; + frame[1] = byte(command, "command"); + params.forEach((value, index) => { + frame[2 + index] = byte(value, `parameter ${index}`); + }); + return frame; +} + +/** Frames that write `data` to `address`, followed by finish and commit. */ +export function instantBlockWriteFrames( + address: number, + data: readonly number[], +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (data.length === 0 || data.length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${data.length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = data.length - 1; + const frames = data.map((value, index) => + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + byte(value, `data byte ${index}`), + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.finish, + 0, + low, + high, + 0, + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frames that prepare and read `length` bytes from `address`. */ +export function instantBlockReadFrames( + address: number, + length: number, +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = length - 1; + const frames: Uint8Array[] = []; + for (let index = 0; index < length; index += 1) { + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + 0, + last, + ]), + ); + } + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frame that requests byte `index` of the prepared read block. */ +export function instantBlockReadByteFrame( + address: number, + index: number, + length: number, +): Uint8Array { + return instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.read, + index, + address & 0xff, + (address >>> 8) & 0xff, + 0, + length - 1, + ]); +} + +/** The value returned by a read byte frame lives at report byte 1. */ +export function decodeInstantReadByte(report: Uint8Array): number | null { + return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; +} + +/** Frames that set a live DPI value and commit it. */ +export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { + const gear = instantDpiGearIndex(dpi); + if (gear == null) { + throw new RangeError(`Unsupported A825 DPI: ${dpi}`); + } + if (mode === 0) { + return [ + instantFrame(INSTANT_COMMAND.dpi, [Math.round(dpi / 8), 0, 0, 0, 0, 0]), + instantFrame(INSTANT_COMMAND.apply), + ]; + } + const units = Math.round(dpi / 16); + return [ + instantFrame(INSTANT_COMMAND.dpi, [ + (units >>> 8) & 0xff, + units & 0xff, + 0, + 0, + 0, + 0, + ]), + instantFrame(INSTANT_COMMAND.apply), + ]; +} + +/** Enter or leave the block-write mode used at the end of an Apply. */ +export function instantModeFrames(enter: boolean): Uint8Array[] { + return [ + instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), + ]; +} + +export interface InstantConfigImage { + /** Raw 0x0000-0x02FF configuration image. */ + bytes: Uint8Array; + /** + * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and + * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); + * it is NOT the polling rate. Kept raw until the layout is fully named. + */ + lightingDirectionByte: number; +} + +export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { + if (bytes.length < INSTANT_CONFIG.lightingDirection + 1) { + throw new RangeError("Instant config image is truncated"); + } + return { + bytes, + lightingDirectionByte: bytes[INSTANT_CONFIG.lightingDirection]!, + }; +} + +export interface InstantStatus { + /** Firmware/build word at bytes 2-3, big-endian (0x0954 on the Kaze). */ + firmware: number; + /** State byte 1; changes with device activity. */ + state: number; + /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ + sensorCpi: number; + /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ + magicOk: boolean; +} + +export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { + if (report.length < 20) return null; + const offset = report[0] === INSTANT_REPORT_ID ? 1 : 0; + if (report.length < offset + 19) return null; + return { + firmware: report[offset + 1]! | (report[offset + 2]! << 8), + state: report[offset]!, + sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), + magicOk: + report[offset + 15] === 0x24 && + report[offset + 16] === 0x5a && + report[offset + 17] === 0xa5, + }; +} From 1fddcbc615871ecb082bab35f1ca2e5440537d03 Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:44:02 +0700 Subject: [PATCH 2/6] docs(instant): align A825 protocol doc with device-doc conventions - Reorganized identity, evidence, transport, validation, unknowns and sources to match the repository's device docs. - Recorded the measured rate sweep result and the read-only scope. --- docs/instant-a825.md | 409 +++++++++++++++++++++---------------------- 1 file changed, 203 insertions(+), 206 deletions(-) diff --git a/docs/instant-a825.md b/docs/instant-a825.md index e503496..a6450ce 100644 --- a/docs/instant-a825.md +++ b/docs/instant-a825.md @@ -1,206 +1,203 @@ -# Instant A825 / Sades Kaze protocol - -This document describes what is known about the Instant A825 control protocol -as used by the Sades Kaze. It separates behaviour observed on the device from -behaviour read out of the vendor binary. - -## Device - -- Vendor: Wuxi Instant Microelectronics (A825 chipset). -- Sades model: Kaze, `Sades Kaze (Instant A825)`. -- USB: VID `0x30FA`, PID `0x1440` (tested unit); vendor configuration also - lists PID `0x1E01`. Public A825 research lists PID `0x7F7F`. -- Product string: `USB GAMING MOUSE`; manufacturer string: `INSTANT`. -- Control collection: usage page `0xFF01`, usage `0x01`, interface 1. -- The collection exposes one feature report, report ID `0x07`. Windows reports - a feature report length of 8 bytes. -- The same report returns a 32-byte status block; the device accepts - `HidD_GetFeature` with a 32-byte buffer and fills the first 19 bytes. - -The A825 datasheet states: 32 KB storage, six CPI levels selected from 23 -values (`200 … 12800`), four configuration groups, report rates -125/250/500/1000 Hz, and ten backlight effects. - -## Transport - -Commands are 8-byte feature reports: - -``` -07 -``` - -Status read on report 7 returns: - -``` -07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... -``` - -`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed marker -`24 5A A5`. `state` and `n` change with device activity. - -## Block access - -Command `0x18` accesses a 16-bit, little-endian addressed configuration -memory. Writing a block: - -``` -07 18 03 -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Reading a block: - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → reply byte 1 -07 18 00 00 00 00 -``` - -`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a -save. - -Verified on the Kaze: the byte at `0x3A` read as `0x0B`; a block write set it -to `0x0A`; a read returned `0x0A`; restoring `0x0B` read back `0x0B`. - -## Stored configuration image - -`0x0000-0x0FFF` was read byte by byte. Non-empty regions: - -- `0x0000-0x008F` — device configuration (see below). -- `0x0400-0x04FF` — repeated 32-byte records beginning - `01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`. -- `0x0500-0x0FFF` — `FF` fill with `00 00` at every `0x100` boundary. - -The tested unit's `0x0000-0x008F`: - -``` -0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 -0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 -0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF -0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 -0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 -0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 -0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 -0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 -0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 -``` - -The vendor app's saved-image writer (`0x480B00`, named -`A825_WriteLightingConfig` in the analysis database) writes these blocks: - -| Address | Length | Meaning (from code) | -| --- | --- | --- | -| `0x0000` | 2 | Header | -| `0x0007` | 25 | Key map | -| `0x001C` | 2 | Stage-enable mask and flags | -| `0x0020` | 8 | Stage colours A | -| `0x0028` | 8 | Stage colours B | -| `0x0030` | 4 | Sensor options | -| `0x003A` | 1 | Lighting direction/symmetry | -| `0x003E` | 2 | Lighting | -| `0x0F80` | 2 | Trailer | - -`0x3A` holds -`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. -It is not the polling rate. - -## Polling rate - -The full configuration builder (`0x481400`, `A825_BuildConfigImage`) assembles -records keyed by their byte offset. Record `0x14` is: - -``` -(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 - + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) -``` - -The top two bits (`byte[0x8104] & 3`) are a 2-bit field. Writing all four -values to `0x14` read back correctly, but the measured report cadence stayed -at ~125 Hz for every value, so this field is **not confirmed** as the polling -rate; it may be applied only on save/reconnect or be a different setting. - -The complete 80-entry record table is in -[a825-config-records.md](./a825-config-records.md). - -## DPI - -`A825_LiveDpiAndButtons` (`0x486630`) sends: - -``` -07 12 00 00 00 00 00 when mode == 0 -07 12 … otherwise -07 11 00 00 00 00 00 00 commit -07 09 … four button-map frames -``` - -The 23 DPI gears are: - -``` -200 400 600 800 1000 1200 1400 1600 1800 2000 -2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 -10400 11200 12800 -``` - -Sending `0x12` on the Kaze did not change the stored image or the status -block. The six-stage CPI table was not found in `0x0000-0x0FFF`. - -## Lighting - -`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` -fields. `A825_ApplyLighting` (`0x469EB0`) collects `light_color`, -`light_color_en`, `light_brightness`, `light_speed`, `light_symmetry` and -`light_direction` from the vendor profile and calls the writer. - -The vendor app's Apply also sends `07 13 7F 00 00 20 07` from the -profile switch (`0x402700`). - -## Vendor Apply capture - -The Apply button writes 32-byte blocks from `0x0000` to `0x02C0`, then -`0x0F80`, then enters/leaves block mode: - -``` -0000: 5A 03 -0007: 00 21 22 23 24 25 26 20 15 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 01 00 -0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF 10 10 FF 3F 00 00 00 00 00 00 0B ... -0040..02C0: 32-byte blocks -0F80: 00 00 -07 18 10 00 00 00 00 00 -07 18 00 00 00 00 00 00 -``` - -## Evidence status - -| Claim | Evidence | -| --- | --- | -| VID/PID, collection, report ID 7, 8-byte feature reports | Device + Windows HID caps | -| 8-byte command frames accepted | Device | -| Block read/write framing and read-back | Device | -| Stored image contents `0x0000-0x0FFF` | Device | -| `0x3A` lighting fields | Vendor code (`0x480B00`) | -| Rate field `byte[0x831A] & 3` | Vendor code (`0x481400`) | -| DPI `0x12` encoding | Vendor code (`0x486630`) | -| Apply block sequence | Captured from the vendor app | - -## Devices - -The A825 is a chipset, not a model. The vendor's generic reference build is -`Instant A825 Gaming Mouse` (`instant-sys.com`, 2025-07-16) and is the same -`New825Tab` codebase as the Sades OEM build. Public listings of A825 mice: - -- Sades Kaze (Instant A825) — tested unit. -- Ant Esports GM320 — public reverse-engineering project. -- AJAZZ NJ08. -- Kreo Harpy. -- Cybeart Ghost. - -The protocol in this document is the vendor reference implementation, so it -applies to the same firmware family rather than only the Kaze. - -## Open questions - -- Record-to-address mapping in `A825_BuildConfigImage`, including record 7. -- The six-stage CPI table location. -- Button-map and lighting encodings beyond the frames listed here. +# Instant A825 + +Protocol of the Instant Microelectronics A825 control interface, reverse +engineered from the vendor `DevDock.exe` and verified on a Sades Kaze. + +## Identity and connection paths + +- Vendor: Wuxi Instant Microelectronics (A825 chipset). +- Tested model: Sades Kaze (Instant A825), wired USB. +- USB: VID `0x30FA`, PID `0x1440`; the vendor configuration also lists PID + `0x1E01`. Public A825 research lists PID `0x7F7F`. +- Product string `USB GAMING MOUSE`, manufacturer string `INSTANT`. +- Configuration collection: usage page `0xFF01`, usage `0x01`, interface 1. +- Report 7 is the only feature report. Windows reports an 8-byte feature + report; the same report returns a 32-byte status block. +- Firmware/build word in the status block: `0x0954`. + +## Evidence + +- `SadesKaze(A825).[20241009].exe` → `DevDock.exe`, product `New825Tab`, + 32-bit MSVC + DuiLib, SHA-256 + `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`. +- Chip vendor reference build: `Instant A825 Mouse Reference + Driver.[20250716]` from instant-sys.com, same `New825Tab` codebase with a + generic `Instant A825 Gaming Mouse` profile. +- Ghidra analysis of the Sades build; the function names below are the + annotated names in that database. `docs/devdock-functions.md` lists the + addresses; `docs/a825-config-records.md` lists every configuration record. +- A825 datasheet V1.01 (Instant Microelectronics). + +## Transport + +Commands are 8-byte feature reports: + +``` +07 +``` + +Status read on report 7: + +``` +07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... +``` + +`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed `24 5A A5` +marker. `state` and `n` change with device activity. + +## Block access + +Command `0x18` addresses a 16-bit little-endian configuration memory. Write: + +``` +07 18 03 +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Read: + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → reply byte 1 +07 18 00 00 00 00 +``` + +`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a +save. `A825_BlockWrite` is `0x455A40`; `A825_BlockMode` is `0x455BA0`. + +## Vendor command paths + +| Command | Path | Purpose | +| --- | --- | --- | +| `18` | `A825_BlockWrite` / `A825_BlockMode` | Read/write the configuration image | +| `12` | `A825_LiveDpiAndButtons` (`0x486630`) | Live DPI value | +| `11` | `A825_LiveDpiAndButtons` | Commit | +| `09` | `A825_ButtonMap` (`0x486440`), `A825_ButtonMapFrame` (`0x454B30`) | Button map | +| `17` | `A825_KeyCodeFrame` (`0x454BA0`) | 16-bit key/function code | +| `13` | profile switch (`0x402700`) | Lighting/mode | +| `18 10`/`18 00` | `A825_BlockMode` | Enter/leave save mode | + +`A825_BuildConfigImage` (`0x481400`) assembles the stored image as +offset/value records. `A825_WriteLightingConfig` (`0x480B00`) writes the +lighting blocks. `A825_ApplyLighting` (`0x469EB0`) collects the lighting UI +and calls the writer. + +## Stored configuration + +The tested unit's `0x0000-0x008F`: + +``` +0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 +0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 +0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF +0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 +0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 +0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 +0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 +0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 +0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 +``` + +`0x0400-0x04FF` holds repeated 32-byte records beginning +`01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`; +`0x0500-0x0FFF` is `FF` fill with `00 00` at every `0x100` boundary. + +Blocks written by the vendor application: + +| Address | Length | Meaning (from code) | +| --- | --- | --- | +| `0x0000` | 2 | Header | +| `0x0007` | 25 | Key map | +| `0x001C` | 2 | Stage-enable mask and flags | +| `0x0020` | 8 | Stage colours A | +| `0x0028` | 8 | Stage colours B | +| `0x0030` | 4 | Sensor options | +| `0x003A` | 1 | Lighting direction/symmetry | +| `0x003E` | 2 | Lighting | +| `0x0F80` | 2 | Trailer | + +`0x3A` holds +`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. +It is not the polling rate. + +## Polling rate + +Record `0x14` of `A825_BuildConfigImage` is: + +``` +(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 + + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) +``` + +The top two bits are a 2-bit field. All four values were written to `0x14` and +read back correctly, but the measured report cadence stayed at ~125 Hz for +every value. The field is therefore not confirmed as the polling rate; it may +be applied only on save/reconnect or be a different setting. + +## DPI + +`A825_LiveDpiAndButtons` sends: + +``` +07 12 00 00 00 00 00 mode 0 +07 12 … other modes +07 11 00 00 00 00 00 00 commit +07 09 … four button-map frames +``` + +The 23 DPI gears: + +``` +200 400 600 800 1000 1200 1400 1600 1800 2000 +2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 +10400 11200 12800 +``` + +Sending `0x12` on the tested unit did not change the stored image or the +status block. The six-stage CPI table was not found in `0x0000-0x0FFF`. + +## Lighting + +`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` +fields. `A825_ApplyLighting` collects `light_color`, `light_color_en`, +`light_brightness`, `light_speed`, `light_symmetry` and `light_direction`. +The profile switch also sends `07 13 7F 00 00 20 07`. + +## Validation + +| Claim | Result | +| --- | --- | +| VID/PID, `0xFF01:0x01`, report 7, 8-byte feature reports | Observed | +| 8-byte command frames accepted | Observed | +| Block write and read-back at `0x3A` (`0x0B → 0x0A → 0x0B`) | Observed | +| Stored image `0x0000-0x0FFF` read byte by byte | Observed | +| Rate field `0x14` write/read-back | Observed; effect on cadence not observed | +| DPI `0x12` effect | Not observed | +| Vendor Apply block sequence | Captured from the vendor app | + +## Not yet verified + +- The mapping from the `0x14` 2-bit field to 125/250/500/1000 Hz. +- The six-stage CPI table location. +- Button-map and lighting semantics beyond the frames listed here. + +## Devices + +The A825 is a chipset. Public A825 mice: + +- Sades Kaze (Instant A825) — tested. +- Ant Esports GM320 — public reverse-engineering project. +- AJAZZ NJ08. +- Kreo Harpy. +- Cybeart Ghost. + +## Sources + +- A825 datasheet V1.01, Instant Microelectronics. +- `SadesKaze(A825).[20241009].exe` (vendor application). +- `Instant A825 Mouse Reference Driver.[20250716]` (vendor reference build). +- `https://github.com/helllopratik/ant-gm320-linux-experimental`. +EOF +echo rewritten; wc -l mproto/docs/instant-a825.md \ No newline at end of file From dc627dd85e799dcd18eb3eae959bb0ff81ad0e2b Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:48:57 +0700 Subject: [PATCH 3/6] feat(instant): export the A825 module from the package root - Added the `instant` namespace to src/index.ts. - Listed @openmouse/protocol/instant in the README protocol table. --- README.md | 221 ++++++++++++++++++++++++++------------------------- src/index.ts | 101 +++++++++++------------ 2 files changed, 162 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index 0fcd87a..67e7e6b 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,111 @@ -# `@openmouse/protocol` - -Transport-independent gaming mouse protocol codecs used by OpenMouse. - -The package owns packet layouts, command constants, checksums, encoders, -decoders, protocol-specific value types, device catalogs, and the WebHID -drivers used by OpenMouse. Pure codec entry points do not depend on WebHID, so -browser, Node.js, and TypeScript projects can use them independently from the -optional driver layer. - -```ts -import { buildFinalmouseReport } from "@openmouse/protocol/finalmouse"; -import { encodeRazerRequest } from "@openmouse/protocol/razer"; -import { RAZER_PRODUCTS } from "@openmouse/protocol/razer-devices"; - -import { - createSupportedClient, - SUPPORTED_HID_FILTERS, -} from "@openmouse/protocol/drivers"; -``` - -## Development - -```sh -npm install -npm run check -``` - -The `prepare` script builds `dist` automatically when this package is installed -directly from Git. Codec sources are grouped by brand under `src/`; WebHID -drivers, discovery filters, the driver registry, and shared status types live -under `src/drivers/`. OpenMouse retains application orchestration and UI code. - -See [CONTRIBUTING.md](CONTRIBUTING.md) for protocol boundaries, hardware -evidence requirements, local OpenMouse integration, and the pull-request -checklist. - -## Protocol entry points - -| Brand | Import | -| --- | --- | -| AJAZZ | `@openmouse/protocol/ajazz` | -| ATK | `@openmouse/protocol/atk` | -| Corsair | `@openmouse/protocol/corsair` | -| Dareu | `@openmouse/protocol/dareu` | -| Delux M800 Mini / M600 Pro | `@openmouse/protocol/delux` | -| Endgame Gear OP1/XM2 8K | `@openmouse/protocol/endgame-gear-op1` | -| Endgame Gear XM1r/OP1/OP1 RGB | `@openmouse/protocol/endgame-gear-ot` | -| Endgame Gear wireless | `@openmouse/protocol/endgame-gear-we` | -| Fantech | `@openmouse/protocol/fantech` | -| Finalmouse | `@openmouse/protocol/finalmouse` | -| G-Wolves | `@openmouse/protocol/gwolves` | -| GearHub (AJAZZ / Attack Shark / Lingbao) | `@openmouse/protocol/gearhub` | -| Glorious | `@openmouse/protocol/glorious` | -| Glorious classic (Model O/D/I) | `@openmouse/protocol/glorious-classic` | -| Glorious core2 (O2/D2 Pro 4K/8K) | `@openmouse/protocol/glorious-core2` | -| Hitscan (Hyperlight web control / native Utility) | `@openmouse/protocol/hitscan` | -| HyperX | `@openmouse/protocol/hyperx` | -| Incott | `@openmouse/protocol/incott` | -| K-snake | `@openmouse/protocol/ksnake` | -| Keychron | `@openmouse/protocol/keychron` | -| Lamzu / CRDRAKO / Attack Shark / LunaFury | `@openmouse/protocol/lamzu` | -| Logitech | `@openmouse/protocol/logitech` | -| MCHOSE | `@openmouse/protocol/mchose` | -| Microsoft | `@openmouse/protocol/microsoft` | -| Motospeed | `@openmouse/protocol/motospeed` | -| moddoMOUSE | `@openmouse/protocol/moddo` | -| Ninjutso | `@openmouse/protocol/ninjutso` | -| Orbital | `@openmouse/protocol/orbital` | -| RAWM | `@openmouse/protocol/rawm` | -| Pulsar / GravaStar | `@openmouse/protocol/pulsar` | -| Razer legacy/current | `@openmouse/protocol/razer` | -| Rapoo VT9 Pro | `@openmouse/protocol/rapoo` | -| Razer V4 | `@openmouse/protocol/razer-v4` | -| Redragon (M612 / M724 / M690 PRO / M719RGB-PRO) | `@openmouse/protocol/redragon` | -| Ryunix | `@openmouse/protocol/ryunix` | -| Amkette XS series | `@openmouse/protocol/amkette` | -| SteelSeries Rival 3 (Gen 1) | `@openmouse/protocol/steelseries` | -| Teevolution | `@openmouse/protocol/teevolution` | -| VGN | `@openmouse/protocol/vgn` | -| WALLHACK | `@openmouse/protocol/wallhack` | -| WLMouse | `@openmouse/protocol/wlmouse` | -| Wooting | `@openmouse/protocol/wooting` | -| Zaunkoenig | `@openmouse/protocol/zaunkoenig` | - -An exported protocol means OpenMouse implements that wire format. It does not -claim every mouse from that brand works. When a catalog provides a `verified` -field, use it to distinguish hardware-tested support from USB recognition. - -LunaFury uses the shared Lamzu/CompX driver at `@openmouse/protocol/lamzu`. -LUNA33 firmware `0.0.26.0` has owner-confirmed cable/8K coverage; TYPE33 and -bottom-button behavior are not hardware-verified. See the -[support and testing notes](docs/lunafury-testing.md) for the verified scope. - -The Ninjutso catalog and packet layouts are derived from the JavaScript shipped -by the official NinjaForce WebHID panel. They have automated transport and -codec coverage, but are not marked as hardware-verified until tested on the -corresponding Sora V2/V3 and TEN-family devices. - -AJAZZ AJ179 PRO is supported by the GearHub driver, identified by device id -1851 rather than its shared receiver PID. USB, 2.4 GHz and Bluetooth settings -have been exercised on hardware. See [docs/ajazz-aj179-pro.md](docs/ajazz-aj179-pro.md) -for transport framing, verified writes and remaining limitations. This does -not claim support for other AJAZZ models or measured high-rate Bluetooth input. - -The SteelSeries Rival 3 Gen 1 codec and driver are derived from the public -rivalcfg project, corroborated against libratbag and OpenRGB. The device is -write-only — only the firmware version can be read back — and no entry is -marked hardware-verified yet. See -[docs/steelseries-testing.md](docs/steelseries-testing.md). +# `@openmouse/protocol` + +Transport-independent gaming mouse protocol codecs used by OpenMouse. + +The package owns packet layouts, command constants, checksums, encoders, +decoders, protocol-specific value types, device catalogs, and the WebHID +drivers used by OpenMouse. Pure codec entry points do not depend on WebHID, so +browser, Node.js, and TypeScript projects can use them independently from the +optional driver layer. + +```ts +import { buildFinalmouseReport } from "@openmouse/protocol/finalmouse"; +import { encodeRazerRequest } from "@openmouse/protocol/razer"; +import { RAZER_PRODUCTS } from "@openmouse/protocol/razer-devices"; + +import { + createSupportedClient, + SUPPORTED_HID_FILTERS, +} from "@openmouse/protocol/drivers"; +``` + +## Development + +```sh +npm install +npm run check +``` + +The `prepare` script builds `dist` automatically when this package is installed +directly from Git. Codec sources are grouped by brand under `src/`; WebHID +drivers, discovery filters, the driver registry, and shared status types live +under `src/drivers/`. OpenMouse retains application orchestration and UI code. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for protocol boundaries, hardware +evidence requirements, local OpenMouse integration, and the pull-request +checklist. + +## Protocol entry points + +| Brand | Import | +| --- | --- | +| AJAZZ | `@openmouse/protocol/ajazz` | +| ATK | `@openmouse/protocol/atk` | +| Corsair | `@openmouse/protocol/corsair` | +| Dareu | `@openmouse/protocol/dareu` | +| Delux M800 Mini / M600 Pro | `@openmouse/protocol/delux` | +| Endgame Gear OP1/XM2 8K | `@openmouse/protocol/endgame-gear-op1` | +| Endgame Gear XM1r/OP1/OP1 RGB | `@openmouse/protocol/endgame-gear-ot` | +| Endgame Gear wireless | `@openmouse/protocol/endgame-gear-we` | +| Fantech | `@openmouse/protocol/fantech` | +| Finalmouse | `@openmouse/protocol/finalmouse` | +| G-Wolves | `@openmouse/protocol/gwolves` | +| GearHub (AJAZZ / Attack Shark / Lingbao) | `@openmouse/protocol/gearhub` | +| Glorious | `@openmouse/protocol/glorious` | +| Glorious classic (Model O/D/I) | `@openmouse/protocol/glorious-classic` | +| Glorious core2 (O2/D2 Pro 4K/8K) | `@openmouse/protocol/glorious-core2` | +| Hitscan (Hyperlight web control / native Utility) | `@openmouse/protocol/hitscan` | +| HyperX | `@openmouse/protocol/hyperx` | +| Incott | `@openmouse/protocol/incott` | +| Instant A825 | `@openmouse/protocol/instant` | +| K-snake | `@openmouse/protocol/ksnake` | +| Keychron | `@openmouse/protocol/keychron` | +| Lamzu / CRDRAKO / Attack Shark / LunaFury | `@openmouse/protocol/lamzu` | +| Logitech | `@openmouse/protocol/logitech` | +| MCHOSE | `@openmouse/protocol/mchose` | +| Microsoft | `@openmouse/protocol/microsoft` | +| Motospeed | `@openmouse/protocol/motospeed` | +| moddoMOUSE | `@openmouse/protocol/moddo` | +| Ninjutso | `@openmouse/protocol/ninjutso` | +| Orbital | `@openmouse/protocol/orbital` | +| RAWM | `@openmouse/protocol/rawm` | +| Pulsar / GravaStar | `@openmouse/protocol/pulsar` | +| Razer legacy/current | `@openmouse/protocol/razer` | +| Rapoo VT9 Pro | `@openmouse/protocol/rapoo` | +| Razer V4 | `@openmouse/protocol/razer-v4` | +| Redragon (M612 / M724 / M690 PRO / M719RGB-PRO) | `@openmouse/protocol/redragon` | +| Ryunix | `@openmouse/protocol/ryunix` | +| Amkette XS series | `@openmouse/protocol/amkette` | +| SteelSeries Rival 3 (Gen 1) | `@openmouse/protocol/steelseries` | +| Teevolution | `@openmouse/protocol/teevolution` | +| VGN | `@openmouse/protocol/vgn` | +| WALLHACK | `@openmouse/protocol/wallhack` | +| WLMouse | `@openmouse/protocol/wlmouse` | +| Wooting | `@openmouse/protocol/wooting` | +| Zaunkoenig | `@openmouse/protocol/zaunkoenig` | + +An exported protocol means OpenMouse implements that wire format. It does not +claim every mouse from that brand works. When a catalog provides a `verified` +field, use it to distinguish hardware-tested support from USB recognition. + +LunaFury uses the shared Lamzu/CompX driver at `@openmouse/protocol/lamzu`. +LUNA33 firmware `0.0.26.0` has owner-confirmed cable/8K coverage; TYPE33 and +bottom-button behavior are not hardware-verified. See the +[support and testing notes](docs/lunafury-testing.md) for the verified scope. + +The Ninjutso catalog and packet layouts are derived from the JavaScript shipped +by the official NinjaForce WebHID panel. They have automated transport and +codec coverage, but are not marked as hardware-verified until tested on the +corresponding Sora V2/V3 and TEN-family devices. + +AJAZZ AJ179 PRO is supported by the GearHub driver, identified by device id +1851 rather than its shared receiver PID. USB, 2.4 GHz and Bluetooth settings +have been exercised on hardware. See [docs/ajazz-aj179-pro.md](docs/ajazz-aj179-pro.md) +for transport framing, verified writes and remaining limitations. This does +not claim support for other AJAZZ models or measured high-rate Bluetooth input. + +The SteelSeries Rival 3 Gen 1 codec and driver are derived from the public +rivalcfg project, corroborated against libratbag and OpenRGB. The device is +write-only — only the firmware version can be read back — and no entry is +marked hardware-verified yet. See +[docs/steelseries-testing.md](docs/steelseries-testing.md). diff --git a/src/index.ts b/src/index.ts index ce0629f..c257ff1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,50 +1,51 @@ -export * as atk from "./atk/index.js"; -export * as aula from "./aula/index.js"; -export * as hitscan from "./hitscan/index.js"; -export * as bitmouse from "./bitmouse/index.js"; -export * as endgameGearWe from "./endgame-gear/wireless.js"; -export * as endgameGearOp1 from "./endgame-gear/op1.js"; -export * as endgameGearOt from "./endgame-gear/ot.js"; -export * as finalmouse from "./finalmouse/index.js"; -export * as keychron from "./keychron/index.js"; -export * as lamzu from "./lamzu/index.js"; -export * as logitech from "./logitech/index.js"; -export * as microsoft from "./microsoft/index.js"; -export * as moddo from "./moddo/index.js"; -export * as ninjutso from "./ninjutso/index.js"; -export * as orbital from "./orbital/index.js"; -export * as pulsar from "./pulsar/index.js"; -export * as razer from "./razer/index.js"; -export * as razerDevices from "./razer/devices.js"; -export * as razerV4 from "./razer/v4.js"; -export * as steelseries from "./steelseries/index.js"; -export * as teevolution from "./teevolution/index.js"; -export * as vgn from "./vgn/index.js"; -export * as wlmouse from "./wlmouse/index.js"; -export * as zaunkoenig from "./zaunkoenig/index.js"; -export * as corsair from "./corsair/index.js"; -export * as dareu from "./dareu/index.js"; -export * as gwolves from "./gwolves/index.js"; -export * as glorious from "./glorious/index.js"; -export * as gloriousCore2 from "./glorious-core2/index.js"; -export * as gloriousSinowealth from "./glorious-sinowealth/index.js"; -export * as ksnake from "./ksnake/index.js"; -export * as hyperx from "./hyperx/index.js"; -export * as valkyrie from "./valkyrie/index.js"; -export * as vaxee from "./vaxee/index.js"; -export * as incott from "./incott/index.js"; -export * as ryunix from "./ryunix/index.js"; -export * as amkette from "./amkette/index.js"; -export * as redragon from "./redragon/index.js"; -export * as delux from "./delux/index.js"; -export * as bytech from "./bytech/index.js"; -export * as motospeed from "./motospeed/index.js"; -export * as rapoo from "./rapoo/index.js"; -export * as fater from "./fater/index.js"; -export * as thermaltake from "./thermaltake/index.js"; -export * as coolermaster from "./coolermaster/index.js"; -export * as redgear from "./redgear/index.ts"; -export * as ajazz from "./ajazz/index.js"; -export * as scyrox from "./scyrox/index.js"; -export * as roccat from "./roccat/index.js"; -export * as ajazzAj200p from "./ajazz/aj200p.js"; +export * as atk from "./atk/index.js"; +export * as aula from "./aula/index.js"; +export * as hitscan from "./hitscan/index.js"; +export * as bitmouse from "./bitmouse/index.js"; +export * as endgameGearWe from "./endgame-gear/wireless.js"; +export * as endgameGearOp1 from "./endgame-gear/op1.js"; +export * as endgameGearOt from "./endgame-gear/ot.js"; +export * as finalmouse from "./finalmouse/index.js"; +export * as keychron from "./keychron/index.js"; +export * as lamzu from "./lamzu/index.js"; +export * as logitech from "./logitech/index.js"; +export * as microsoft from "./microsoft/index.js"; +export * as moddo from "./moddo/index.js"; +export * as ninjutso from "./ninjutso/index.js"; +export * as orbital from "./orbital/index.js"; +export * as pulsar from "./pulsar/index.js"; +export * as razer from "./razer/index.js"; +export * as razerDevices from "./razer/devices.js"; +export * as razerV4 from "./razer/v4.js"; +export * as steelseries from "./steelseries/index.js"; +export * as teevolution from "./teevolution/index.js"; +export * as vgn from "./vgn/index.js"; +export * as wlmouse from "./wlmouse/index.js"; +export * as zaunkoenig from "./zaunkoenig/index.js"; +export * as corsair from "./corsair/index.js"; +export * as dareu from "./dareu/index.js"; +export * as gwolves from "./gwolves/index.js"; +export * as glorious from "./glorious/index.js"; +export * as gloriousCore2 from "./glorious-core2/index.js"; +export * as gloriousSinowealth from "./glorious-sinowealth/index.js"; +export * as ksnake from "./ksnake/index.js"; +export * as hyperx from "./hyperx/index.js"; +export * as valkyrie from "./valkyrie/index.js"; +export * as vaxee from "./vaxee/index.js"; +export * as incott from "./incott/index.js"; +export * as instant from "./instant/index.js"; +export * as ryunix from "./ryunix/index.js"; +export * as amkette from "./amkette/index.js"; +export * as redragon from "./redragon/index.js"; +export * as delux from "./delux/index.js"; +export * as bytech from "./bytech/index.js"; +export * as motospeed from "./motospeed/index.js"; +export * as rapoo from "./rapoo/index.js"; +export * as fater from "./fater/index.js"; +export * as thermaltake from "./thermaltake/index.js"; +export * as coolermaster from "./coolermaster/index.js"; +export * as redgear from "./redgear/index.ts"; +export * as ajazz from "./ajazz/index.js"; +export * as scyrox from "./scyrox/index.js"; +export * as roccat from "./roccat/index.js"; +export * as ajazzAj200p from "./ajazz/aj200p.js"; From 5ce514a9c237b8968dce952893b712591cdeb7c7 Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:49:47 +0700 Subject: [PATCH 4/6] style(instant): use LF line endings - Normalized the A825 protocol, driver, function map, README entry and root export to LF as required by CONTRIBUTING. --- README.md | 222 +++++------ docs/devdock-functions.md | 196 ++++----- src/drivers/instant/a825-hid.ts | 496 +++++++++++------------ src/index.ts | 102 ++--- src/instant/protocol.ts | 678 ++++++++++++++++---------------- 5 files changed, 847 insertions(+), 847 deletions(-) diff --git a/README.md b/README.md index 67e7e6b..ff70d4a 100644 --- a/README.md +++ b/README.md @@ -1,111 +1,111 @@ -# `@openmouse/protocol` - -Transport-independent gaming mouse protocol codecs used by OpenMouse. - -The package owns packet layouts, command constants, checksums, encoders, -decoders, protocol-specific value types, device catalogs, and the WebHID -drivers used by OpenMouse. Pure codec entry points do not depend on WebHID, so -browser, Node.js, and TypeScript projects can use them independently from the -optional driver layer. - -```ts -import { buildFinalmouseReport } from "@openmouse/protocol/finalmouse"; -import { encodeRazerRequest } from "@openmouse/protocol/razer"; -import { RAZER_PRODUCTS } from "@openmouse/protocol/razer-devices"; - -import { - createSupportedClient, - SUPPORTED_HID_FILTERS, -} from "@openmouse/protocol/drivers"; -``` - -## Development - -```sh -npm install -npm run check -``` - -The `prepare` script builds `dist` automatically when this package is installed -directly from Git. Codec sources are grouped by brand under `src/`; WebHID -drivers, discovery filters, the driver registry, and shared status types live -under `src/drivers/`. OpenMouse retains application orchestration and UI code. - -See [CONTRIBUTING.md](CONTRIBUTING.md) for protocol boundaries, hardware -evidence requirements, local OpenMouse integration, and the pull-request -checklist. - -## Protocol entry points - -| Brand | Import | -| --- | --- | -| AJAZZ | `@openmouse/protocol/ajazz` | -| ATK | `@openmouse/protocol/atk` | -| Corsair | `@openmouse/protocol/corsair` | -| Dareu | `@openmouse/protocol/dareu` | -| Delux M800 Mini / M600 Pro | `@openmouse/protocol/delux` | -| Endgame Gear OP1/XM2 8K | `@openmouse/protocol/endgame-gear-op1` | -| Endgame Gear XM1r/OP1/OP1 RGB | `@openmouse/protocol/endgame-gear-ot` | -| Endgame Gear wireless | `@openmouse/protocol/endgame-gear-we` | -| Fantech | `@openmouse/protocol/fantech` | -| Finalmouse | `@openmouse/protocol/finalmouse` | -| G-Wolves | `@openmouse/protocol/gwolves` | -| GearHub (AJAZZ / Attack Shark / Lingbao) | `@openmouse/protocol/gearhub` | -| Glorious | `@openmouse/protocol/glorious` | -| Glorious classic (Model O/D/I) | `@openmouse/protocol/glorious-classic` | -| Glorious core2 (O2/D2 Pro 4K/8K) | `@openmouse/protocol/glorious-core2` | -| Hitscan (Hyperlight web control / native Utility) | `@openmouse/protocol/hitscan` | -| HyperX | `@openmouse/protocol/hyperx` | -| Incott | `@openmouse/protocol/incott` | -| Instant A825 | `@openmouse/protocol/instant` | -| K-snake | `@openmouse/protocol/ksnake` | -| Keychron | `@openmouse/protocol/keychron` | -| Lamzu / CRDRAKO / Attack Shark / LunaFury | `@openmouse/protocol/lamzu` | -| Logitech | `@openmouse/protocol/logitech` | -| MCHOSE | `@openmouse/protocol/mchose` | -| Microsoft | `@openmouse/protocol/microsoft` | -| Motospeed | `@openmouse/protocol/motospeed` | -| moddoMOUSE | `@openmouse/protocol/moddo` | -| Ninjutso | `@openmouse/protocol/ninjutso` | -| Orbital | `@openmouse/protocol/orbital` | -| RAWM | `@openmouse/protocol/rawm` | -| Pulsar / GravaStar | `@openmouse/protocol/pulsar` | -| Razer legacy/current | `@openmouse/protocol/razer` | -| Rapoo VT9 Pro | `@openmouse/protocol/rapoo` | -| Razer V4 | `@openmouse/protocol/razer-v4` | -| Redragon (M612 / M724 / M690 PRO / M719RGB-PRO) | `@openmouse/protocol/redragon` | -| Ryunix | `@openmouse/protocol/ryunix` | -| Amkette XS series | `@openmouse/protocol/amkette` | -| SteelSeries Rival 3 (Gen 1) | `@openmouse/protocol/steelseries` | -| Teevolution | `@openmouse/protocol/teevolution` | -| VGN | `@openmouse/protocol/vgn` | -| WALLHACK | `@openmouse/protocol/wallhack` | -| WLMouse | `@openmouse/protocol/wlmouse` | -| Wooting | `@openmouse/protocol/wooting` | -| Zaunkoenig | `@openmouse/protocol/zaunkoenig` | - -An exported protocol means OpenMouse implements that wire format. It does not -claim every mouse from that brand works. When a catalog provides a `verified` -field, use it to distinguish hardware-tested support from USB recognition. - -LunaFury uses the shared Lamzu/CompX driver at `@openmouse/protocol/lamzu`. -LUNA33 firmware `0.0.26.0` has owner-confirmed cable/8K coverage; TYPE33 and -bottom-button behavior are not hardware-verified. See the -[support and testing notes](docs/lunafury-testing.md) for the verified scope. - -The Ninjutso catalog and packet layouts are derived from the JavaScript shipped -by the official NinjaForce WebHID panel. They have automated transport and -codec coverage, but are not marked as hardware-verified until tested on the -corresponding Sora V2/V3 and TEN-family devices. - -AJAZZ AJ179 PRO is supported by the GearHub driver, identified by device id -1851 rather than its shared receiver PID. USB, 2.4 GHz and Bluetooth settings -have been exercised on hardware. See [docs/ajazz-aj179-pro.md](docs/ajazz-aj179-pro.md) -for transport framing, verified writes and remaining limitations. This does -not claim support for other AJAZZ models or measured high-rate Bluetooth input. - -The SteelSeries Rival 3 Gen 1 codec and driver are derived from the public -rivalcfg project, corroborated against libratbag and OpenRGB. The device is -write-only — only the firmware version can be read back — and no entry is -marked hardware-verified yet. See -[docs/steelseries-testing.md](docs/steelseries-testing.md). +# `@openmouse/protocol` + +Transport-independent gaming mouse protocol codecs used by OpenMouse. + +The package owns packet layouts, command constants, checksums, encoders, +decoders, protocol-specific value types, device catalogs, and the WebHID +drivers used by OpenMouse. Pure codec entry points do not depend on WebHID, so +browser, Node.js, and TypeScript projects can use them independently from the +optional driver layer. + +```ts +import { buildFinalmouseReport } from "@openmouse/protocol/finalmouse"; +import { encodeRazerRequest } from "@openmouse/protocol/razer"; +import { RAZER_PRODUCTS } from "@openmouse/protocol/razer-devices"; + +import { + createSupportedClient, + SUPPORTED_HID_FILTERS, +} from "@openmouse/protocol/drivers"; +``` + +## Development + +```sh +npm install +npm run check +``` + +The `prepare` script builds `dist` automatically when this package is installed +directly from Git. Codec sources are grouped by brand under `src/`; WebHID +drivers, discovery filters, the driver registry, and shared status types live +under `src/drivers/`. OpenMouse retains application orchestration and UI code. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for protocol boundaries, hardware +evidence requirements, local OpenMouse integration, and the pull-request +checklist. + +## Protocol entry points + +| Brand | Import | +| --- | --- | +| AJAZZ | `@openmouse/protocol/ajazz` | +| ATK | `@openmouse/protocol/atk` | +| Corsair | `@openmouse/protocol/corsair` | +| Dareu | `@openmouse/protocol/dareu` | +| Delux M800 Mini / M600 Pro | `@openmouse/protocol/delux` | +| Endgame Gear OP1/XM2 8K | `@openmouse/protocol/endgame-gear-op1` | +| Endgame Gear XM1r/OP1/OP1 RGB | `@openmouse/protocol/endgame-gear-ot` | +| Endgame Gear wireless | `@openmouse/protocol/endgame-gear-we` | +| Fantech | `@openmouse/protocol/fantech` | +| Finalmouse | `@openmouse/protocol/finalmouse` | +| G-Wolves | `@openmouse/protocol/gwolves` | +| GearHub (AJAZZ / Attack Shark / Lingbao) | `@openmouse/protocol/gearhub` | +| Glorious | `@openmouse/protocol/glorious` | +| Glorious classic (Model O/D/I) | `@openmouse/protocol/glorious-classic` | +| Glorious core2 (O2/D2 Pro 4K/8K) | `@openmouse/protocol/glorious-core2` | +| Hitscan (Hyperlight web control / native Utility) | `@openmouse/protocol/hitscan` | +| HyperX | `@openmouse/protocol/hyperx` | +| Incott | `@openmouse/protocol/incott` | +| Instant A825 | `@openmouse/protocol/instant` | +| K-snake | `@openmouse/protocol/ksnake` | +| Keychron | `@openmouse/protocol/keychron` | +| Lamzu / CRDRAKO / Attack Shark / LunaFury | `@openmouse/protocol/lamzu` | +| Logitech | `@openmouse/protocol/logitech` | +| MCHOSE | `@openmouse/protocol/mchose` | +| Microsoft | `@openmouse/protocol/microsoft` | +| Motospeed | `@openmouse/protocol/motospeed` | +| moddoMOUSE | `@openmouse/protocol/moddo` | +| Ninjutso | `@openmouse/protocol/ninjutso` | +| Orbital | `@openmouse/protocol/orbital` | +| RAWM | `@openmouse/protocol/rawm` | +| Pulsar / GravaStar | `@openmouse/protocol/pulsar` | +| Razer legacy/current | `@openmouse/protocol/razer` | +| Rapoo VT9 Pro | `@openmouse/protocol/rapoo` | +| Razer V4 | `@openmouse/protocol/razer-v4` | +| Redragon (M612 / M724 / M690 PRO / M719RGB-PRO) | `@openmouse/protocol/redragon` | +| Ryunix | `@openmouse/protocol/ryunix` | +| Amkette XS series | `@openmouse/protocol/amkette` | +| SteelSeries Rival 3 (Gen 1) | `@openmouse/protocol/steelseries` | +| Teevolution | `@openmouse/protocol/teevolution` | +| VGN | `@openmouse/protocol/vgn` | +| WALLHACK | `@openmouse/protocol/wallhack` | +| WLMouse | `@openmouse/protocol/wlmouse` | +| Wooting | `@openmouse/protocol/wooting` | +| Zaunkoenig | `@openmouse/protocol/zaunkoenig` | + +An exported protocol means OpenMouse implements that wire format. It does not +claim every mouse from that brand works. When a catalog provides a `verified` +field, use it to distinguish hardware-tested support from USB recognition. + +LunaFury uses the shared Lamzu/CompX driver at `@openmouse/protocol/lamzu`. +LUNA33 firmware `0.0.26.0` has owner-confirmed cable/8K coverage; TYPE33 and +bottom-button behavior are not hardware-verified. See the +[support and testing notes](docs/lunafury-testing.md) for the verified scope. + +The Ninjutso catalog and packet layouts are derived from the JavaScript shipped +by the official NinjaForce WebHID panel. They have automated transport and +codec coverage, but are not marked as hardware-verified until tested on the +corresponding Sora V2/V3 and TEN-family devices. + +AJAZZ AJ179 PRO is supported by the GearHub driver, identified by device id +1851 rather than its shared receiver PID. USB, 2.4 GHz and Bluetooth settings +have been exercised on hardware. See [docs/ajazz-aj179-pro.md](docs/ajazz-aj179-pro.md) +for transport framing, verified writes and remaining limitations. This does +not claim support for other AJAZZ models or measured high-rate Bluetooth input. + +The SteelSeries Rival 3 Gen 1 codec and driver are derived from the public +rivalcfg project, corroborated against libratbag and OpenRGB. The device is +write-only — only the firmware version can be read back — and no entry is +marked hardware-verified yet. See +[docs/steelseries-testing.md](docs/steelseries-testing.md). diff --git a/docs/devdock-functions.md b/docs/devdock-functions.md index 752a4d5..f2a5241 100644 --- a/docs/devdock-functions.md +++ b/docs/devdock-functions.md @@ -1,98 +1,98 @@ -# DevDock function map (Sades Kaze A825) - -Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from -`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. - -The analysis database used the names below; the addresses are the evidence. - -| Address | Name | Role | -| --- | --- | --- | -| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | -| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | -| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | -| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | -| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` packs `byte[0x8104] & 3` above three flags; writing it did not change the measured report cadence. | -| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | -| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | -| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | -| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | -| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | -| `0x486FA0` | apply state collector | Collect UI state into the device object. | -| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | -| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | -| `0x460A60` | `MacroSenderThread` | Macro playback thread. | -| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | -| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | -| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | - -## Block write - -`A825_BlockWrite(this, handle, address, data, length)`: - -``` -07 18 03 -``` - -one frame per byte, then: - -``` -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Addresses are little-endian. The wait between the finish and commit frames is -12 ms. - -## Read - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → feature report byte 1 -07 18 00 00 00 00 -``` - -## Block mode - -`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then -`07 18 00 00 00 00 00 00`. - -## DPI frames - -`A825_LiveDpiAndButtons`: - -``` -07 12 mode 0 -07 12 other modes -07 11 -07 09 × 4 -``` - -The four `09` frames use: - -``` -byte2 = ((map >> 4) << 6) + profile -byte3 = (map << 4) + 8 + index -byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 -``` - -where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the -flags are `byte[0x79C..0x79F]`. - -## Configuration image - -`A825_BuildConfigImage` collects records with numeric ids: - -| Id | Value | -| --- | --- | -| 0 | `0x5A` | -| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | -| 2 | `0xA5` | -| 3 | `byte[0x8068]` | -| 4 | `byte[0x8068] >> 8` | -| 5 | `byte[0x8064]` | -| 6 | `byte[0x8064] >> 8` | -| 7 | `byte[0x802C]` (key map byte 0) | -| 8+ | lighting and stage fields | - -The record-to-image-address mapping is not resolved. +# DevDock function map (Sades Kaze A825) + +Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from +`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. + +The analysis database used the names below; the addresses are the evidence. + +| Address | Name | Role | +| --- | --- | --- | +| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | +| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | +| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | +| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | +| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` packs `byte[0x8104] & 3` above three flags; writing it did not change the measured report cadence. | +| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | +| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | +| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | +| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | +| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | +| `0x486FA0` | apply state collector | Collect UI state into the device object. | +| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | +| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | +| `0x460A60` | `MacroSenderThread` | Macro playback thread. | +| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | +| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | +| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | + +## Block write + +`A825_BlockWrite(this, handle, address, data, length)`: + +``` +07 18 03 +``` + +one frame per byte, then: + +``` +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Addresses are little-endian. The wait between the finish and commit frames is +12 ms. + +## Read + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → feature report byte 1 +07 18 00 00 00 00 +``` + +## Block mode + +`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then +`07 18 00 00 00 00 00 00`. + +## DPI frames + +`A825_LiveDpiAndButtons`: + +``` +07 12 mode 0 +07 12 other modes +07 11 +07 09 × 4 +``` + +The four `09` frames use: + +``` +byte2 = ((map >> 4) << 6) + profile +byte3 = (map << 4) + 8 + index +byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 +``` + +where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the +flags are `byte[0x79C..0x79F]`. + +## Configuration image + +`A825_BuildConfigImage` collects records with numeric ids: + +| Id | Value | +| --- | --- | +| 0 | `0x5A` | +| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | +| 2 | `0xA5` | +| 3 | `byte[0x8068]` | +| 4 | `byte[0x8068] >> 8` | +| 5 | `byte[0x8064]` | +| 6 | `byte[0x8064] >> 8` | +| 7 | `byte[0x802C]` (key map byte 0) | +| 8+ | lighting and stage fields | + +The record-to-image-address mapping is not resolved. diff --git a/src/drivers/instant/a825-hid.ts b/src/drivers/instant/a825-hid.ts index bf4d235..7a1cb46 100644 --- a/src/drivers/instant/a825-hid.ts +++ b/src/drivers/instant/a825-hid.ts @@ -1,248 +1,248 @@ -import type { MouseStatus } from "../mouse-types.ts"; -import { - decodeInstantConfig, - decodeInstantStatus, - instantBlockReadByteFrame, - instantBlockReadFrames, - instantFrame, - INSTANT_BLOCK, - INSTANT_COMMAND, - INSTANT_CONFIG_LENGTH, - INSTANT_DPI_GEARS, - INSTANT_POLLING_RATES, - INSTANT_PRODUCT_IDS, - INSTANT_REPORT_ID, - INSTANT_USAGE, - INSTANT_USAGE_PAGE, - INSTANT_VENDOR_ID, - instantDpiFrames, - type InstantConfigImage, -} from "@openmouse/protocol/instant"; - -function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { - return collections.some( - (collection) => - (collection.usagePage === INSTANT_USAGE_PAGE && - collection.usage === INSTANT_USAGE && - collection.featureReports.some( - (report) => report.reportId === INSTANT_REPORT_ID, - )) || - hasConfigCollection(collection.children), - ); -} - -function statusBytes(view: DataView, reportId: number): Uint8Array { - const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); - return bytes[0] === reportId ? bytes.slice(1) : bytes.slice(); -} - -/** - * Sades Kaze / Instant A825 control client. - * - * Reads the 32-byte status block and the stored configuration image. Settings - * framing is implemented in `@openmouse/protocol/instant`. The DPI command has - * no observable read-back on this firmware and the polling-rate field is not yet - * mapped, so the panel shows this device as read-only. - */ -export class InstantA825HidClient { - readonly device: HIDDevice; - private config: InstantConfigImage | null = null; - private status: Uint8Array | null = null; - private queue: Promise = Promise.resolve(); - private generation = 0; - private opening: Promise | null = null; - - constructor(device: HIDDevice) { - this.device = device; - } - - static isSupported(device: HIDDevice): boolean { - return ( - device.vendorId === INSTANT_VENDOR_ID && - INSTANT_PRODUCT_IDS.has(device.productId) && - hasConfigCollection(device.collections) - ); - } - - getDpiOptions(): number[] { - return [...INSTANT_DPI_GEARS]; - } - - getPollingRateOptions(): number[] { - return [...INSTANT_POLLING_RATES]; - } - - async open(): Promise { - if (!InstantA825HidClient.isSupported(this.device)) { - throw new Error("Unsupported A825 HID interface"); - } - if (this.opening) return this.opening; - if (this.device.opened) return; - const generation = this.generation; - const task = (async () => { - await this.device.open(); - if (generation !== this.generation) { - if (this.device.opened) await this.device.close(); - throw new Error("A825 disconnected while opening"); - } - })(); - this.opening = task; - try { - await task; - } finally { - if (this.opening === task) this.opening = null; - } - } - - async close(): Promise { - this.generation += 1; - this.config = null; - this.status = null; - this.queue = Promise.resolve(); - await this.opening?.catch(() => undefined); - if (this.device.opened) await this.device.close(); - } - - /** Raw 32-byte status report, including report ID 7. */ - getRawStatusReport(): Uint8Array | null { - return this.status?.slice() ?? null; - } - - /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ - getConfigImage(): InstantConfigImage | null { - return this.config - ? { - ...this.config, - bytes: this.config.bytes.slice(), - } - : null; - } - - private serialize(action: () => Promise): Promise { - const generation = this.generation; - const task = this.queue.then(() => { - if (generation !== this.generation) { - throw new Error("A825 disconnected before queued transfer"); - } - return action(); - }); - this.queue = task.then( - () => undefined, - () => undefined, - ); - return task; - } - - private async send(frame: Uint8Array): Promise { - await this.device.sendFeatureReport( - INSTANT_REPORT_ID, - frame.slice(1).buffer, - ); - } - - private async readStatusReport(): Promise { - const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); - return statusBytes(view, INSTANT_REPORT_ID); - } - - /** Read one byte from the configuration image, using the vendor read path. */ - private async readByte(address: number): Promise { - const setup = instantBlockReadFrames(address, 1); - for (const frame of setup) await this.send(frame); - await this.send(instantBlockReadByteFrame(address, 0, 1)); - const report = await this.readStatusReport(); - // The vendor closes the read window after every byte. - await this.send( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - address & 0xff, - (address >>> 8) & 0xff, - 0, - 0, - ]), - ); - const full = new Uint8Array(report.length + 1); - full[0] = INSTANT_REPORT_ID; - full.set(report, 1); - const value = full.length > 1 ? full[1] : null; - if (value == null) throw new Error("A825 config read returned no data"); - return value; - } - - /** - * Read the stored configuration image. This is 0x300 one-byte reads and is - * intentionally explicit: read a small range when only a few bytes matter. - */ - async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { - if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { - throw new RangeError(`Invalid A825 config length: ${length}`); - } - return this.serialize(async () => { - await this.open(); - const bytes = new Uint8Array(INSTANT_CONFIG_LENGTH); - for (let address = 0; address < length; address += 1) { - bytes[address] = await this.readByte(address); - } - this.config = decodeInstantConfig(bytes); - return this.getConfigImage()!; - }); - } - - async readStatus(): Promise { - return this.serialize(async () => { - const generation = this.generation; - await this.open(); - if (generation !== this.generation) { - throw new Error("A825 disconnected while opening"); - } - const report = await this.readStatusReport(); - this.status = new Uint8Array(report.length + 1); - this.status[0] = INSTANT_REPORT_ID; - this.status.set(report, 1); - const decoded = decodeInstantStatus(this.status); - - return { - brand: "Sades", - name: this.device.productName || "Sades Kaze", - ui: { - family: "sades-a825", - settingsReady: false, - valuesVerified: decoded !== null, - pollingReadOnly: true, - hideProcessingCard: true, - hideSignalCard: true, - hideSleepCard: true, - defaultDisplayName: "Sades Kaze", - statusNote: - "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", - }, - batteryPercent: null, - batteryState: "Unknown", - dpi: 0, - pollingRateHz: 0, - supportedPollingRates: [...INSTANT_POLLING_RATES], - activeProfile: null, - connectionType: "Wired", - connectionDetail: "USB", - liftOffDistance: null, - firmware: - decoded != null - ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] - : [], - }; - }); - } - - /** - * Send the vendor's live DPI command. Kept for protocol tooling; the panel - * does not expose it because this firmware gives no read-back for the value. - */ - async setLiveDpi(dpi: number, mode = 0): Promise { - return this.serialize(async () => { - await this.open(); - for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); - return dpi; - }); - } -} +import type { MouseStatus } from "../mouse-types.ts"; +import { + decodeInstantConfig, + decodeInstantStatus, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantFrame, + INSTANT_BLOCK, + INSTANT_COMMAND, + INSTANT_CONFIG_LENGTH, + INSTANT_DPI_GEARS, + INSTANT_POLLING_RATES, + INSTANT_PRODUCT_IDS, + INSTANT_REPORT_ID, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, + instantDpiFrames, + type InstantConfigImage, +} from "@openmouse/protocol/instant"; + +function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { + return collections.some( + (collection) => + (collection.usagePage === INSTANT_USAGE_PAGE && + collection.usage === INSTANT_USAGE && + collection.featureReports.some( + (report) => report.reportId === INSTANT_REPORT_ID, + )) || + hasConfigCollection(collection.children), + ); +} + +function statusBytes(view: DataView, reportId: number): Uint8Array { + const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); + return bytes[0] === reportId ? bytes.slice(1) : bytes.slice(); +} + +/** + * Sades Kaze / Instant A825 control client. + * + * Reads the 32-byte status block and the stored configuration image. Settings + * framing is implemented in `@openmouse/protocol/instant`. The DPI command has + * no observable read-back on this firmware and the polling-rate field is not yet + * mapped, so the panel shows this device as read-only. + */ +export class InstantA825HidClient { + readonly device: HIDDevice; + private config: InstantConfigImage | null = null; + private status: Uint8Array | null = null; + private queue: Promise = Promise.resolve(); + private generation = 0; + private opening: Promise | null = null; + + constructor(device: HIDDevice) { + this.device = device; + } + + static isSupported(device: HIDDevice): boolean { + return ( + device.vendorId === INSTANT_VENDOR_ID && + INSTANT_PRODUCT_IDS.has(device.productId) && + hasConfigCollection(device.collections) + ); + } + + getDpiOptions(): number[] { + return [...INSTANT_DPI_GEARS]; + } + + getPollingRateOptions(): number[] { + return [...INSTANT_POLLING_RATES]; + } + + async open(): Promise { + if (!InstantA825HidClient.isSupported(this.device)) { + throw new Error("Unsupported A825 HID interface"); + } + if (this.opening) return this.opening; + if (this.device.opened) return; + const generation = this.generation; + const task = (async () => { + await this.device.open(); + if (generation !== this.generation) { + if (this.device.opened) await this.device.close(); + throw new Error("A825 disconnected while opening"); + } + })(); + this.opening = task; + try { + await task; + } finally { + if (this.opening === task) this.opening = null; + } + } + + async close(): Promise { + this.generation += 1; + this.config = null; + this.status = null; + this.queue = Promise.resolve(); + await this.opening?.catch(() => undefined); + if (this.device.opened) await this.device.close(); + } + + /** Raw 32-byte status report, including report ID 7. */ + getRawStatusReport(): Uint8Array | null { + return this.status?.slice() ?? null; + } + + /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ + getConfigImage(): InstantConfigImage | null { + return this.config + ? { + ...this.config, + bytes: this.config.bytes.slice(), + } + : null; + } + + private serialize(action: () => Promise): Promise { + const generation = this.generation; + const task = this.queue.then(() => { + if (generation !== this.generation) { + throw new Error("A825 disconnected before queued transfer"); + } + return action(); + }); + this.queue = task.then( + () => undefined, + () => undefined, + ); + return task; + } + + private async send(frame: Uint8Array): Promise { + await this.device.sendFeatureReport( + INSTANT_REPORT_ID, + frame.slice(1).buffer, + ); + } + + private async readStatusReport(): Promise { + const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); + return statusBytes(view, INSTANT_REPORT_ID); + } + + /** Read one byte from the configuration image, using the vendor read path. */ + private async readByte(address: number): Promise { + const setup = instantBlockReadFrames(address, 1); + for (const frame of setup) await this.send(frame); + await this.send(instantBlockReadByteFrame(address, 0, 1)); + const report = await this.readStatusReport(); + // The vendor closes the read window after every byte. + await this.send( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + address & 0xff, + (address >>> 8) & 0xff, + 0, + 0, + ]), + ); + const full = new Uint8Array(report.length + 1); + full[0] = INSTANT_REPORT_ID; + full.set(report, 1); + const value = full.length > 1 ? full[1] : null; + if (value == null) throw new Error("A825 config read returned no data"); + return value; + } + + /** + * Read the stored configuration image. This is 0x300 one-byte reads and is + * intentionally explicit: read a small range when only a few bytes matter. + */ + async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { + if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { + throw new RangeError(`Invalid A825 config length: ${length}`); + } + return this.serialize(async () => { + await this.open(); + const bytes = new Uint8Array(INSTANT_CONFIG_LENGTH); + for (let address = 0; address < length; address += 1) { + bytes[address] = await this.readByte(address); + } + this.config = decodeInstantConfig(bytes); + return this.getConfigImage()!; + }); + } + + async readStatus(): Promise { + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const report = await this.readStatusReport(); + this.status = new Uint8Array(report.length + 1); + this.status[0] = INSTANT_REPORT_ID; + this.status.set(report, 1); + const decoded = decodeInstantStatus(this.status); + + return { + brand: "Sades", + name: this.device.productName || "Sades Kaze", + ui: { + family: "sades-a825", + settingsReady: false, + valuesVerified: decoded !== null, + pollingReadOnly: true, + hideProcessingCard: true, + hideSignalCard: true, + hideSleepCard: true, + defaultDisplayName: "Sades Kaze", + statusNote: + "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", + }, + batteryPercent: null, + batteryState: "Unknown", + dpi: 0, + pollingRateHz: 0, + supportedPollingRates: [...INSTANT_POLLING_RATES], + activeProfile: null, + connectionType: "Wired", + connectionDetail: "USB", + liftOffDistance: null, + firmware: + decoded != null + ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] + : [], + }; + }); + } + + /** + * Send the vendor's live DPI command. Kept for protocol tooling; the panel + * does not expose it because this firmware gives no read-back for the value. + */ + async setLiveDpi(dpi: number, mode = 0): Promise { + return this.serialize(async () => { + await this.open(); + for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); + return dpi; + }); + } +} diff --git a/src/index.ts b/src/index.ts index c257ff1..c7df9b1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,51 +1,51 @@ -export * as atk from "./atk/index.js"; -export * as aula from "./aula/index.js"; -export * as hitscan from "./hitscan/index.js"; -export * as bitmouse from "./bitmouse/index.js"; -export * as endgameGearWe from "./endgame-gear/wireless.js"; -export * as endgameGearOp1 from "./endgame-gear/op1.js"; -export * as endgameGearOt from "./endgame-gear/ot.js"; -export * as finalmouse from "./finalmouse/index.js"; -export * as keychron from "./keychron/index.js"; -export * as lamzu from "./lamzu/index.js"; -export * as logitech from "./logitech/index.js"; -export * as microsoft from "./microsoft/index.js"; -export * as moddo from "./moddo/index.js"; -export * as ninjutso from "./ninjutso/index.js"; -export * as orbital from "./orbital/index.js"; -export * as pulsar from "./pulsar/index.js"; -export * as razer from "./razer/index.js"; -export * as razerDevices from "./razer/devices.js"; -export * as razerV4 from "./razer/v4.js"; -export * as steelseries from "./steelseries/index.js"; -export * as teevolution from "./teevolution/index.js"; -export * as vgn from "./vgn/index.js"; -export * as wlmouse from "./wlmouse/index.js"; -export * as zaunkoenig from "./zaunkoenig/index.js"; -export * as corsair from "./corsair/index.js"; -export * as dareu from "./dareu/index.js"; -export * as gwolves from "./gwolves/index.js"; -export * as glorious from "./glorious/index.js"; -export * as gloriousCore2 from "./glorious-core2/index.js"; -export * as gloriousSinowealth from "./glorious-sinowealth/index.js"; -export * as ksnake from "./ksnake/index.js"; -export * as hyperx from "./hyperx/index.js"; -export * as valkyrie from "./valkyrie/index.js"; -export * as vaxee from "./vaxee/index.js"; -export * as incott from "./incott/index.js"; -export * as instant from "./instant/index.js"; -export * as ryunix from "./ryunix/index.js"; -export * as amkette from "./amkette/index.js"; -export * as redragon from "./redragon/index.js"; -export * as delux from "./delux/index.js"; -export * as bytech from "./bytech/index.js"; -export * as motospeed from "./motospeed/index.js"; -export * as rapoo from "./rapoo/index.js"; -export * as fater from "./fater/index.js"; -export * as thermaltake from "./thermaltake/index.js"; -export * as coolermaster from "./coolermaster/index.js"; -export * as redgear from "./redgear/index.ts"; -export * as ajazz from "./ajazz/index.js"; -export * as scyrox from "./scyrox/index.js"; -export * as roccat from "./roccat/index.js"; -export * as ajazzAj200p from "./ajazz/aj200p.js"; +export * as atk from "./atk/index.js"; +export * as aula from "./aula/index.js"; +export * as hitscan from "./hitscan/index.js"; +export * as bitmouse from "./bitmouse/index.js"; +export * as endgameGearWe from "./endgame-gear/wireless.js"; +export * as endgameGearOp1 from "./endgame-gear/op1.js"; +export * as endgameGearOt from "./endgame-gear/ot.js"; +export * as finalmouse from "./finalmouse/index.js"; +export * as keychron from "./keychron/index.js"; +export * as lamzu from "./lamzu/index.js"; +export * as logitech from "./logitech/index.js"; +export * as microsoft from "./microsoft/index.js"; +export * as moddo from "./moddo/index.js"; +export * as ninjutso from "./ninjutso/index.js"; +export * as orbital from "./orbital/index.js"; +export * as pulsar from "./pulsar/index.js"; +export * as razer from "./razer/index.js"; +export * as razerDevices from "./razer/devices.js"; +export * as razerV4 from "./razer/v4.js"; +export * as steelseries from "./steelseries/index.js"; +export * as teevolution from "./teevolution/index.js"; +export * as vgn from "./vgn/index.js"; +export * as wlmouse from "./wlmouse/index.js"; +export * as zaunkoenig from "./zaunkoenig/index.js"; +export * as corsair from "./corsair/index.js"; +export * as dareu from "./dareu/index.js"; +export * as gwolves from "./gwolves/index.js"; +export * as glorious from "./glorious/index.js"; +export * as gloriousCore2 from "./glorious-core2/index.js"; +export * as gloriousSinowealth from "./glorious-sinowealth/index.js"; +export * as ksnake from "./ksnake/index.js"; +export * as hyperx from "./hyperx/index.js"; +export * as valkyrie from "./valkyrie/index.js"; +export * as vaxee from "./vaxee/index.js"; +export * as incott from "./incott/index.js"; +export * as instant from "./instant/index.js"; +export * as ryunix from "./ryunix/index.js"; +export * as amkette from "./amkette/index.js"; +export * as redragon from "./redragon/index.js"; +export * as delux from "./delux/index.js"; +export * as bytech from "./bytech/index.js"; +export * as motospeed from "./motospeed/index.js"; +export * as rapoo from "./rapoo/index.js"; +export * as fater from "./fater/index.js"; +export * as thermaltake from "./thermaltake/index.js"; +export * as coolermaster from "./coolermaster/index.js"; +export * as redgear from "./redgear/index.ts"; +export * as ajazz from "./ajazz/index.js"; +export * as scyrox from "./scyrox/index.js"; +export * as roccat from "./roccat/index.js"; +export * as ajazzAj200p from "./ajazz/aj200p.js"; diff --git a/src/instant/protocol.ts b/src/instant/protocol.ts index dd28469..df5e954 100644 --- a/src/instant/protocol.ts +++ b/src/instant/protocol.ts @@ -1,339 +1,339 @@ -/** - * Instant Microelectronics A825 configuration protocol. - * - * Reverse-engineered from the vendor control app shipped for the Sades Kaze - * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` - * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a - * Sades Kaze on VID 0x30FA / PID 0x1440. - * - * Transport - * --------- - * The control collection is usage page 0xFF01, usage 1, on interface 1. Its - * only feature report is report ID 7. The vendor app and the device both use - * 8-byte feature reports: - * - * [0x07, command, a, b, c, d, e, f] - * - * The same report also carries a 32-byte status block that the device returns - * from a feature read; only the first eight bytes are used for command replies. - * - * Block access (command 0x18) - * --------------------------- - * The device exposes a 16-bit, little-endian addressed configuration memory. - * A block is written as one frame per byte, then finished and committed: - * - * 07 18 03 - * 07 18 09 00 00 - * 07 18 00 00 00 00 - * - * A byte is read by issuing the same address/length setup and then one frame - * per byte: - * - * 07 18 03 00 00 - * 07 18 00 00 00 00 - * 07 18 05 00 → reply byte 1 - * 07 18 00 00 00 00 - * - * Verified on hardware: writing the byte at 0x3A and reading it back returns - * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not - * the polling rate. The 0x0000-0x0FFF image is readable with - * `instantBlockReadFrames`. - * - * Direct commands - * --------------- - * The vendor app also writes a DPI value and a button map directly: - * - * 07 12 00 00 00 00 00 (mode 0) - * 07 12 ... (other modes) - * 07 11 00 ... commit - * 07 09 ... button map - * 07 17 ... 16-bit key/function code - * 07 13 ... lighting/mode - * - * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the - * 0x0F80 trailer). The direct commands above are read from the vendor code; - * sending 0x12 on the tested unit changed neither the stored image nor the - * status block. - */ - -export const INSTANT_VENDOR_ID = 0x30fa; - -/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ -export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ - 0x1440, 0x1e01, 0x7f7f, -]); - -export const INSTANT_USAGE_PAGE = 0xff01; -export const INSTANT_USAGE = 0x01; -export const INSTANT_INTERFACE = 1; - -export const INSTANT_REPORT_ID = 0x07; -export const INSTANT_FRAME_LENGTH = 8; -/** Status block returned by a feature read on report 7. */ -export const INSTANT_STATUS_LENGTH = 32; - -export const INSTANT_COMMAND = { - block: 0x18, - dpi: 0x12, - apply: 0x11, - buttonMap: 0x09, - keyCode: 0x17, - notice: 0x13, -} as const; - -export const INSTANT_BLOCK = { - write: 0x03, - read: 0x05, - finish: 0x09, - commit: 0x00, - mode: 0x10, -} as const; - -/** - * Configuration image addresses written by the vendor app's - * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes - * between blocks are untouched. - */ -export const INSTANT_CONFIG = { - header: 0x0000, - keymap: 0x0007, - stageEnable: 0x001c, - stageColorsA: 0x0020, - stageColorsB: 0x0028, - sensor: 0x0030, - lightingDirection: 0x003a, - lighting: 0x003e, - trailer: 0x0f80, -} as const; - -/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ -export const INSTANT_CONFIG_LENGTH = 0x1000; - -/** - * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array - * index + 1 is the on-wire gear index (the value the vendor app stores in a - * DPI stage); the second number in the INI is a separate firmware code. - */ -export const INSTANT_DPI_GEARS: readonly number[] = [ - 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, - 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, -]; - -export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; - -export function instantDpiGearIndex(dpi: number): number | null { - const index = INSTANT_DPI_GEARS.indexOf(dpi); - return index < 0 ? null : index + 1; -} - -function byte(value: number, name: string): number { - if (!Number.isInteger(value) || value < 0 || value > 0xff) { - throw new RangeError(`${name} is not a byte: ${value}`); - } - return value; -} - -/** Build one 8-byte report. `params` fills bytes 2..7. */ -export function instantFrame( - command: number, - params: readonly number[] = [], -): Uint8Array { - if (params.length > 6) { - throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); - } - const frame = new Uint8Array(INSTANT_FRAME_LENGTH); - frame[0] = INSTANT_REPORT_ID; - frame[1] = byte(command, "command"); - params.forEach((value, index) => { - frame[2 + index] = byte(value, `parameter ${index}`); - }); - return frame; -} - -/** Frames that write `data` to `address`, followed by finish and commit. */ -export function instantBlockWriteFrames( - address: number, - data: readonly number[], -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (data.length === 0 || data.length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${data.length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = data.length - 1; - const frames = data.map((value, index) => - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - byte(value, `data byte ${index}`), - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.finish, - 0, - low, - high, - 0, - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frames that prepare and read `length` bytes from `address`. */ -export function instantBlockReadFrames( - address: number, - length: number, -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (length < 1 || length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = length - 1; - const frames: Uint8Array[] = []; - for (let index = 0; index < length; index += 1) { - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - 0, - last, - ]), - ); - } - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frame that requests byte `index` of the prepared read block. */ -export function instantBlockReadByteFrame( - address: number, - index: number, - length: number, -): Uint8Array { - return instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.read, - index, - address & 0xff, - (address >>> 8) & 0xff, - 0, - length - 1, - ]); -} - -/** The value returned by a read byte frame lives at report byte 1. */ -export function decodeInstantReadByte(report: Uint8Array): number | null { - return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; -} - -/** Frames that set a live DPI value and commit it. */ -export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { - const gear = instantDpiGearIndex(dpi); - if (gear == null) { - throw new RangeError(`Unsupported A825 DPI: ${dpi}`); - } - if (mode === 0) { - return [ - instantFrame(INSTANT_COMMAND.dpi, [Math.round(dpi / 8), 0, 0, 0, 0, 0]), - instantFrame(INSTANT_COMMAND.apply), - ]; - } - const units = Math.round(dpi / 16); - return [ - instantFrame(INSTANT_COMMAND.dpi, [ - (units >>> 8) & 0xff, - units & 0xff, - 0, - 0, - 0, - 0, - ]), - instantFrame(INSTANT_COMMAND.apply), - ]; -} - -/** Enter or leave the block-write mode used at the end of an Apply. */ -export function instantModeFrames(enter: boolean): Uint8Array[] { - return [ - instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), - ]; -} - -export interface InstantConfigImage { - /** Raw 0x0000-0x02FF configuration image. */ - bytes: Uint8Array; - /** - * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and - * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); - * it is NOT the polling rate. Kept raw until the layout is fully named. - */ - lightingDirectionByte: number; -} - -export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { - if (bytes.length < INSTANT_CONFIG.lightingDirection + 1) { - throw new RangeError("Instant config image is truncated"); - } - return { - bytes, - lightingDirectionByte: bytes[INSTANT_CONFIG.lightingDirection]!, - }; -} - -export interface InstantStatus { - /** Firmware/build word at bytes 2-3, big-endian (0x0954 on the Kaze). */ - firmware: number; - /** State byte 1; changes with device activity. */ - state: number; - /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ - sensorCpi: number; - /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ - magicOk: boolean; -} - -export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { - if (report.length < 20) return null; - const offset = report[0] === INSTANT_REPORT_ID ? 1 : 0; - if (report.length < offset + 19) return null; - return { - firmware: report[offset + 1]! | (report[offset + 2]! << 8), - state: report[offset]!, - sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), - magicOk: - report[offset + 15] === 0x24 && - report[offset + 16] === 0x5a && - report[offset + 17] === 0xa5, - }; -} +/** + * Instant Microelectronics A825 configuration protocol. + * + * Reverse-engineered from the vendor control app shipped for the Sades Kaze + * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` + * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a + * Sades Kaze on VID 0x30FA / PID 0x1440. + * + * Transport + * --------- + * The control collection is usage page 0xFF01, usage 1, on interface 1. Its + * only feature report is report ID 7. The vendor app and the device both use + * 8-byte feature reports: + * + * [0x07, command, a, b, c, d, e, f] + * + * The same report also carries a 32-byte status block that the device returns + * from a feature read; only the first eight bytes are used for command replies. + * + * Block access (command 0x18) + * --------------------------- + * The device exposes a 16-bit, little-endian addressed configuration memory. + * A block is written as one frame per byte, then finished and committed: + * + * 07 18 03 + * 07 18 09 00 00 + * 07 18 00 00 00 00 + * + * A byte is read by issuing the same address/length setup and then one frame + * per byte: + * + * 07 18 03 00 00 + * 07 18 00 00 00 00 + * 07 18 05 00 → reply byte 1 + * 07 18 00 00 00 00 + * + * Verified on hardware: writing the byte at 0x3A and reading it back returns + * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not + * the polling rate. The 0x0000-0x0FFF image is readable with + * `instantBlockReadFrames`. + * + * Direct commands + * --------------- + * The vendor app also writes a DPI value and a button map directly: + * + * 07 12 00 00 00 00 00 (mode 0) + * 07 12 ... (other modes) + * 07 11 00 ... commit + * 07 09 ... button map + * 07 17 ... 16-bit key/function code + * 07 13 ... lighting/mode + * + * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the + * 0x0F80 trailer). The direct commands above are read from the vendor code; + * sending 0x12 on the tested unit changed neither the stored image nor the + * status block. + */ + +export const INSTANT_VENDOR_ID = 0x30fa; + +/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ +export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ + 0x1440, 0x1e01, 0x7f7f, +]); + +export const INSTANT_USAGE_PAGE = 0xff01; +export const INSTANT_USAGE = 0x01; +export const INSTANT_INTERFACE = 1; + +export const INSTANT_REPORT_ID = 0x07; +export const INSTANT_FRAME_LENGTH = 8; +/** Status block returned by a feature read on report 7. */ +export const INSTANT_STATUS_LENGTH = 32; + +export const INSTANT_COMMAND = { + block: 0x18, + dpi: 0x12, + apply: 0x11, + buttonMap: 0x09, + keyCode: 0x17, + notice: 0x13, +} as const; + +export const INSTANT_BLOCK = { + write: 0x03, + read: 0x05, + finish: 0x09, + commit: 0x00, + mode: 0x10, +} as const; + +/** + * Configuration image addresses written by the vendor app's + * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes + * between blocks are untouched. + */ +export const INSTANT_CONFIG = { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, +} as const; + +/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ +export const INSTANT_CONFIG_LENGTH = 0x1000; + +/** + * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array + * index + 1 is the on-wire gear index (the value the vendor app stores in a + * DPI stage); the second number in the INI is a separate firmware code. + */ +export const INSTANT_DPI_GEARS: readonly number[] = [ + 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, + 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, +]; + +export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; + +export function instantDpiGearIndex(dpi: number): number | null { + const index = INSTANT_DPI_GEARS.indexOf(dpi); + return index < 0 ? null : index + 1; +} + +function byte(value: number, name: string): number { + if (!Number.isInteger(value) || value < 0 || value > 0xff) { + throw new RangeError(`${name} is not a byte: ${value}`); + } + return value; +} + +/** Build one 8-byte report. `params` fills bytes 2..7. */ +export function instantFrame( + command: number, + params: readonly number[] = [], +): Uint8Array { + if (params.length > 6) { + throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); + } + const frame = new Uint8Array(INSTANT_FRAME_LENGTH); + frame[0] = INSTANT_REPORT_ID; + frame[1] = byte(command, "command"); + params.forEach((value, index) => { + frame[2 + index] = byte(value, `parameter ${index}`); + }); + return frame; +} + +/** Frames that write `data` to `address`, followed by finish and commit. */ +export function instantBlockWriteFrames( + address: number, + data: readonly number[], +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (data.length === 0 || data.length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${data.length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = data.length - 1; + const frames = data.map((value, index) => + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + byte(value, `data byte ${index}`), + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.finish, + 0, + low, + high, + 0, + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frames that prepare and read `length` bytes from `address`. */ +export function instantBlockReadFrames( + address: number, + length: number, +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = length - 1; + const frames: Uint8Array[] = []; + for (let index = 0; index < length; index += 1) { + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + 0, + last, + ]), + ); + } + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frame that requests byte `index` of the prepared read block. */ +export function instantBlockReadByteFrame( + address: number, + index: number, + length: number, +): Uint8Array { + return instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.read, + index, + address & 0xff, + (address >>> 8) & 0xff, + 0, + length - 1, + ]); +} + +/** The value returned by a read byte frame lives at report byte 1. */ +export function decodeInstantReadByte(report: Uint8Array): number | null { + return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; +} + +/** Frames that set a live DPI value and commit it. */ +export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { + const gear = instantDpiGearIndex(dpi); + if (gear == null) { + throw new RangeError(`Unsupported A825 DPI: ${dpi}`); + } + if (mode === 0) { + return [ + instantFrame(INSTANT_COMMAND.dpi, [Math.round(dpi / 8), 0, 0, 0, 0, 0]), + instantFrame(INSTANT_COMMAND.apply), + ]; + } + const units = Math.round(dpi / 16); + return [ + instantFrame(INSTANT_COMMAND.dpi, [ + (units >>> 8) & 0xff, + units & 0xff, + 0, + 0, + 0, + 0, + ]), + instantFrame(INSTANT_COMMAND.apply), + ]; +} + +/** Enter or leave the block-write mode used at the end of an Apply. */ +export function instantModeFrames(enter: boolean): Uint8Array[] { + return [ + instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), + ]; +} + +export interface InstantConfigImage { + /** Raw 0x0000-0x02FF configuration image. */ + bytes: Uint8Array; + /** + * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and + * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); + * it is NOT the polling rate. Kept raw until the layout is fully named. + */ + lightingDirectionByte: number; +} + +export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { + if (bytes.length < INSTANT_CONFIG.lightingDirection + 1) { + throw new RangeError("Instant config image is truncated"); + } + return { + bytes, + lightingDirectionByte: bytes[INSTANT_CONFIG.lightingDirection]!, + }; +} + +export interface InstantStatus { + /** Firmware/build word at bytes 2-3, big-endian (0x0954 on the Kaze). */ + firmware: number; + /** State byte 1; changes with device activity. */ + state: number; + /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ + sensorCpi: number; + /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ + magicOk: boolean; +} + +export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { + if (report.length < 20) return null; + const offset = report[0] === INSTANT_REPORT_ID ? 1 : 0; + if (report.length < offset + 19) return null; + return { + firmware: report[offset + 1]! | (report[offset + 2]! << 8), + state: report[offset]!, + sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), + magicOk: + report[offset + 15] === 0x24 && + report[offset + 16] === 0x5a && + report[offset + 17] === 0xa5, + }; +} From b048670ea96468631e4e02bb33403411eaa3a174 Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:20:03 +0700 Subject: [PATCH 5/6] fix(instant): address CodeRabbit review findings - Use fixed reply lengths instead of a 0x07 first-byte heuristic, with regressions for numbered and unnumbered replies. - Wait for a physical close before reopening, and close the read window when a reply is lost. - Return only the bytes a partial config read actually read, and cache only full images. - Reject stale generations before publishing status or config results. - Keep valuesVerified false; report a firmware build only when the status marker matches. - Validate read lengths, indexes, 16-bit addresses, and the mode-0 DPI byte limit. - Correct the record-id/bit-position wording, high-byte formulas, little-endian comment, and remove stray heredoc lines. --- docs/a825-config-records.md | 176 +++---- docs/devdock-functions.md | 196 ++++---- docs/instant-a825.md | 405 ++++++++-------- src/drivers/instant/a825-hid.test.ts | 255 +++++----- src/drivers/instant/a825-hid.ts | 540 +++++++++++---------- src/instant/protocol.test.ts | 238 ++++----- src/instant/protocol.ts | 695 ++++++++++++++------------- 7 files changed, 1295 insertions(+), 1210 deletions(-) diff --git a/docs/a825-config-records.md b/docs/a825-config-records.md index b521389..bd53fb9 100644 --- a/docs/a825-config-records.md +++ b/docs/a825-config-records.md @@ -1,88 +1,88 @@ -# A825 configuration records - -Generated from Ghidra's decompilation of `A825_BuildConfigImage` (0x481400) -in `DevDock.exe` (SHA-256 `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`). -The map key is the byte offset in the configuration image. - -| Offset | Value | -| --- | --- | -| `0x000` | `0x5a` | -| `0x001` | `(-(cVar20 != '\0') & 3U) + (*(byte *)((int)this + 0x74c) & 3) * ' '` | -| `0x002` | `0xa5` | -| `0x003` | `(byte)*(undefined4 *)((int)this + 0x8068)` | -| `0x004` | `(byte)(*(int *)((int)this + 0x8068) + (*(int *)((int)this + 0x8068) >> 0x1f & 0xffU) >> 8)` | -| `0x005` | `(byte)*(undefined4 *)((int)this + 0x8064)` | -| `0x006` | `(byte)(*(int *)((int)this + 0x8064) + (*(int *)((int)this + 0x8064) >> 0x1f & 0xffU) >> 8)` | -| `0x007` | `*(byte *)((int)this + 0x802c)` | -| `0x008` | `*(byte *)((int)this + 0x802d)` | -| `0x009` | `*(byte *)((int)this + 0x802e)` | -| `0x00A` | `*(byte *)((int)this + 0x802f)` | -| `0x00B` | `*(byte *)((int)this + 0x8030)` | -| `0x00C` | `*(byte *)((int)this + 0x8031)` | -| `0x00D` | `*(byte *)((int)this + 0x8032)` | -| `0x00E` | `*(byte *)((int)this + 0x8033)` | -| `0x00F` | `*(byte *)((int)this + 0x8034)` | -| `0x010` | `0` | -| `0x012` | `0` | -| `0x013` | `(((((*(byte *)((int)this + 0x7a7) >> 4 & 1) * '\x02' + (*(byte *)((int)this + 0x7a6) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a5) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a4) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a3) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a2) >> 4 & 1)` | -| `0x014` | `(((*(byte *)((int)this + 0x8104) & 3) * '\x02' + (*(byte *)((int)this + 0x8298) & 1)) * '\x02' + (*(byte *)((int)this + 0x829d) & 1)) * '\x02' + (*(byte *)((int)this + 0x829c) & 1) ` | -| `0x015` | `*(char *)((int)this + 0x7a4) * '\x10' + (*(byte *)((int)this + 0x7a5) & 0xf)` | -| `0x016` | `*(char *)((int)this + 0x7a6) * '\x10' + (*(byte *)((int)this + 0x7a7) & 0xf)` | -| `0x017` | `*(byte *)((int)this + 0x750) & 7` | -| `0x018` | `*(byte *)((int)this + 0x82a0) & 0x3f` | -| `0x019` | `(byte)iVar25` | -| `0x01B` | `(byte)(iVar25 + (iVar25 >> 0x1f & 0xffU) >> 8)` | -| `0x01C` | `((*(char *)((int)this + 0x82a6) * '\b' + (*(byte *)((int)this + 0x829e) & 7)) * '\x02' + *(char *)((int)this + 0x82a5)) * '\b' + (local_2cd & 7)` | -| `0x01D` | `*(byte *)((int)this + 0x7a8)` | -| `0x01E` | `0` | -| `0x020` | `(byte)*(undefined4 *)((int)this + 0x758) & 0xf` | -| `0x021` | `(byte)*(undefined4 *)((int)this + 0x75c) & 0xf` | -| `0x022` | `(byte)*(undefined4 *)((int)this + 0x760) & 0xf` | -| `0x023` | `(byte)*(undefined4 *)((int)this + 0x764) & 0xf` | -| `0x024` | `(byte)*(undefined4 *)((int)this + 0x768) & 0xf` | -| `0x025` | `(byte)*(undefined4 *)((int)this + 0x76c) & 0xf` | -| `0x026` | `(byte)*(undefined4 *)((int)this + 0x770) & 0xf` | -| `0x027` | `(byte)*(undefined4 *)((int)this + 0x774) & 0xf` | -| `0x028` | `(byte)*(undefined4 *)((int)this + 0x778) & 0xf` | -| `0x029` | `(byte)*(undefined4 *)((int)this + 0x77c) & 0xf` | -| `0x02A` | `(byte)*(undefined4 *)((int)this + 0x780) & 0xf` | -| `0x02B` | `(byte)*(undefined4 *)((int)this + 0x784) & 0xf` | -| `0x02C` | `(byte)*(undefined4 *)((int)this + 0x788) & 0xf` | -| `0x02D` | `(byte)*(undefined4 *)((int)this + 0x78c) & 0xf` | -| `0x02E` | `(byte)*(undefined4 *)((int)this + 0x790) & 0xf` | -| `0x02F` | `(byte)*(undefined4 *)((int)this + 0x794) & 0xf` | -| `0x030` | `(byte)*(undefined4 *)((int)this + 0x798) & 0xf` | -| `0x031` | `0` | -| `0x032` | `0` | -| `0x033` | `0` | -| `0x035` | `0` | -| `0x036` | `0` | -| `0x037` | `0` | -| `0x038` | `0` | -| `0x039` | `0` | -| `0x03A` | `*(byte *)((int)this + 0x8035)` | -| `0x03B` | `*(byte *)((int)this + 0x8036)` | -| `0x03C` | `*(byte *)((int)this + 0x8037)` | -| `0x03D` | `0` | -| `0x03E` | `0` | -| `0x03F` | `((*(char *)((int)this + 0x810c) * '\x04' + *(char *)((int)this + 0x8114)) * '\x04' + *(char *)((int)this + 0x8115)) * '\b' + *(char *)((int)this + 0x82ec)` | -| `0x040` | `(*(char *)((int)this + 0x82b4) * '\x02' + *(char *)((int)this + 0x82bc)) * ' ' + *(char *)((int)this + 0x82c4)` | -| `0x042` | `(*(char *)((int)this + 0x82b8) * '\x02' + *(char *)((int)this + 0x82c0)) * ' ' + *(char *)((int)this + 0x82c8)` | -| `0x043` | `(((*(char *)((int)this + 0x80fc) * '\x02' + *(char *)((int)this + 0x82f0)) * '\x02' + *(char *)((int)this + 0x82f4)) * '\x02' + *(char *)((int)this + 0x80f4)) * '\x10' + cVar20` | -| `0x044` | `(*(char *)((int)this + 0x908) * '\x02' + *(char *)((int)this + 0x86c)) * ' ' + *(char *)((int)this + 0x803a)` | -| `0x045` | `(*(char *)((int)this + 0x909) * '\x02' + *(char *)((int)this + 0x870)) * ' ' + *(char *)((int)this + 0x803b)` | -| `0x046` | `(*(char *)((int)this + 0x90a) * '\x02' + *(char *)((int)this + 0x874)) * ' ' + *(char *)((int)this + 0x803c)` | -| `0x047` | `(*(char *)((int)this + 0x90b) * '\x02' + *(char *)((int)this + 0x878)) * ' ' + *(char *)((int)this + 0x803d)` | -| `0x048` | `((char)*(undefined4 *)((int)this + 0x87c) + *(char *)((int)this + 0x90c) * '\x02') * ' ' + *(char *)((int)this + 0x803e)` | -| `0x049` | `((char)*(undefined4 *)((int)this + 0x880) + *(char *)((int)this + 0x90d) * '\x02') * ' ' + *(char *)((int)this + 0x803f)` | -| `0x04A` | `((char)*(undefined4 *)((int)this + 0x884) + *(char *)((int)this + 0x90e) * '\x02') * ' ' + *(char *)((int)this + 0x8040)` | -| `0x04B` | `((char)*(undefined4 *)((int)this + 0x88c) + *(char *)((int)this + 0x910) * '\x02') * ' ' + *(char *)((int)this + 0x8042)` | -| `0x04D` | `((char)*(undefined4 *)((int)this + 0x890) + *(char *)((int)this + 0x911) * '\x02') * ' ' + *(char *)((int)this + 0x8043)` | -| `0x04E` | `((char)*(undefined4 *)((int)this + 0x894) + *(char *)((int)this + 0x912) * '\x02') * ' ' + *(char *)((int)this + 0x8044)` | -| `0x04F` | `((char)*(undefined4 *)((int)this + 0x89c) + *(char *)((int)this + 0x914) * '\x02') * ' ' + *(char *)((int)this + 0x8048)` | -| `0x051` | `((char)*(undefined4 *)((int)this + 0x8a0) + *(char *)((int)this + 0x915) * '\x02') * ' ' + *(char *)((int)this + 0x8049)` | -| `0x052` | `((char)*(undefined4 *)((int)this + 0x8a4) + *(char *)((int)this + 0x916) * '\x02') * ' ' + *(char *)((int)this + 0x804a)` | -| `0x053` | `((char)*(undefined4 *)((int)this + 0x8ac) + *(char *)((int)this + 0x918) * '\x02') * ' ' + *(char *)((int)this + 0x804c)` | -| `0x055` | `((char)*(undefined4 *)((int)this + 0x8b0) + *(char *)((int)this + 0x919) * '\x02') * ' ' + *(char *)((int)this + 0x804d)` | -| `0x056` | `((char)*(undefined4 *)((int)this + 0x8b4) + *(char *)((int)this + 0x91a) * '\x02') * ' ' + *(char *)((int)this + 0x804e)` | -| `0x057` | `((char)*(undefined4 *)((int)this + 0x8bc) + *(char *)((int)this + 0x91c) * '\x02') * ' ' + *(char *)((int)this + 0x8050)` | +# A825 configuration records + +Generated from Ghidra's decompilation of `A825_BuildConfigImage` (0x481400) +in `DevDock.exe` (SHA-256 `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`). +The map key is the record id that `A825_BuildConfigImage` uses. The mapping from each record id to a byte offset in the configuration image is not resolved; see `docs/devdock-functions.md`. + +| Record id | Value | +| --- | --- | +| `0x000` | `0x5a` | +| `0x001` | `(-(cVar20 != '\0') & 3U) + (*(byte *)((int)this + 0x74c) & 3) * ' '` | +| `0x002` | `0xa5` | +| `0x003` | `(byte)*(undefined4 *)((int)this + 0x8068)` | +| `0x004` | `(byte)(*(int *)((int)this + 0x8068) + (*(int *)((int)this + 0x8068) >> 0x1f & 0xffU) >> 8)` | +| `0x005` | `(byte)*(undefined4 *)((int)this + 0x8064)` | +| `0x006` | `(byte)(*(int *)((int)this + 0x8064) + (*(int *)((int)this + 0x8064) >> 0x1f & 0xffU) >> 8)` | +| `0x007` | `*(byte *)((int)this + 0x802c)` | +| `0x008` | `*(byte *)((int)this + 0x802d)` | +| `0x009` | `*(byte *)((int)this + 0x802e)` | +| `0x00A` | `*(byte *)((int)this + 0x802f)` | +| `0x00B` | `*(byte *)((int)this + 0x8030)` | +| `0x00C` | `*(byte *)((int)this + 0x8031)` | +| `0x00D` | `*(byte *)((int)this + 0x8032)` | +| `0x00E` | `*(byte *)((int)this + 0x8033)` | +| `0x00F` | `*(byte *)((int)this + 0x8034)` | +| `0x010` | `0` | +| `0x012` | `0` | +| `0x013` | `(((((*(byte *)((int)this + 0x7a7) >> 4 & 1) * '\x02' + (*(byte *)((int)this + 0x7a6) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a5) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a4) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a3) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a2) >> 4 & 1)` | +| `0x014` | `(((*(byte *)((int)this + 0x8104) & 3) * '\x02' + (*(byte *)((int)this + 0x8298) & 1)) * '\x02' + (*(byte *)((int)this + 0x829d) & 1)) * '\x02' + (*(byte *)((int)this + 0x829c) & 1) ` | +| `0x015` | `*(char *)((int)this + 0x7a4) * '\x10' + (*(byte *)((int)this + 0x7a5) & 0xf)` | +| `0x016` | `*(char *)((int)this + 0x7a6) * '\x10' + (*(byte *)((int)this + 0x7a7) & 0xf)` | +| `0x017` | `*(byte *)((int)this + 0x750) & 7` | +| `0x018` | `*(byte *)((int)this + 0x82a0) & 0x3f` | +| `0x019` | `(byte)iVar25` | +| `0x01B` | `(byte)(iVar25 + (iVar25 >> 0x1f & 0xffU) >> 8)` | +| `0x01C` | `((*(char *)((int)this + 0x82a6) * '\b' + (*(byte *)((int)this + 0x829e) & 7)) * '\x02' + *(char *)((int)this + 0x82a5)) * '\b' + (local_2cd & 7)` | +| `0x01D` | `*(byte *)((int)this + 0x7a8)` | +| `0x01E` | `0` | +| `0x020` | `(byte)*(undefined4 *)((int)this + 0x758) & 0xf` | +| `0x021` | `(byte)*(undefined4 *)((int)this + 0x75c) & 0xf` | +| `0x022` | `(byte)*(undefined4 *)((int)this + 0x760) & 0xf` | +| `0x023` | `(byte)*(undefined4 *)((int)this + 0x764) & 0xf` | +| `0x024` | `(byte)*(undefined4 *)((int)this + 0x768) & 0xf` | +| `0x025` | `(byte)*(undefined4 *)((int)this + 0x76c) & 0xf` | +| `0x026` | `(byte)*(undefined4 *)((int)this + 0x770) & 0xf` | +| `0x027` | `(byte)*(undefined4 *)((int)this + 0x774) & 0xf` | +| `0x028` | `(byte)*(undefined4 *)((int)this + 0x778) & 0xf` | +| `0x029` | `(byte)*(undefined4 *)((int)this + 0x77c) & 0xf` | +| `0x02A` | `(byte)*(undefined4 *)((int)this + 0x780) & 0xf` | +| `0x02B` | `(byte)*(undefined4 *)((int)this + 0x784) & 0xf` | +| `0x02C` | `(byte)*(undefined4 *)((int)this + 0x788) & 0xf` | +| `0x02D` | `(byte)*(undefined4 *)((int)this + 0x78c) & 0xf` | +| `0x02E` | `(byte)*(undefined4 *)((int)this + 0x790) & 0xf` | +| `0x02F` | `(byte)*(undefined4 *)((int)this + 0x794) & 0xf` | +| `0x030` | `(byte)*(undefined4 *)((int)this + 0x798) & 0xf` | +| `0x031` | `0` | +| `0x032` | `0` | +| `0x033` | `0` | +| `0x035` | `0` | +| `0x036` | `0` | +| `0x037` | `0` | +| `0x038` | `0` | +| `0x039` | `0` | +| `0x03A` | `*(byte *)((int)this + 0x8035)` | +| `0x03B` | `*(byte *)((int)this + 0x8036)` | +| `0x03C` | `*(byte *)((int)this + 0x8037)` | +| `0x03D` | `0` | +| `0x03E` | `0` | +| `0x03F` | `((*(char *)((int)this + 0x810c) * '\x04' + *(char *)((int)this + 0x8114)) * '\x04' + *(char *)((int)this + 0x8115)) * '\b' + *(char *)((int)this + 0x82ec)` | +| `0x040` | `(*(char *)((int)this + 0x82b4) * '\x02' + *(char *)((int)this + 0x82bc)) * ' ' + *(char *)((int)this + 0x82c4)` | +| `0x042` | `(*(char *)((int)this + 0x82b8) * '\x02' + *(char *)((int)this + 0x82c0)) * ' ' + *(char *)((int)this + 0x82c8)` | +| `0x043` | `(((*(char *)((int)this + 0x80fc) * '\x02' + *(char *)((int)this + 0x82f0)) * '\x02' + *(char *)((int)this + 0x82f4)) * '\x02' + *(char *)((int)this + 0x80f4)) * '\x10' + cVar20` | +| `0x044` | `(*(char *)((int)this + 0x908) * '\x02' + *(char *)((int)this + 0x86c)) * ' ' + *(char *)((int)this + 0x803a)` | +| `0x045` | `(*(char *)((int)this + 0x909) * '\x02' + *(char *)((int)this + 0x870)) * ' ' + *(char *)((int)this + 0x803b)` | +| `0x046` | `(*(char *)((int)this + 0x90a) * '\x02' + *(char *)((int)this + 0x874)) * ' ' + *(char *)((int)this + 0x803c)` | +| `0x047` | `(*(char *)((int)this + 0x90b) * '\x02' + *(char *)((int)this + 0x878)) * ' ' + *(char *)((int)this + 0x803d)` | +| `0x048` | `((char)*(undefined4 *)((int)this + 0x87c) + *(char *)((int)this + 0x90c) * '\x02') * ' ' + *(char *)((int)this + 0x803e)` | +| `0x049` | `((char)*(undefined4 *)((int)this + 0x880) + *(char *)((int)this + 0x90d) * '\x02') * ' ' + *(char *)((int)this + 0x803f)` | +| `0x04A` | `((char)*(undefined4 *)((int)this + 0x884) + *(char *)((int)this + 0x90e) * '\x02') * ' ' + *(char *)((int)this + 0x8040)` | +| `0x04B` | `((char)*(undefined4 *)((int)this + 0x88c) + *(char *)((int)this + 0x910) * '\x02') * ' ' + *(char *)((int)this + 0x8042)` | +| `0x04D` | `((char)*(undefined4 *)((int)this + 0x890) + *(char *)((int)this + 0x911) * '\x02') * ' ' + *(char *)((int)this + 0x8043)` | +| `0x04E` | `((char)*(undefined4 *)((int)this + 0x894) + *(char *)((int)this + 0x912) * '\x02') * ' ' + *(char *)((int)this + 0x8044)` | +| `0x04F` | `((char)*(undefined4 *)((int)this + 0x89c) + *(char *)((int)this + 0x914) * '\x02') * ' ' + *(char *)((int)this + 0x8048)` | +| `0x051` | `((char)*(undefined4 *)((int)this + 0x8a0) + *(char *)((int)this + 0x915) * '\x02') * ' ' + *(char *)((int)this + 0x8049)` | +| `0x052` | `((char)*(undefined4 *)((int)this + 0x8a4) + *(char *)((int)this + 0x916) * '\x02') * ' ' + *(char *)((int)this + 0x804a)` | +| `0x053` | `((char)*(undefined4 *)((int)this + 0x8ac) + *(char *)((int)this + 0x918) * '\x02') * ' ' + *(char *)((int)this + 0x804c)` | +| `0x055` | `((char)*(undefined4 *)((int)this + 0x8b0) + *(char *)((int)this + 0x919) * '\x02') * ' ' + *(char *)((int)this + 0x804d)` | +| `0x056` | `((char)*(undefined4 *)((int)this + 0x8b4) + *(char *)((int)this + 0x91a) * '\x02') * ' ' + *(char *)((int)this + 0x804e)` | +| `0x057` | `((char)*(undefined4 *)((int)this + 0x8bc) + *(char *)((int)this + 0x91c) * '\x02') * ' ' + *(char *)((int)this + 0x8050)` | diff --git a/docs/devdock-functions.md b/docs/devdock-functions.md index f2a5241..7743029 100644 --- a/docs/devdock-functions.md +++ b/docs/devdock-functions.md @@ -1,98 +1,98 @@ -# DevDock function map (Sades Kaze A825) - -Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from -`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. - -The analysis database used the names below; the addresses are the evidence. - -| Address | Name | Role | -| --- | --- | --- | -| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | -| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | -| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | -| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | -| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` packs `byte[0x8104] & 3` above three flags; writing it did not change the measured report cadence. | -| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | -| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | -| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | -| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | -| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | -| `0x486FA0` | apply state collector | Collect UI state into the device object. | -| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | -| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | -| `0x460A60` | `MacroSenderThread` | Macro playback thread. | -| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | -| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | -| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | - -## Block write - -`A825_BlockWrite(this, handle, address, data, length)`: - -``` -07 18 03 -``` - -one frame per byte, then: - -``` -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Addresses are little-endian. The wait between the finish and commit frames is -12 ms. - -## Read - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → feature report byte 1 -07 18 00 00 00 00 -``` - -## Block mode - -`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then -`07 18 00 00 00 00 00 00`. - -## DPI frames - -`A825_LiveDpiAndButtons`: - -``` -07 12 mode 0 -07 12 other modes -07 11 -07 09 × 4 -``` - -The four `09` frames use: - -``` -byte2 = ((map >> 4) << 6) + profile -byte3 = (map << 4) + 8 + index -byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 -``` - -where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the -flags are `byte[0x79C..0x79F]`. - -## Configuration image - -`A825_BuildConfigImage` collects records with numeric ids: - -| Id | Value | -| --- | --- | -| 0 | `0x5A` | -| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | -| 2 | `0xA5` | -| 3 | `byte[0x8068]` | -| 4 | `byte[0x8068] >> 8` | -| 5 | `byte[0x8064]` | -| 6 | `byte[0x8064] >> 8` | -| 7 | `byte[0x802C]` (key map byte 0) | -| 8+ | lighting and stage fields | - -The record-to-image-address mapping is not resolved. +# DevDock function map (Sades Kaze A825) + +Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from +`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. + +The analysis database used the names below; the addresses are the evidence. + +| Address | Name | Role | +| --- | --- | --- | +| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | +| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | +| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | +| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | +| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` puts `byte[0x8104] & 3` in bits 4-3 above three flags; writing it did not change the measured report cadence. | +| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | +| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | +| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | +| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | +| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | +| `0x486FA0` | apply state collector | Collect UI state into the device object. | +| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | +| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | +| `0x460A60` | `MacroSenderThread` | Macro playback thread. | +| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | +| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | +| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | + +## Block write + +`A825_BlockWrite(this, handle, address, data, length)`: + +``` +07 18 03 +``` + +one frame per byte, then: + +``` +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Addresses are little-endian. The wait between the finish and commit frames is +12 ms. + +## Read + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → feature report byte 1 +07 18 00 00 00 00 +``` + +## Block mode + +`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then +`07 18 00 00 00 00 00 00`. + +## DPI frames + +`A825_LiveDpiAndButtons`: + +``` +07 12 mode 0 +07 12 other modes +07 11 +07 09 × 4 +``` + +The four `09` frames use: + +``` +byte2 = ((map >> 4) << 6) + profile +byte3 = (map << 4) + 8 + index +byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 +``` + +where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the +flags are `byte[0x79C..0x79F]`. + +## Configuration image + +`A825_BuildConfigImage` collects records with numeric ids: + +| Id | Value | +| --- | --- | +| 0 | `0x5A` | +| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | +| 2 | `0xA5` | +| 3 | `byte[0x8068]` | +| 4 | `byte 1 of the 32-bit value at 0x8068` | +| 5 | `byte[0x8064]` | +| 6 | `byte 1 of the 32-bit value at 0x8064` | +| 7 | `byte[0x802C]` (key map byte 0) | +| 8+ | lighting and stage fields | + +The record-to-image-address mapping is not resolved. diff --git a/docs/instant-a825.md b/docs/instant-a825.md index a6450ce..6695c0b 100644 --- a/docs/instant-a825.md +++ b/docs/instant-a825.md @@ -1,203 +1,202 @@ -# Instant A825 - -Protocol of the Instant Microelectronics A825 control interface, reverse -engineered from the vendor `DevDock.exe` and verified on a Sades Kaze. - -## Identity and connection paths - -- Vendor: Wuxi Instant Microelectronics (A825 chipset). -- Tested model: Sades Kaze (Instant A825), wired USB. -- USB: VID `0x30FA`, PID `0x1440`; the vendor configuration also lists PID - `0x1E01`. Public A825 research lists PID `0x7F7F`. -- Product string `USB GAMING MOUSE`, manufacturer string `INSTANT`. -- Configuration collection: usage page `0xFF01`, usage `0x01`, interface 1. -- Report 7 is the only feature report. Windows reports an 8-byte feature - report; the same report returns a 32-byte status block. -- Firmware/build word in the status block: `0x0954`. - -## Evidence - -- `SadesKaze(A825).[20241009].exe` → `DevDock.exe`, product `New825Tab`, - 32-bit MSVC + DuiLib, SHA-256 - `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`. -- Chip vendor reference build: `Instant A825 Mouse Reference - Driver.[20250716]` from instant-sys.com, same `New825Tab` codebase with a - generic `Instant A825 Gaming Mouse` profile. -- Ghidra analysis of the Sades build; the function names below are the - annotated names in that database. `docs/devdock-functions.md` lists the - addresses; `docs/a825-config-records.md` lists every configuration record. -- A825 datasheet V1.01 (Instant Microelectronics). - -## Transport - -Commands are 8-byte feature reports: - -``` -07 -``` - -Status read on report 7: - -``` -07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... -``` - -`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed `24 5A A5` -marker. `state` and `n` change with device activity. - -## Block access - -Command `0x18` addresses a 16-bit little-endian configuration memory. Write: - -``` -07 18 03 -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Read: - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → reply byte 1 -07 18 00 00 00 00 -``` - -`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a -save. `A825_BlockWrite` is `0x455A40`; `A825_BlockMode` is `0x455BA0`. - -## Vendor command paths - -| Command | Path | Purpose | -| --- | --- | --- | -| `18` | `A825_BlockWrite` / `A825_BlockMode` | Read/write the configuration image | -| `12` | `A825_LiveDpiAndButtons` (`0x486630`) | Live DPI value | -| `11` | `A825_LiveDpiAndButtons` | Commit | -| `09` | `A825_ButtonMap` (`0x486440`), `A825_ButtonMapFrame` (`0x454B30`) | Button map | -| `17` | `A825_KeyCodeFrame` (`0x454BA0`) | 16-bit key/function code | -| `13` | profile switch (`0x402700`) | Lighting/mode | -| `18 10`/`18 00` | `A825_BlockMode` | Enter/leave save mode | - -`A825_BuildConfigImage` (`0x481400`) assembles the stored image as -offset/value records. `A825_WriteLightingConfig` (`0x480B00`) writes the -lighting blocks. `A825_ApplyLighting` (`0x469EB0`) collects the lighting UI -and calls the writer. - -## Stored configuration - -The tested unit's `0x0000-0x008F`: - -``` -0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 -0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 -0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF -0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 -0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 -0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 -0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 -0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 -0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 -``` - -`0x0400-0x04FF` holds repeated 32-byte records beginning -`01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`; -`0x0500-0x0FFF` is `FF` fill with `00 00` at every `0x100` boundary. - -Blocks written by the vendor application: - -| Address | Length | Meaning (from code) | -| --- | --- | --- | -| `0x0000` | 2 | Header | -| `0x0007` | 25 | Key map | -| `0x001C` | 2 | Stage-enable mask and flags | -| `0x0020` | 8 | Stage colours A | -| `0x0028` | 8 | Stage colours B | -| `0x0030` | 4 | Sensor options | -| `0x003A` | 1 | Lighting direction/symmetry | -| `0x003E` | 2 | Lighting | -| `0x0F80` | 2 | Trailer | - -`0x3A` holds -`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. -It is not the polling rate. - -## Polling rate - -Record `0x14` of `A825_BuildConfigImage` is: - -``` -(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 - + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) -``` - -The top two bits are a 2-bit field. All four values were written to `0x14` and -read back correctly, but the measured report cadence stayed at ~125 Hz for -every value. The field is therefore not confirmed as the polling rate; it may -be applied only on save/reconnect or be a different setting. - -## DPI - -`A825_LiveDpiAndButtons` sends: - -``` -07 12 00 00 00 00 00 mode 0 -07 12 … other modes -07 11 00 00 00 00 00 00 commit -07 09 … four button-map frames -``` - -The 23 DPI gears: - -``` -200 400 600 800 1000 1200 1400 1600 1800 2000 -2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 -10400 11200 12800 -``` - -Sending `0x12` on the tested unit did not change the stored image or the -status block. The six-stage CPI table was not found in `0x0000-0x0FFF`. - -## Lighting - -`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` -fields. `A825_ApplyLighting` collects `light_color`, `light_color_en`, -`light_brightness`, `light_speed`, `light_symmetry` and `light_direction`. -The profile switch also sends `07 13 7F 00 00 20 07`. - -## Validation - -| Claim | Result | -| --- | --- | -| VID/PID, `0xFF01:0x01`, report 7, 8-byte feature reports | Observed | -| 8-byte command frames accepted | Observed | -| Block write and read-back at `0x3A` (`0x0B → 0x0A → 0x0B`) | Observed | -| Stored image `0x0000-0x0FFF` read byte by byte | Observed | -| Rate field `0x14` write/read-back | Observed; effect on cadence not observed | -| DPI `0x12` effect | Not observed | -| Vendor Apply block sequence | Captured from the vendor app | - -## Not yet verified - -- The mapping from the `0x14` 2-bit field to 125/250/500/1000 Hz. -- The six-stage CPI table location. -- Button-map and lighting semantics beyond the frames listed here. - -## Devices - -The A825 is a chipset. Public A825 mice: - -- Sades Kaze (Instant A825) — tested. -- Ant Esports GM320 — public reverse-engineering project. -- AJAZZ NJ08. -- Kreo Harpy. -- Cybeart Ghost. - -## Sources - -- A825 datasheet V1.01, Instant Microelectronics. -- `SadesKaze(A825).[20241009].exe` (vendor application). -- `Instant A825 Mouse Reference Driver.[20250716]` (vendor reference build). -- `https://github.com/helllopratik/ant-gm320-linux-experimental`. -EOF -echo rewritten; wc -l mproto/docs/instant-a825.md \ No newline at end of file +# Instant A825 + +Protocol of the Instant Microelectronics A825 control interface, reverse +engineered from the vendor `DevDock.exe` and verified on a Sades Kaze. + +## Identity and connection paths + +- Vendor: Wuxi Instant Microelectronics (A825 chipset). +- Tested model: Sades Kaze (Instant A825), wired USB. +- USB: VID `0x30FA`, PID `0x1440`; the vendor configuration also lists PID + `0x1E01`. Public A825 research lists PID `0x7F7F`. +- Product string `USB GAMING MOUSE`, manufacturer string `INSTANT`. +- Configuration collection: usage page `0xFF01`, usage `0x01`, interface 1. +- Report 7 is the only feature report. Windows reports an 8-byte feature + report; the same report returns a 32-byte status block. +- Firmware/build word in the status block: `0x0954`. + +## Evidence + +- `SadesKaze(A825).[20241009].exe` → `DevDock.exe`, product `New825Tab`, + 32-bit MSVC + DuiLib, SHA-256 + `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`. +- Chip vendor reference build: `Instant A825 Mouse Reference + Driver.[20250716]` from instant-sys.com, same `New825Tab` codebase with a + generic `Instant A825 Gaming Mouse` profile. +- Ghidra analysis of the Sades build; the function names below are the + annotated names in that database. `docs/devdock-functions.md` lists the + addresses; `docs/a825-config-records.md` lists every configuration record. +- A825 datasheet V1.01 (Instant Microelectronics). + +## Transport + +Commands are 8-byte feature reports: + +``` +07 +``` + +Status read on report 7: + +``` +07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... +``` + +`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed `24 5A A5` +marker. `state` and `n` change with device activity. + +## Block access + +Command `0x18` addresses a 16-bit little-endian configuration memory. Write: + +``` +07 18 03 +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Read: + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → reply byte 1 +07 18 00 00 00 00 +``` + +`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a +save. `A825_BlockWrite` is `0x455A40`; `A825_BlockMode` is `0x455BA0`. + +## Vendor command paths + +| Command | Path | Purpose | +| --- | --- | --- | +| `18` | `A825_BlockWrite` / `A825_BlockMode` | Read/write the configuration image | +| `12` | `A825_LiveDpiAndButtons` (`0x486630`) | Live DPI value | +| `11` | `A825_LiveDpiAndButtons` | Commit | +| `09` | `A825_ButtonMap` (`0x486440`), `A825_ButtonMapFrame` (`0x454B30`) | Button map | +| `17` | `A825_KeyCodeFrame` (`0x454BA0`) | 16-bit key/function code | +| `13` | profile switch (`0x402700`) | Lighting/mode | +| `18 10`/`18 00` | `A825_BlockMode` | Enter/leave save mode | + +`A825_BuildConfigImage` (`0x481400`) assembles the stored image as +offset/value records. `A825_WriteLightingConfig` (`0x480B00`) writes the +lighting blocks. `A825_ApplyLighting` (`0x469EB0`) collects the lighting UI +and calls the writer. + +## Stored configuration + +The tested unit's `0x0000-0x008F`: + +``` +0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 +0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 +0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF +0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 +0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 +0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 +0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 +0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 +0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 +``` + +`0x0400-0x04FF` holds repeated 32-byte records beginning +`01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`; +`0x0500-0x0FFF` is `FF` fill with `00 00` at every `0x100` boundary. + +Blocks written by the vendor application: + +| Address | Length | Meaning (from code) | +| --- | --- | --- | +| `0x0000` | 2 | Header | +| `0x0007` | 25 | Key map | +| `0x001C` | 2 | Stage-enable mask and flags | +| `0x0020` | 8 | Stage colours A | +| `0x0028` | 8 | Stage colours B | +| `0x0030` | 4 | Sensor options | +| `0x003A` | 1 | Lighting direction/symmetry | +| `0x003E` | 2 | Lighting | +| `0x0F80` | 2 | Trailer | + +`0x3A` holds +`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. +It is not the polling rate. + +## Polling rate + +Record `0x14` of `A825_BuildConfigImage` is: + +``` +(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 + + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) +``` + +Bits 4-3 of this record (`(byte >> 3) & 3`) are a 2-bit field. All four values +were written to `0x14` and read back correctly, but the measured report cadence +stayed at ~125 Hz for every value. The field is therefore not confirmed as the +polling rate; it may be applied only on save/reconnect or be a different +setting. + +## DPI + +`A825_LiveDpiAndButtons` sends: + +``` +07 12 00 00 00 00 00 mode 0 +07 12 … other modes +07 11 00 00 00 00 00 00 commit +07 09 … four button-map frames +``` + +The 23 DPI gears: + +``` +200 400 600 800 1000 1200 1400 1600 1800 2000 +2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 +10400 11200 12800 +``` + +Sending `0x12` on the tested unit did not change the stored image or the +status block. The six-stage CPI table was not found in `0x0000-0x0FFF`. + +## Lighting + +`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` +fields. `A825_ApplyLighting` collects `light_color`, `light_color_en`, +`light_brightness`, `light_speed`, `light_symmetry` and `light_direction`. +The profile switch also sends `07 13 7F 00 00 20 07`. + +## Validation + +| Claim | Result | +| --- | --- | +| VID/PID, `0xFF01:0x01`, report 7, 8-byte feature reports | Observed | +| 8-byte command frames accepted | Observed | +| Block write and read-back at `0x3A` (`0x0B → 0x0A → 0x0B`) | Observed | +| Stored image `0x0000-0x0FFF` read byte by byte | Observed | +| Rate field `0x14` write/read-back | Observed; effect on cadence not observed | +| DPI `0x12` effect | Not observed | +| Vendor Apply block sequence | Captured from the vendor app | + +## Not yet verified + +- The mapping from the `0x14` 2-bit field to 125/250/500/1000 Hz. +- The six-stage CPI table location. +- Button-map and lighting semantics beyond the frames listed here. + +## Devices + +The A825 is a chipset. Public A825 mice: + +- Sades Kaze (Instant A825) — tested. +- Ant Esports GM320 — public reverse-engineering project. +- AJAZZ NJ08. +- Kreo Harpy. +- Cybeart Ghost. + +## Sources + +- A825 datasheet V1.01, Instant Microelectronics. +- `SadesKaze(A825).[20241009].exe` (vendor application). +- `Instant A825 Mouse Reference Driver.[20250716]` (vendor reference build). +- `https://github.com/helllopratik/ant-gm320-linux-experimental`. diff --git a/src/drivers/instant/a825-hid.test.ts b/src/drivers/instant/a825-hid.test.ts index b0fbf6a..a848656 100644 --- a/src/drivers/instant/a825-hid.test.ts +++ b/src/drivers/instant/a825-hid.test.ts @@ -1,117 +1,138 @@ -import assert from "node:assert/strict"; -import test from "node:test"; - -import { - INSTANT_REPORT_ID, - INSTANT_USAGE, - INSTANT_USAGE_PAGE, - INSTANT_VENDOR_ID, -} from "@openmouse/protocol/instant"; -import { InstantA825HidClient } from "./a825-hid.ts"; - -function report(reportId: number): HIDReportInfo { - return { reportId, items: [] } as unknown as HIDReportInfo; -} - -function controlCollection(): HIDCollectionInfo { - return { - usagePage: INSTANT_USAGE_PAGE, - usage: INSTANT_USAGE, - type: 1, - children: [], - featureReports: [report(INSTANT_REPORT_ID)], - inputReports: [], - outputReports: [], - } as unknown as HIDCollectionInfo; -} - -const STATUS = Uint8Array.of( - 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, - 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, -); - -function fakeDevice(options: { - rate?: number; - productId?: number; -} = {}) { - let rate = options.rate ?? 0x0b; - let statusRead = false; - let readSetup = false; - const sent: Uint8Array[] = []; - let pendingWrite: { address: number; data: number[] } | null = null; - let writeFinished = false; - - const device = { - vendorId: INSTANT_VENDOR_ID, - productId: options.productId ?? 0x1440, - productName: "USB GAMING MOUSE", - opened: false, - collections: [controlCollection()], - async open() { - this.opened = true; - }, - async close() { - this.opened = false; - }, - async sendFeatureReport(_reportId: number, data: BufferSource) { - const view = ArrayBuffer.isView(data) - ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) - : new Uint8Array(data as ArrayBuffer); - const frame = Uint8Array.of(INSTANT_REPORT_ID, ...view); - sent.push(frame); - const address = frame[4]! | (frame[5]! << 8); - if (frame[1] === 0x18 && frame[2] === 0x03) { - readSetup = true; - if (frame[7] === 0) { - pendingWrite = { address, data: [frame[6]!] }; - } else if (pendingWrite?.address === address) { - pendingWrite.data[frame[3]!] = frame[6]!; - } - } - if (frame[1] === 0x18 && frame[2] === 0x09) { - writeFinished = true; - } - if (frame[1] === 0x18 && frame[2] === 0x00 && writeFinished) { - if (pendingWrite?.address === 0x3a) rate = pendingWrite.data[0]!; - pendingWrite = null; - writeFinished = false; - } - }, - async receiveFeatureReport(_reportId: number) { - if (readSetup) { - readSetup = false; - return new DataView(Uint8Array.of(INSTANT_REPORT_ID, rate, 0, 0, 0, 0, 0, 0).buffer); - } - statusRead = true; - return new DataView(STATUS.slice().buffer); - }, - } as unknown as HIDDevice; - - return { device, sent, get rate() { return rate; } }; -} - -test("A825 identifies the Sades Kaze control collection", () => { - const { device } = fakeDevice(); - assert.equal(InstantA825HidClient.isSupported(device), true); - assert.equal( - InstantA825HidClient.isSupported({ ...device, productId: 0x1234 } as HIDDevice), - false, - ); - assert.equal(InstantA825HidClient.isSupported({ ...device, vendorId: 0x1234 } as HIDDevice), false); -}); - -test("readStatus decodes firmware and stays read-only", async () => { - const { device } = fakeDevice({ rate: 0x0b }); - const client = new InstantA825HidClient(device); - const status = await client.readStatus(); - assert.equal(status.brand, "Sades"); - assert.equal(status.connectionType, "Wired"); - assert.equal(status.pollingRateHz, 0); - assert.equal(status.supportedPollingRates?.join(","), "125,250,500,1000"); - assert.equal(status.activeProfile, null); - assert.equal(status.dpi, 0); - assert.deepEqual(status.firmware, ["Build 0x0954"]); - assert.equal(status.ui?.settingsReady, false); - assert.equal(status.ui?.family, "sades-a825"); -}); +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + INSTANT_REPORT_ID, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, +} from "@openmouse/protocol/instant"; +import { InstantA825HidClient } from "./a825-hid.ts"; + +function report(reportId: number): HIDReportInfo { + return { reportId, items: [] } as unknown as HIDReportInfo; +} + +function controlCollection(): HIDCollectionInfo { + return { + usagePage: INSTANT_USAGE_PAGE, + usage: INSTANT_USAGE, + type: 1, + children: [], + featureReports: [report(INSTANT_REPORT_ID)], + inputReports: [], + outputReports: [], + } as unknown as HIDCollectionInfo; +} + +const STATUS = Uint8Array.of( + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +); + +function fakeDevice(options: { + rate?: number; + productId?: number; + numberedReply?: boolean; +} = {}) { + let rate = options.rate ?? 0x0b; + let statusRead = false; + let readSetup = false; + const sent: Uint8Array[] = []; + let pendingWrite: { address: number; data: number[] } | null = null; + let writeFinished = false; + + const device = { + vendorId: INSTANT_VENDOR_ID, + productId: options.productId ?? 0x1440, + productName: "USB GAMING MOUSE", + opened: false, + collections: [controlCollection()], + async open() { + this.opened = true; + }, + async close() { + this.opened = false; + }, + async sendFeatureReport(_reportId: number, data: BufferSource) { + const view = ArrayBuffer.isView(data) + ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) + : new Uint8Array(data as ArrayBuffer); + const frame = Uint8Array.of(INSTANT_REPORT_ID, ...view); + sent.push(frame); + const address = frame[4]! | (frame[5]! << 8); + if (frame[1] === 0x18 && frame[2] === 0x03) { + readSetup = true; + if (frame[7] === 0) { + pendingWrite = { address, data: [frame[6]!] }; + } else if (pendingWrite?.address === address) { + pendingWrite.data[frame[3]!] = frame[6]!; + } + } + if (frame[1] === 0x18 && frame[2] === 0x09) { + writeFinished = true; + } + if (frame[1] === 0x18 && frame[2] === 0x00 && writeFinished) { + if (pendingWrite?.address === 0x3a) rate = pendingWrite.data[0]!; + pendingWrite = null; + writeFinished = false; + } + }, + async receiveFeatureReport(_reportId: number) { + if (readSetup) { + readSetup = false; + const body = options.numberedReply === false + ? Uint8Array.of(rate, 0, 0, 0, 0, 0, 0) + : Uint8Array.of(INSTANT_REPORT_ID, rate, 0, 0, 0, 0, 0, 0); + return new DataView(body.buffer); + } + statusRead = true; + return new DataView(STATUS.slice().buffer); + }, + } as unknown as HIDDevice; + + return { device, sent, get rate() { return rate; } }; +} + +test("A825 identifies the Sades Kaze control collection", () => { + const { device } = fakeDevice(); + assert.equal(InstantA825HidClient.isSupported(device), true); + assert.equal( + InstantA825HidClient.isSupported({ ...device, productId: 0x1234 } as HIDDevice), + false, + ); + assert.equal(InstantA825HidClient.isSupported({ ...device, vendorId: 0x1234 } as HIDDevice), false); +}); + +test("readStatus decodes firmware and stays read-only", async () => { + const { device } = fakeDevice({ rate: 0x0b }); + const client = new InstantA825HidClient(device); + const status = await client.readStatus(); + assert.equal(status.brand, "Sades"); + assert.equal(status.connectionType, "Wired"); + assert.equal(status.pollingRateHz, 0); + assert.equal(status.supportedPollingRates?.join(","), "125,250,500,1000"); + assert.equal(status.activeProfile, null); + assert.equal(status.dpi, 0); + assert.deepEqual(status.firmware, ["Build 0x0954"]); + assert.equal(status.ui?.settingsReady, false); + assert.equal(status.ui?.family, "sades-a825"); + assert.equal(status.ui?.valuesVerified, false); +}); + +test("readConfigImage keeps a partial read and a stored 0x07 byte", async () => { + const fake = fakeDevice({ rate: 0x07 }); + const client = new InstantA825HidClient(fake.device); + const image = await client.readConfigImage(1); + assert.equal(image.bytes.length, 1); + assert.equal(image.bytes[0], 0x07); + assert.equal(image.lightingDirectionByte, null); +}); + +test("readConfigImage accepts an unnumbered 7-byte reply", async () => { + const fake = fakeDevice({ rate: 0x07, numberedReply: false }); + const client = new InstantA825HidClient(fake.device); + const image = await client.readConfigImage(1); + assert.deepEqual(Array.from(image.bytes), [0x07]); +}); diff --git a/src/drivers/instant/a825-hid.ts b/src/drivers/instant/a825-hid.ts index 7a1cb46..90eb587 100644 --- a/src/drivers/instant/a825-hid.ts +++ b/src/drivers/instant/a825-hid.ts @@ -1,248 +1,292 @@ -import type { MouseStatus } from "../mouse-types.ts"; -import { - decodeInstantConfig, - decodeInstantStatus, - instantBlockReadByteFrame, - instantBlockReadFrames, - instantFrame, - INSTANT_BLOCK, - INSTANT_COMMAND, - INSTANT_CONFIG_LENGTH, - INSTANT_DPI_GEARS, - INSTANT_POLLING_RATES, - INSTANT_PRODUCT_IDS, - INSTANT_REPORT_ID, - INSTANT_USAGE, - INSTANT_USAGE_PAGE, - INSTANT_VENDOR_ID, - instantDpiFrames, - type InstantConfigImage, -} from "@openmouse/protocol/instant"; - -function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { - return collections.some( - (collection) => - (collection.usagePage === INSTANT_USAGE_PAGE && - collection.usage === INSTANT_USAGE && - collection.featureReports.some( - (report) => report.reportId === INSTANT_REPORT_ID, - )) || - hasConfigCollection(collection.children), - ); -} - -function statusBytes(view: DataView, reportId: number): Uint8Array { - const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); - return bytes[0] === reportId ? bytes.slice(1) : bytes.slice(); -} - -/** - * Sades Kaze / Instant A825 control client. - * - * Reads the 32-byte status block and the stored configuration image. Settings - * framing is implemented in `@openmouse/protocol/instant`. The DPI command has - * no observable read-back on this firmware and the polling-rate field is not yet - * mapped, so the panel shows this device as read-only. - */ -export class InstantA825HidClient { - readonly device: HIDDevice; - private config: InstantConfigImage | null = null; - private status: Uint8Array | null = null; - private queue: Promise = Promise.resolve(); - private generation = 0; - private opening: Promise | null = null; - - constructor(device: HIDDevice) { - this.device = device; - } - - static isSupported(device: HIDDevice): boolean { - return ( - device.vendorId === INSTANT_VENDOR_ID && - INSTANT_PRODUCT_IDS.has(device.productId) && - hasConfigCollection(device.collections) - ); - } - - getDpiOptions(): number[] { - return [...INSTANT_DPI_GEARS]; - } - - getPollingRateOptions(): number[] { - return [...INSTANT_POLLING_RATES]; - } - - async open(): Promise { - if (!InstantA825HidClient.isSupported(this.device)) { - throw new Error("Unsupported A825 HID interface"); - } - if (this.opening) return this.opening; - if (this.device.opened) return; - const generation = this.generation; - const task = (async () => { - await this.device.open(); - if (generation !== this.generation) { - if (this.device.opened) await this.device.close(); - throw new Error("A825 disconnected while opening"); - } - })(); - this.opening = task; - try { - await task; - } finally { - if (this.opening === task) this.opening = null; - } - } - - async close(): Promise { - this.generation += 1; - this.config = null; - this.status = null; - this.queue = Promise.resolve(); - await this.opening?.catch(() => undefined); - if (this.device.opened) await this.device.close(); - } - - /** Raw 32-byte status report, including report ID 7. */ - getRawStatusReport(): Uint8Array | null { - return this.status?.slice() ?? null; - } - - /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ - getConfigImage(): InstantConfigImage | null { - return this.config - ? { - ...this.config, - bytes: this.config.bytes.slice(), - } - : null; - } - - private serialize(action: () => Promise): Promise { - const generation = this.generation; - const task = this.queue.then(() => { - if (generation !== this.generation) { - throw new Error("A825 disconnected before queued transfer"); - } - return action(); - }); - this.queue = task.then( - () => undefined, - () => undefined, - ); - return task; - } - - private async send(frame: Uint8Array): Promise { - await this.device.sendFeatureReport( - INSTANT_REPORT_ID, - frame.slice(1).buffer, - ); - } - - private async readStatusReport(): Promise { - const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); - return statusBytes(view, INSTANT_REPORT_ID); - } - - /** Read one byte from the configuration image, using the vendor read path. */ - private async readByte(address: number): Promise { - const setup = instantBlockReadFrames(address, 1); - for (const frame of setup) await this.send(frame); - await this.send(instantBlockReadByteFrame(address, 0, 1)); - const report = await this.readStatusReport(); - // The vendor closes the read window after every byte. - await this.send( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - address & 0xff, - (address >>> 8) & 0xff, - 0, - 0, - ]), - ); - const full = new Uint8Array(report.length + 1); - full[0] = INSTANT_REPORT_ID; - full.set(report, 1); - const value = full.length > 1 ? full[1] : null; - if (value == null) throw new Error("A825 config read returned no data"); - return value; - } - - /** - * Read the stored configuration image. This is 0x300 one-byte reads and is - * intentionally explicit: read a small range when only a few bytes matter. - */ - async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { - if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { - throw new RangeError(`Invalid A825 config length: ${length}`); - } - return this.serialize(async () => { - await this.open(); - const bytes = new Uint8Array(INSTANT_CONFIG_LENGTH); - for (let address = 0; address < length; address += 1) { - bytes[address] = await this.readByte(address); - } - this.config = decodeInstantConfig(bytes); - return this.getConfigImage()!; - }); - } - - async readStatus(): Promise { - return this.serialize(async () => { - const generation = this.generation; - await this.open(); - if (generation !== this.generation) { - throw new Error("A825 disconnected while opening"); - } - const report = await this.readStatusReport(); - this.status = new Uint8Array(report.length + 1); - this.status[0] = INSTANT_REPORT_ID; - this.status.set(report, 1); - const decoded = decodeInstantStatus(this.status); - - return { - brand: "Sades", - name: this.device.productName || "Sades Kaze", - ui: { - family: "sades-a825", - settingsReady: false, - valuesVerified: decoded !== null, - pollingReadOnly: true, - hideProcessingCard: true, - hideSignalCard: true, - hideSleepCard: true, - defaultDisplayName: "Sades Kaze", - statusNote: - "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", - }, - batteryPercent: null, - batteryState: "Unknown", - dpi: 0, - pollingRateHz: 0, - supportedPollingRates: [...INSTANT_POLLING_RATES], - activeProfile: null, - connectionType: "Wired", - connectionDetail: "USB", - liftOffDistance: null, - firmware: - decoded != null - ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] - : [], - }; - }); - } - - /** - * Send the vendor's live DPI command. Kept for protocol tooling; the panel - * does not expose it because this firmware gives no read-back for the value. - */ - async setLiveDpi(dpi: number, mode = 0): Promise { - return this.serialize(async () => { - await this.open(); - for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); - return dpi; - }); - } -} +import type { MouseStatus } from "../mouse-types.ts"; +import { + decodeInstantConfig, + decodeInstantStatus, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantFrame, + INSTANT_BLOCK, + INSTANT_COMMAND, + INSTANT_CONFIG_LENGTH, + INSTANT_DPI_GEARS, + INSTANT_FRAME_LENGTH, + INSTANT_POLLING_RATES, + INSTANT_PRODUCT_IDS, + INSTANT_REPORT_ID, + INSTANT_STATUS_LENGTH, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, + instantDpiFrames, + type InstantConfigImage, +} from "@openmouse/protocol/instant"; + +function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { + return collections.some( + (collection) => + (collection.usagePage === INSTANT_USAGE_PAGE && + collection.usage === INSTANT_USAGE && + collection.featureReports.some( + (report) => report.reportId === INSTANT_REPORT_ID, + )) || + hasConfigCollection(collection.children), + ); +} + +function statusBytes(view: DataView, reportId: number): Uint8Array { + const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); + // The A825 reports are fixed-size: a numbered reply is 8 bytes for a command + // and 32 for the status block. A reply of 7 or 31 bytes has no report ID, so + // do not guess from the first byte (a stored value may itself be 0x07). + const numbered = + bytes.length === INSTANT_FRAME_LENGTH || bytes.length === INSTANT_STATUS_LENGTH; + if (numbered) { + if (bytes[0] !== reportId) { + throw new Error(`Unexpected A825 report ID: ${bytes[0]}`); + } + return bytes.slice(1); + } + return bytes.slice(); +} + +/** + * Sades Kaze / Instant A825 control client. + * + * Reads the 32-byte status block and the stored configuration image. Settings + * framing is implemented in `@openmouse/protocol/instant`. The DPI command has + * no observable read-back on this firmware and the polling-rate field is not yet + * mapped, so the panel shows this device as read-only. + */ +export class InstantA825HidClient { + readonly device: HIDDevice; + private config: InstantConfigImage | null = null; + private status: Uint8Array | null = null; + private queue: Promise = Promise.resolve(); + private generation = 0; + private opening: Promise | null = null; + private closing: Promise | null = null; + + constructor(device: HIDDevice) { + this.device = device; + } + + static isSupported(device: HIDDevice): boolean { + return ( + device.vendorId === INSTANT_VENDOR_ID && + INSTANT_PRODUCT_IDS.has(device.productId) && + hasConfigCollection(device.collections) + ); + } + + getDpiOptions(): number[] { + return [...INSTANT_DPI_GEARS]; + } + + getPollingRateOptions(): number[] { + return [...INSTANT_POLLING_RATES]; + } + + async open(): Promise { + if (!InstantA825HidClient.isSupported(this.device)) { + throw new Error("Unsupported A825 HID interface"); + } + if (this.closing) await this.closing; + if (this.opening) return this.opening; + if (this.device.opened) return; + const generation = this.generation; + const task = (async () => { + await this.device.open(); + if (generation !== this.generation) { + if (this.device.opened) await this.device.close(); + throw new Error("A825 disconnected while opening"); + } + })(); + this.opening = task; + try { + await task; + } finally { + if (this.opening === task) this.opening = null; + } + } + + async close(): Promise { + this.generation += 1; + this.config = null; + this.status = null; + this.queue = Promise.resolve(); + const task = (async () => { + await this.opening?.catch(() => undefined); + if (this.device.opened) await this.device.close(); + })(); + this.closing = task; + try { + await task; + } finally { + if (this.closing === task) this.closing = null; + } + } + + /** Raw 32-byte status report, including report ID 7. */ + getRawStatusReport(): Uint8Array | null { + return this.status?.slice() ?? null; + } + + /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ + getConfigImage(): InstantConfigImage | null { + return this.config + ? { + ...this.config, + bytes: this.config.bytes.slice(), + } + : null; + } + + private serialize(action: () => Promise): Promise { + const generation = this.generation; + const task = this.queue.then(() => { + if (generation !== this.generation) { + throw new Error("A825 disconnected before queued transfer"); + } + return action(); + }); + this.queue = task.then( + () => undefined, + () => undefined, + ); + return task; + } + + private async send(frame: Uint8Array): Promise { + await this.device.sendFeatureReport( + INSTANT_REPORT_ID, + frame.slice(1).buffer, + ); + } + + private async readStatusReport(): Promise { + const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); + return statusBytes(view, INSTANT_REPORT_ID); + } + + /** Read one byte from the configuration image, using the vendor read path. */ + private async readByte(address: number): Promise { + const setup = instantBlockReadFrames(address, 1); + for (const frame of setup) await this.send(frame); + await this.send(instantBlockReadByteFrame(address, 0, 1)); + const closeWindow = instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + address & 0xff, + (address >>> 8) & 0xff, + 0, + 0, + ]); + let report: Uint8Array; + try { + report = await this.readStatusReport(); + } catch (error) { + // The read window is open even when the reply is lost. Try to close it, + // but keep the original failure. + await this.send(closeWindow).catch(() => undefined); + throw error; + } + // The vendor closes the read window after every byte. + await this.send(closeWindow); + const full = new Uint8Array(report.length + 1); + full[0] = INSTANT_REPORT_ID; + full.set(report, 1); + const value = full.length > 1 ? full[1] : null; + if (value == null) throw new Error("A825 config read returned no data"); + return value; + } + + /** + * Read the stored configuration image. A full read is 0x1000 one-byte + * transfers; read a small range when only a few bytes matter. + */ + async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { + if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { + throw new RangeError(`Invalid A825 config length: ${length}`); + } + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const bytes = new Uint8Array(length); + for (let address = 0; address < length; address += 1) { + bytes[address] = await this.readByte(address); + } + if (generation !== this.generation) { + throw new Error("A825 disconnected during the configuration read"); + } + const image = decodeInstantConfig(bytes); + if (length === INSTANT_CONFIG_LENGTH) this.config = image; + return { + bytes: image.bytes.slice(), + lightingDirectionByte: image.lightingDirectionByte, + }; + }); + } + + async readStatus(): Promise { + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const report = await this.readStatusReport(); + if (generation !== this.generation) { + throw new Error("A825 disconnected during the status read"); + } + this.status = new Uint8Array(report.length + 1); + this.status[0] = INSTANT_REPORT_ID; + this.status.set(report, 1); + const decoded = decodeInstantStatus(this.status); + + return { + brand: "Sades", + name: this.device.productName || "Sades Kaze", + ui: { + family: "sades-a825", + settingsReady: false, + valuesVerified: false, + pollingReadOnly: true, + hideProcessingCard: true, + hideSignalCard: true, + hideSleepCard: true, + defaultDisplayName: "Sades Kaze", + statusNote: + "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", + }, + batteryPercent: null, + batteryState: "Unknown", + dpi: 0, + pollingRateHz: 0, + supportedPollingRates: [...INSTANT_POLLING_RATES], + activeProfile: null, + connectionType: "Wired", + connectionDetail: "USB", + liftOffDistance: null, + firmware: + decoded?.magicOk + ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] + : [], + }; + }); + } + + /** + * Send the vendor's live DPI command. Kept for protocol tooling; the panel + * does not expose it because this firmware gives no read-back for the value. + */ + async setLiveDpi(dpi: number, mode = 0): Promise { + return this.serialize(async () => { + await this.open(); + for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); + return dpi; + }); + } +} diff --git a/src/instant/protocol.test.ts b/src/instant/protocol.test.ts index a354fed..ac8350a 100644 --- a/src/instant/protocol.test.ts +++ b/src/instant/protocol.test.ts @@ -1,117 +1,121 @@ -import assert from "node:assert/strict"; -import test from "node:test"; - -import { - decodeInstantConfig, - decodeInstantReadByte, - decodeInstantStatus, - INSTANT_CONFIG, - INSTANT_DPI_GEARS, - INSTANT_REPORT_ID, - instantBlockReadByteFrame, - instantBlockReadFrames, - instantBlockWriteFrames, - instantDpiFrames, - instantDpiGearIndex, - instantFrame, - instantModeFrames, -} from "./protocol.ts"; - -function hex(frame: Uint8Array): string { - return Buffer.from(frame).toString("hex"); -} - -test("instantFrame pads to an 8-byte report 7 frame", () => { - assert.equal(hex(instantFrame(0x18, [0x03, 0])), "0718030000000000"); - assert.equal(instantFrame(0x18).length, 8); - assert.equal(instantFrame(0x18)[0], INSTANT_REPORT_ID); - assert.throws(() => instantFrame(0x18, [1, 2, 3, 4, 5, 6, 7]), RangeError); -}); - -test("block write matches the vendor's captured Apply frames", () => { - const frames = instantBlockWriteFrames(0x0000, [0x5a, 0x03]); - assert.deepEqual(frames.map(hex), [ - "0718030000005a01", - "0718030100000301", - "0718090000000001", - "0718000000000000", - ]); - const high = instantBlockWriteFrames(0x003a, [0x0b]); - assert.equal(hex(high[0]!), "071803003a000b00"); - assert.equal(hex(high[1]!), "071809003a000000"); -}); - -test("block read uses little-endian addresses and a final commit", () => { - const frames = instantBlockReadFrames(0x003a, 2); - assert.equal(frames.length, 3); - assert.equal(hex(frames[0]!), "071803003a000001"); - assert.equal(hex(frames[1]!), "071803013a000001"); - assert.equal(hex(frames[2]!), "071800003a000000"); - assert.equal(hex(instantBlockReadByteFrame(0x003a, 1, 2)), "071805013a000001"); - assert.equal(decodeInstantReadByte(new Uint8Array([0x07, 0x0b])), 0x0b); - assert.equal(decodeInstantReadByte(new Uint8Array([0x07])), null); -}); - -test("DPI frames match the vendor's 0x12 encoding", () => { - assert.deepEqual(instantDpiFrames(800).map(hex), [ - "0712640000000000", - "0711000000000000", - ]); - assert.deepEqual(instantDpiFrames(1600, 1).map(hex), [ - "0712006400000000", - "0711000000000000", - ]); - assert.throws(() => instantDpiFrames(300, 1), RangeError); - assert.throws(() => instantDpiFrames(123), RangeError); -}); - -test("mode frames enter and leave block mode", () => { - assert.equal(hex(instantModeFrames(true)[0]!), "0718100000000000"); - assert.equal(hex(instantModeFrames(false)[0]!), "0718000000000000"); -}); - -test("config decode keeps the lighting byte raw", () => { - // Ghidra: 0x3A packs light_direction/light_symmetry, not the polling rate. - const config = decodeInstantConfig(new Uint8Array([...new Uint8Array(0x3a), 0x0b])); - assert.equal(config.lightingDirectionByte, 0x0b); - assert.equal(config.bytes[0x3a], 0x0b); -}); - -test("DPI table is the vendor's 23-value table", () => { - assert.equal(INSTANT_DPI_GEARS.length, 23); - assert.equal(instantDpiGearIndex(200), 1); - assert.equal(instantDpiGearIndex(12800), 23); - assert.equal(instantDpiGearIndex(300), null); -}); - -test("status decode keeps the vendor block markers", () => { - const report = new Uint8Array([ - 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, - 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - ]); - assert.deepEqual(decodeInstantStatus(report), { - firmware: 0x0954, - state: 0x00, - sensorCpi: 0x0626, - magicOk: true, - }); - assert.equal(decodeInstantStatus(new Uint8Array(8)), null); - const broken = report.slice(); - broken[16] = 0x00; - assert.equal(decodeInstantStatus(broken)?.magicOk, false); -}); - -test("config address map is the vendor's Apply layout", () => { - assert.deepEqual(INSTANT_CONFIG, { - header: 0x0000, - keymap: 0x0007, - stageEnable: 0x001c, - stageColorsA: 0x0020, - stageColorsB: 0x0028, - sensor: 0x0030, - lightingDirection: 0x003a, - lighting: 0x003e, - trailer: 0x0f80, - }); -}); +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + decodeInstantConfig, + decodeInstantReadByte, + decodeInstantStatus, + INSTANT_CONFIG, + INSTANT_DPI_GEARS, + INSTANT_REPORT_ID, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantBlockWriteFrames, + instantDpiFrames, + instantDpiGearIndex, + instantFrame, + instantModeFrames, +} from "./protocol.ts"; + +function hex(frame: Uint8Array): string { + return Buffer.from(frame).toString("hex"); +} + +test("instantFrame pads to an 8-byte report 7 frame", () => { + assert.equal(hex(instantFrame(0x18, [0x03, 0])), "0718030000000000"); + assert.equal(instantFrame(0x18).length, 8); + assert.equal(instantFrame(0x18)[0], INSTANT_REPORT_ID); + assert.throws(() => instantFrame(0x18, [1, 2, 3, 4, 5, 6, 7]), RangeError); +}); + +test("block write matches the vendor's captured Apply frames", () => { + const frames = instantBlockWriteFrames(0x0000, [0x5a, 0x03]); + assert.deepEqual(frames.map(hex), [ + "0718030000005a01", + "0718030100000301", + "0718090000000001", + "0718000000000000", + ]); + const high = instantBlockWriteFrames(0x003a, [0x0b]); + assert.equal(hex(high[0]!), "071803003a000b00"); + assert.equal(hex(high[1]!), "071809003a000000"); +}); + +test("block read uses little-endian addresses and a final commit", () => { + const frames = instantBlockReadFrames(0x003a, 2); + assert.equal(frames.length, 3); + assert.equal(hex(frames[0]!), "071803003a000001"); + assert.equal(hex(frames[1]!), "071803013a000001"); + assert.equal(hex(frames[2]!), "071800003a000000"); + assert.equal(hex(instantBlockReadByteFrame(0x003a, 1, 2)), "071805013a000001"); + assert.throws(() => instantBlockReadByteFrame(0x003a, 1, 1), RangeError); + assert.throws(() => instantBlockReadByteFrame(0x10000, 0, 1), RangeError); + assert.throws(() => instantBlockReadFrames(0x003a, Number.NaN), RangeError); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07, 0x0b])), 0x0b); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07])), null); +}); + +test("DPI frames match the vendor's 0x12 encoding", () => { + assert.deepEqual(instantDpiFrames(800).map(hex), [ + "0712640000000000", + "0711000000000000", + ]); + assert.deepEqual(instantDpiFrames(1600, 1).map(hex), [ + "0712006400000000", + "0711000000000000", + ]); + assert.throws(() => instantDpiFrames(300, 1), RangeError); + assert.throws(() => instantDpiFrames(123), RangeError); +}); + +test("mode frames enter and leave block mode", () => { + assert.equal(hex(instantModeFrames(true)[0]!), "0718100000000000"); + assert.equal(hex(instantModeFrames(false)[0]!), "0718000000000000"); +}); + +test("config decode keeps the lighting byte raw", () => { + // Ghidra: 0x3A packs light_direction/light_symmetry, not the polling rate. + const config = decodeInstantConfig(new Uint8Array([...new Uint8Array(0x3a), 0x0b])); + assert.equal(config.lightingDirectionByte, 0x0b); + assert.equal(config.bytes[0x3a], 0x0b); + assert.equal(decodeInstantConfig(new Uint8Array(0x3a)).lightingDirectionByte, null); +}); + +test("DPI table is the vendor's 23-value table", () => { + assert.equal(INSTANT_DPI_GEARS.length, 23); + assert.equal(instantDpiGearIndex(200), 1); + assert.equal(instantDpiGearIndex(12800), 23); + assert.equal(instantDpiGearIndex(300), null); +}); + +test("status decode keeps the vendor block markers", () => { + const report = new Uint8Array([ + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + ]); + assert.deepEqual(decodeInstantStatus(report), { + firmware: 0x0954, + state: 0x00, + sensorCpi: 0x0626, + magicOk: true, + }); + assert.equal(decodeInstantStatus(new Uint8Array(8)), null); + const broken = report.slice(); + broken[16] = 0x00; + assert.equal(decodeInstantStatus(broken)?.magicOk, false); +}); + +test("config address map is the vendor's Apply layout", () => { + assert.deepEqual(INSTANT_CONFIG, { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, + }); +}); diff --git a/src/instant/protocol.ts b/src/instant/protocol.ts index df5e954..e9f0b9a 100644 --- a/src/instant/protocol.ts +++ b/src/instant/protocol.ts @@ -1,339 +1,356 @@ -/** - * Instant Microelectronics A825 configuration protocol. - * - * Reverse-engineered from the vendor control app shipped for the Sades Kaze - * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` - * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a - * Sades Kaze on VID 0x30FA / PID 0x1440. - * - * Transport - * --------- - * The control collection is usage page 0xFF01, usage 1, on interface 1. Its - * only feature report is report ID 7. The vendor app and the device both use - * 8-byte feature reports: - * - * [0x07, command, a, b, c, d, e, f] - * - * The same report also carries a 32-byte status block that the device returns - * from a feature read; only the first eight bytes are used for command replies. - * - * Block access (command 0x18) - * --------------------------- - * The device exposes a 16-bit, little-endian addressed configuration memory. - * A block is written as one frame per byte, then finished and committed: - * - * 07 18 03 - * 07 18 09 00 00 - * 07 18 00 00 00 00 - * - * A byte is read by issuing the same address/length setup and then one frame - * per byte: - * - * 07 18 03 00 00 - * 07 18 00 00 00 00 - * 07 18 05 00 → reply byte 1 - * 07 18 00 00 00 00 - * - * Verified on hardware: writing the byte at 0x3A and reading it back returns - * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not - * the polling rate. The 0x0000-0x0FFF image is readable with - * `instantBlockReadFrames`. - * - * Direct commands - * --------------- - * The vendor app also writes a DPI value and a button map directly: - * - * 07 12 00 00 00 00 00 (mode 0) - * 07 12 ... (other modes) - * 07 11 00 ... commit - * 07 09 ... button map - * 07 17 ... 16-bit key/function code - * 07 13 ... lighting/mode - * - * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the - * 0x0F80 trailer). The direct commands above are read from the vendor code; - * sending 0x12 on the tested unit changed neither the stored image nor the - * status block. - */ - -export const INSTANT_VENDOR_ID = 0x30fa; - -/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ -export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ - 0x1440, 0x1e01, 0x7f7f, -]); - -export const INSTANT_USAGE_PAGE = 0xff01; -export const INSTANT_USAGE = 0x01; -export const INSTANT_INTERFACE = 1; - -export const INSTANT_REPORT_ID = 0x07; -export const INSTANT_FRAME_LENGTH = 8; -/** Status block returned by a feature read on report 7. */ -export const INSTANT_STATUS_LENGTH = 32; - -export const INSTANT_COMMAND = { - block: 0x18, - dpi: 0x12, - apply: 0x11, - buttonMap: 0x09, - keyCode: 0x17, - notice: 0x13, -} as const; - -export const INSTANT_BLOCK = { - write: 0x03, - read: 0x05, - finish: 0x09, - commit: 0x00, - mode: 0x10, -} as const; - -/** - * Configuration image addresses written by the vendor app's - * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes - * between blocks are untouched. - */ -export const INSTANT_CONFIG = { - header: 0x0000, - keymap: 0x0007, - stageEnable: 0x001c, - stageColorsA: 0x0020, - stageColorsB: 0x0028, - sensor: 0x0030, - lightingDirection: 0x003a, - lighting: 0x003e, - trailer: 0x0f80, -} as const; - -/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ -export const INSTANT_CONFIG_LENGTH = 0x1000; - -/** - * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array - * index + 1 is the on-wire gear index (the value the vendor app stores in a - * DPI stage); the second number in the INI is a separate firmware code. - */ -export const INSTANT_DPI_GEARS: readonly number[] = [ - 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, - 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, -]; - -export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; - -export function instantDpiGearIndex(dpi: number): number | null { - const index = INSTANT_DPI_GEARS.indexOf(dpi); - return index < 0 ? null : index + 1; -} - -function byte(value: number, name: string): number { - if (!Number.isInteger(value) || value < 0 || value > 0xff) { - throw new RangeError(`${name} is not a byte: ${value}`); - } - return value; -} - -/** Build one 8-byte report. `params` fills bytes 2..7. */ -export function instantFrame( - command: number, - params: readonly number[] = [], -): Uint8Array { - if (params.length > 6) { - throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); - } - const frame = new Uint8Array(INSTANT_FRAME_LENGTH); - frame[0] = INSTANT_REPORT_ID; - frame[1] = byte(command, "command"); - params.forEach((value, index) => { - frame[2 + index] = byte(value, `parameter ${index}`); - }); - return frame; -} - -/** Frames that write `data` to `address`, followed by finish and commit. */ -export function instantBlockWriteFrames( - address: number, - data: readonly number[], -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (data.length === 0 || data.length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${data.length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = data.length - 1; - const frames = data.map((value, index) => - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - byte(value, `data byte ${index}`), - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.finish, - 0, - low, - high, - 0, - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frames that prepare and read `length` bytes from `address`. */ -export function instantBlockReadFrames( - address: number, - length: number, -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (length < 1 || length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = length - 1; - const frames: Uint8Array[] = []; - for (let index = 0; index < length; index += 1) { - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - 0, - last, - ]), - ); - } - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frame that requests byte `index` of the prepared read block. */ -export function instantBlockReadByteFrame( - address: number, - index: number, - length: number, -): Uint8Array { - return instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.read, - index, - address & 0xff, - (address >>> 8) & 0xff, - 0, - length - 1, - ]); -} - -/** The value returned by a read byte frame lives at report byte 1. */ -export function decodeInstantReadByte(report: Uint8Array): number | null { - return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; -} - -/** Frames that set a live DPI value and commit it. */ -export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { - const gear = instantDpiGearIndex(dpi); - if (gear == null) { - throw new RangeError(`Unsupported A825 DPI: ${dpi}`); - } - if (mode === 0) { - return [ - instantFrame(INSTANT_COMMAND.dpi, [Math.round(dpi / 8), 0, 0, 0, 0, 0]), - instantFrame(INSTANT_COMMAND.apply), - ]; - } - const units = Math.round(dpi / 16); - return [ - instantFrame(INSTANT_COMMAND.dpi, [ - (units >>> 8) & 0xff, - units & 0xff, - 0, - 0, - 0, - 0, - ]), - instantFrame(INSTANT_COMMAND.apply), - ]; -} - -/** Enter or leave the block-write mode used at the end of an Apply. */ -export function instantModeFrames(enter: boolean): Uint8Array[] { - return [ - instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), - ]; -} - -export interface InstantConfigImage { - /** Raw 0x0000-0x02FF configuration image. */ - bytes: Uint8Array; - /** - * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and - * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); - * it is NOT the polling rate. Kept raw until the layout is fully named. - */ - lightingDirectionByte: number; -} - -export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { - if (bytes.length < INSTANT_CONFIG.lightingDirection + 1) { - throw new RangeError("Instant config image is truncated"); - } - return { - bytes, - lightingDirectionByte: bytes[INSTANT_CONFIG.lightingDirection]!, - }; -} - -export interface InstantStatus { - /** Firmware/build word at bytes 2-3, big-endian (0x0954 on the Kaze). */ - firmware: number; - /** State byte 1; changes with device activity. */ - state: number; - /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ - sensorCpi: number; - /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ - magicOk: boolean; -} - -export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { - if (report.length < 20) return null; - const offset = report[0] === INSTANT_REPORT_ID ? 1 : 0; - if (report.length < offset + 19) return null; - return { - firmware: report[offset + 1]! | (report[offset + 2]! << 8), - state: report[offset]!, - sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), - magicOk: - report[offset + 15] === 0x24 && - report[offset + 16] === 0x5a && - report[offset + 17] === 0xa5, - }; -} +/** + * Instant Microelectronics A825 configuration protocol. + * + * Reverse-engineered from the vendor control app shipped for the Sades Kaze + * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` + * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a + * Sades Kaze on VID 0x30FA / PID 0x1440. + * + * Transport + * --------- + * The control collection is usage page 0xFF01, usage 1, on interface 1. Its + * only feature report is report ID 7. The vendor app and the device both use + * 8-byte feature reports: + * + * [0x07, command, a, b, c, d, e, f] + * + * The same report also carries a 32-byte status block that the device returns + * from a feature read; only the first eight bytes are used for command replies. + * + * Block access (command 0x18) + * --------------------------- + * The device exposes a 16-bit, little-endian addressed configuration memory. + * A block is written as one frame per byte, then finished and committed: + * + * 07 18 03 + * 07 18 09 00 00 + * 07 18 00 00 00 00 + * + * A byte is read by issuing the same address/length setup and then one frame + * per byte: + * + * 07 18 03 00 00 + * 07 18 00 00 00 00 + * 07 18 05 00 → reply byte 1 + * 07 18 00 00 00 00 + * + * Verified on hardware: writing the byte at 0x3A and reading it back returns + * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not + * the polling rate. The 0x0000-0x0FFF image is readable with + * `instantBlockReadFrames`. + * + * Direct commands + * --------------- + * The vendor app also writes a DPI value and a button map directly: + * + * 07 12 00 00 00 00 00 (mode 0) + * 07 12 ... (other modes) + * 07 11 00 ... commit + * 07 09 ... button map + * 07 17 ... 16-bit key/function code + * 07 13 ... lighting/mode + * + * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the + * 0x0F80 trailer). The direct commands above are read from the vendor code; + * sending 0x12 on the tested unit changed neither the stored image nor the + * status block. + */ + +export const INSTANT_VENDOR_ID = 0x30fa; + +/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ +export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ + 0x1440, 0x1e01, 0x7f7f, +]); + +export const INSTANT_USAGE_PAGE = 0xff01; +export const INSTANT_USAGE = 0x01; +export const INSTANT_INTERFACE = 1; + +export const INSTANT_REPORT_ID = 0x07; +export const INSTANT_FRAME_LENGTH = 8; +/** Status block returned by a feature read on report 7. */ +export const INSTANT_STATUS_LENGTH = 32; + +export const INSTANT_COMMAND = { + block: 0x18, + dpi: 0x12, + apply: 0x11, + buttonMap: 0x09, + keyCode: 0x17, + notice: 0x13, +} as const; + +export const INSTANT_BLOCK = { + write: 0x03, + read: 0x05, + finish: 0x09, + commit: 0x00, + mode: 0x10, +} as const; + +/** + * Configuration image addresses written by the vendor app's + * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes + * between blocks are untouched. + */ +export const INSTANT_CONFIG = { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, +} as const; + +/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ +export const INSTANT_CONFIG_LENGTH = 0x1000; + +/** + * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array + * index + 1 is the on-wire gear index (the value the vendor app stores in a + * DPI stage); the second number in the INI is a separate firmware code. + */ +export const INSTANT_DPI_GEARS: readonly number[] = [ + 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, + 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, +]; + +export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; + +export function instantDpiGearIndex(dpi: number): number | null { + const index = INSTANT_DPI_GEARS.indexOf(dpi); + return index < 0 ? null : index + 1; +} + +function byte(value: number, name: string): number { + if (!Number.isInteger(value) || value < 0 || value > 0xff) { + throw new RangeError(`${name} is not a byte: ${value}`); + } + return value; +} + +/** Build one 8-byte report. `params` fills bytes 2..7. */ +export function instantFrame( + command: number, + params: readonly number[] = [], +): Uint8Array { + if (params.length > 6) { + throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); + } + const frame = new Uint8Array(INSTANT_FRAME_LENGTH); + frame[0] = INSTANT_REPORT_ID; + frame[1] = byte(command, "command"); + params.forEach((value, index) => { + frame[2 + index] = byte(value, `parameter ${index}`); + }); + return frame; +} + +/** Frames that write `data` to `address`, followed by finish and commit. */ +export function instantBlockWriteFrames( + address: number, + data: readonly number[], +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (data.length === 0 || data.length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${data.length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = data.length - 1; + const frames = data.map((value, index) => + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + byte(value, `data byte ${index}`), + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.finish, + 0, + low, + high, + 0, + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frames that prepare and read `length` bytes from `address`. */ +export function instantBlockReadFrames( + address: number, + length: number, +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (!Number.isInteger(length) || length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = length - 1; + const frames: Uint8Array[] = []; + for (let index = 0; index < length; index += 1) { + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + 0, + last, + ]), + ); + } + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frame that requests byte `index` of the prepared read block. */ +export function instantBlockReadByteFrame( + address: number, + index: number, + length: number, +): Uint8Array { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (!Number.isInteger(length) || length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + if (!Number.isInteger(index) || index < 0 || index >= length) { + throw new RangeError(`Instant block index ${index} is outside a ${length}-byte block`); + } + return instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.read, + index, + address & 0xff, + (address >>> 8) & 0xff, + 0, + length - 1, + ]); +} + +/** The value returned by a read byte frame lives at report byte 1. */ +export function decodeInstantReadByte(report: Uint8Array): number | null { + return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; +} + +/** Frames that set a live DPI value and commit it. */ +export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { + const gear = instantDpiGearIndex(dpi); + if (gear == null) { + throw new RangeError(`Unsupported A825 DPI: ${dpi}`); + } + if (mode === 0) { + const units = Math.round(dpi / 8); + if (units > 0xff) { + throw new RangeError( + `A825 mode 0 stores DPI/8 in one byte; ${dpi} needs the 16-bit mode`, + ); + } + return [ + instantFrame(INSTANT_COMMAND.dpi, [units, 0, 0, 0, 0, 0]), + instantFrame(INSTANT_COMMAND.apply), + ]; + } + const units = Math.round(dpi / 16); + return [ + instantFrame(INSTANT_COMMAND.dpi, [ + (units >>> 8) & 0xff, + units & 0xff, + 0, + 0, + 0, + 0, + ]), + instantFrame(INSTANT_COMMAND.apply), + ]; +} + +/** Enter or leave the block-write mode used at the end of an Apply. */ +export function instantModeFrames(enter: boolean): Uint8Array[] { + return [ + instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), + ]; +} + +export interface InstantConfigImage { + /** Bytes read from the configuration image; the array length is the requested range. */ + bytes: Uint8Array; + /** + * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and + * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); + * it is NOT the polling rate. Kept raw until the layout is fully named. + */ + lightingDirectionByte: number | null; +} + +export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { + return { + bytes, + lightingDirectionByte: + bytes.length > INSTANT_CONFIG.lightingDirection + ? bytes[INSTANT_CONFIG.lightingDirection]! + : null, + }; +} + +export interface InstantStatus { + /** Firmware/build word at bytes 2-3, little-endian (0x0954 on the Kaze). */ + firmware: number; + /** State byte 1; changes with device activity. */ + state: number; + /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ + sensorCpi: number; + /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ + magicOk: boolean; +} + +export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { + if (report.length < 20) return null; + const hasReportId = report.length === INSTANT_STATUS_LENGTH; + const offset = hasReportId ? 1 : 0; + if (hasReportId && report[0] !== INSTANT_REPORT_ID) return null; + if (report.length < offset + 19) return null; + return { + firmware: report[offset + 1]! | (report[offset + 2]! << 8), + state: report[offset]!, + sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), + magicOk: + report[offset + 15] === 0x24 && + report[offset + 16] === 0x5a && + report[offset + 17] === 0xa5, + }; +} From 4f94b7da9e0f80dbfdf8fb62aefea3eb939417c9 Mon Sep 17 00:00:00 2001 From: benjamin <118074832+its-benjamin@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:20:25 +0700 Subject: [PATCH 6/6] style(instant): keep edited files on LF - Normalized the files touched by the review fixes to LF; content unchanged. --- docs/a825-config-records.md | 176 +++---- docs/devdock-functions.md | 196 ++++---- docs/instant-a825.md | 404 +++++++-------- src/drivers/instant/a825-hid.test.ts | 276 +++++------ src/drivers/instant/a825-hid.ts | 584 +++++++++++----------- src/instant/protocol.test.ts | 242 ++++----- src/instant/protocol.ts | 712 +++++++++++++-------------- 7 files changed, 1295 insertions(+), 1295 deletions(-) diff --git a/docs/a825-config-records.md b/docs/a825-config-records.md index bd53fb9..1f8f2f4 100644 --- a/docs/a825-config-records.md +++ b/docs/a825-config-records.md @@ -1,88 +1,88 @@ -# A825 configuration records - -Generated from Ghidra's decompilation of `A825_BuildConfigImage` (0x481400) -in `DevDock.exe` (SHA-256 `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`). -The map key is the record id that `A825_BuildConfigImage` uses. The mapping from each record id to a byte offset in the configuration image is not resolved; see `docs/devdock-functions.md`. - -| Record id | Value | -| --- | --- | -| `0x000` | `0x5a` | -| `0x001` | `(-(cVar20 != '\0') & 3U) + (*(byte *)((int)this + 0x74c) & 3) * ' '` | -| `0x002` | `0xa5` | -| `0x003` | `(byte)*(undefined4 *)((int)this + 0x8068)` | -| `0x004` | `(byte)(*(int *)((int)this + 0x8068) + (*(int *)((int)this + 0x8068) >> 0x1f & 0xffU) >> 8)` | -| `0x005` | `(byte)*(undefined4 *)((int)this + 0x8064)` | -| `0x006` | `(byte)(*(int *)((int)this + 0x8064) + (*(int *)((int)this + 0x8064) >> 0x1f & 0xffU) >> 8)` | -| `0x007` | `*(byte *)((int)this + 0x802c)` | -| `0x008` | `*(byte *)((int)this + 0x802d)` | -| `0x009` | `*(byte *)((int)this + 0x802e)` | -| `0x00A` | `*(byte *)((int)this + 0x802f)` | -| `0x00B` | `*(byte *)((int)this + 0x8030)` | -| `0x00C` | `*(byte *)((int)this + 0x8031)` | -| `0x00D` | `*(byte *)((int)this + 0x8032)` | -| `0x00E` | `*(byte *)((int)this + 0x8033)` | -| `0x00F` | `*(byte *)((int)this + 0x8034)` | -| `0x010` | `0` | -| `0x012` | `0` | -| `0x013` | `(((((*(byte *)((int)this + 0x7a7) >> 4 & 1) * '\x02' + (*(byte *)((int)this + 0x7a6) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a5) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a4) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a3) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a2) >> 4 & 1)` | -| `0x014` | `(((*(byte *)((int)this + 0x8104) & 3) * '\x02' + (*(byte *)((int)this + 0x8298) & 1)) * '\x02' + (*(byte *)((int)this + 0x829d) & 1)) * '\x02' + (*(byte *)((int)this + 0x829c) & 1) ` | -| `0x015` | `*(char *)((int)this + 0x7a4) * '\x10' + (*(byte *)((int)this + 0x7a5) & 0xf)` | -| `0x016` | `*(char *)((int)this + 0x7a6) * '\x10' + (*(byte *)((int)this + 0x7a7) & 0xf)` | -| `0x017` | `*(byte *)((int)this + 0x750) & 7` | -| `0x018` | `*(byte *)((int)this + 0x82a0) & 0x3f` | -| `0x019` | `(byte)iVar25` | -| `0x01B` | `(byte)(iVar25 + (iVar25 >> 0x1f & 0xffU) >> 8)` | -| `0x01C` | `((*(char *)((int)this + 0x82a6) * '\b' + (*(byte *)((int)this + 0x829e) & 7)) * '\x02' + *(char *)((int)this + 0x82a5)) * '\b' + (local_2cd & 7)` | -| `0x01D` | `*(byte *)((int)this + 0x7a8)` | -| `0x01E` | `0` | -| `0x020` | `(byte)*(undefined4 *)((int)this + 0x758) & 0xf` | -| `0x021` | `(byte)*(undefined4 *)((int)this + 0x75c) & 0xf` | -| `0x022` | `(byte)*(undefined4 *)((int)this + 0x760) & 0xf` | -| `0x023` | `(byte)*(undefined4 *)((int)this + 0x764) & 0xf` | -| `0x024` | `(byte)*(undefined4 *)((int)this + 0x768) & 0xf` | -| `0x025` | `(byte)*(undefined4 *)((int)this + 0x76c) & 0xf` | -| `0x026` | `(byte)*(undefined4 *)((int)this + 0x770) & 0xf` | -| `0x027` | `(byte)*(undefined4 *)((int)this + 0x774) & 0xf` | -| `0x028` | `(byte)*(undefined4 *)((int)this + 0x778) & 0xf` | -| `0x029` | `(byte)*(undefined4 *)((int)this + 0x77c) & 0xf` | -| `0x02A` | `(byte)*(undefined4 *)((int)this + 0x780) & 0xf` | -| `0x02B` | `(byte)*(undefined4 *)((int)this + 0x784) & 0xf` | -| `0x02C` | `(byte)*(undefined4 *)((int)this + 0x788) & 0xf` | -| `0x02D` | `(byte)*(undefined4 *)((int)this + 0x78c) & 0xf` | -| `0x02E` | `(byte)*(undefined4 *)((int)this + 0x790) & 0xf` | -| `0x02F` | `(byte)*(undefined4 *)((int)this + 0x794) & 0xf` | -| `0x030` | `(byte)*(undefined4 *)((int)this + 0x798) & 0xf` | -| `0x031` | `0` | -| `0x032` | `0` | -| `0x033` | `0` | -| `0x035` | `0` | -| `0x036` | `0` | -| `0x037` | `0` | -| `0x038` | `0` | -| `0x039` | `0` | -| `0x03A` | `*(byte *)((int)this + 0x8035)` | -| `0x03B` | `*(byte *)((int)this + 0x8036)` | -| `0x03C` | `*(byte *)((int)this + 0x8037)` | -| `0x03D` | `0` | -| `0x03E` | `0` | -| `0x03F` | `((*(char *)((int)this + 0x810c) * '\x04' + *(char *)((int)this + 0x8114)) * '\x04' + *(char *)((int)this + 0x8115)) * '\b' + *(char *)((int)this + 0x82ec)` | -| `0x040` | `(*(char *)((int)this + 0x82b4) * '\x02' + *(char *)((int)this + 0x82bc)) * ' ' + *(char *)((int)this + 0x82c4)` | -| `0x042` | `(*(char *)((int)this + 0x82b8) * '\x02' + *(char *)((int)this + 0x82c0)) * ' ' + *(char *)((int)this + 0x82c8)` | -| `0x043` | `(((*(char *)((int)this + 0x80fc) * '\x02' + *(char *)((int)this + 0x82f0)) * '\x02' + *(char *)((int)this + 0x82f4)) * '\x02' + *(char *)((int)this + 0x80f4)) * '\x10' + cVar20` | -| `0x044` | `(*(char *)((int)this + 0x908) * '\x02' + *(char *)((int)this + 0x86c)) * ' ' + *(char *)((int)this + 0x803a)` | -| `0x045` | `(*(char *)((int)this + 0x909) * '\x02' + *(char *)((int)this + 0x870)) * ' ' + *(char *)((int)this + 0x803b)` | -| `0x046` | `(*(char *)((int)this + 0x90a) * '\x02' + *(char *)((int)this + 0x874)) * ' ' + *(char *)((int)this + 0x803c)` | -| `0x047` | `(*(char *)((int)this + 0x90b) * '\x02' + *(char *)((int)this + 0x878)) * ' ' + *(char *)((int)this + 0x803d)` | -| `0x048` | `((char)*(undefined4 *)((int)this + 0x87c) + *(char *)((int)this + 0x90c) * '\x02') * ' ' + *(char *)((int)this + 0x803e)` | -| `0x049` | `((char)*(undefined4 *)((int)this + 0x880) + *(char *)((int)this + 0x90d) * '\x02') * ' ' + *(char *)((int)this + 0x803f)` | -| `0x04A` | `((char)*(undefined4 *)((int)this + 0x884) + *(char *)((int)this + 0x90e) * '\x02') * ' ' + *(char *)((int)this + 0x8040)` | -| `0x04B` | `((char)*(undefined4 *)((int)this + 0x88c) + *(char *)((int)this + 0x910) * '\x02') * ' ' + *(char *)((int)this + 0x8042)` | -| `0x04D` | `((char)*(undefined4 *)((int)this + 0x890) + *(char *)((int)this + 0x911) * '\x02') * ' ' + *(char *)((int)this + 0x8043)` | -| `0x04E` | `((char)*(undefined4 *)((int)this + 0x894) + *(char *)((int)this + 0x912) * '\x02') * ' ' + *(char *)((int)this + 0x8044)` | -| `0x04F` | `((char)*(undefined4 *)((int)this + 0x89c) + *(char *)((int)this + 0x914) * '\x02') * ' ' + *(char *)((int)this + 0x8048)` | -| `0x051` | `((char)*(undefined4 *)((int)this + 0x8a0) + *(char *)((int)this + 0x915) * '\x02') * ' ' + *(char *)((int)this + 0x8049)` | -| `0x052` | `((char)*(undefined4 *)((int)this + 0x8a4) + *(char *)((int)this + 0x916) * '\x02') * ' ' + *(char *)((int)this + 0x804a)` | -| `0x053` | `((char)*(undefined4 *)((int)this + 0x8ac) + *(char *)((int)this + 0x918) * '\x02') * ' ' + *(char *)((int)this + 0x804c)` | -| `0x055` | `((char)*(undefined4 *)((int)this + 0x8b0) + *(char *)((int)this + 0x919) * '\x02') * ' ' + *(char *)((int)this + 0x804d)` | -| `0x056` | `((char)*(undefined4 *)((int)this + 0x8b4) + *(char *)((int)this + 0x91a) * '\x02') * ' ' + *(char *)((int)this + 0x804e)` | -| `0x057` | `((char)*(undefined4 *)((int)this + 0x8bc) + *(char *)((int)this + 0x91c) * '\x02') * ' ' + *(char *)((int)this + 0x8050)` | +# A825 configuration records + +Generated from Ghidra's decompilation of `A825_BuildConfigImage` (0x481400) +in `DevDock.exe` (SHA-256 `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`). +The map key is the record id that `A825_BuildConfigImage` uses. The mapping from each record id to a byte offset in the configuration image is not resolved; see `docs/devdock-functions.md`. + +| Record id | Value | +| --- | --- | +| `0x000` | `0x5a` | +| `0x001` | `(-(cVar20 != '\0') & 3U) + (*(byte *)((int)this + 0x74c) & 3) * ' '` | +| `0x002` | `0xa5` | +| `0x003` | `(byte)*(undefined4 *)((int)this + 0x8068)` | +| `0x004` | `(byte)(*(int *)((int)this + 0x8068) + (*(int *)((int)this + 0x8068) >> 0x1f & 0xffU) >> 8)` | +| `0x005` | `(byte)*(undefined4 *)((int)this + 0x8064)` | +| `0x006` | `(byte)(*(int *)((int)this + 0x8064) + (*(int *)((int)this + 0x8064) >> 0x1f & 0xffU) >> 8)` | +| `0x007` | `*(byte *)((int)this + 0x802c)` | +| `0x008` | `*(byte *)((int)this + 0x802d)` | +| `0x009` | `*(byte *)((int)this + 0x802e)` | +| `0x00A` | `*(byte *)((int)this + 0x802f)` | +| `0x00B` | `*(byte *)((int)this + 0x8030)` | +| `0x00C` | `*(byte *)((int)this + 0x8031)` | +| `0x00D` | `*(byte *)((int)this + 0x8032)` | +| `0x00E` | `*(byte *)((int)this + 0x8033)` | +| `0x00F` | `*(byte *)((int)this + 0x8034)` | +| `0x010` | `0` | +| `0x012` | `0` | +| `0x013` | `(((((*(byte *)((int)this + 0x7a7) >> 4 & 1) * '\x02' + (*(byte *)((int)this + 0x7a6) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a5) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a4) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a3) >> 4 & 1)) * '\x02' + (*(byte *)((int)this + 0x7a2) >> 4 & 1)` | +| `0x014` | `(((*(byte *)((int)this + 0x8104) & 3) * '\x02' + (*(byte *)((int)this + 0x8298) & 1)) * '\x02' + (*(byte *)((int)this + 0x829d) & 1)) * '\x02' + (*(byte *)((int)this + 0x829c) & 1) ` | +| `0x015` | `*(char *)((int)this + 0x7a4) * '\x10' + (*(byte *)((int)this + 0x7a5) & 0xf)` | +| `0x016` | `*(char *)((int)this + 0x7a6) * '\x10' + (*(byte *)((int)this + 0x7a7) & 0xf)` | +| `0x017` | `*(byte *)((int)this + 0x750) & 7` | +| `0x018` | `*(byte *)((int)this + 0x82a0) & 0x3f` | +| `0x019` | `(byte)iVar25` | +| `0x01B` | `(byte)(iVar25 + (iVar25 >> 0x1f & 0xffU) >> 8)` | +| `0x01C` | `((*(char *)((int)this + 0x82a6) * '\b' + (*(byte *)((int)this + 0x829e) & 7)) * '\x02' + *(char *)((int)this + 0x82a5)) * '\b' + (local_2cd & 7)` | +| `0x01D` | `*(byte *)((int)this + 0x7a8)` | +| `0x01E` | `0` | +| `0x020` | `(byte)*(undefined4 *)((int)this + 0x758) & 0xf` | +| `0x021` | `(byte)*(undefined4 *)((int)this + 0x75c) & 0xf` | +| `0x022` | `(byte)*(undefined4 *)((int)this + 0x760) & 0xf` | +| `0x023` | `(byte)*(undefined4 *)((int)this + 0x764) & 0xf` | +| `0x024` | `(byte)*(undefined4 *)((int)this + 0x768) & 0xf` | +| `0x025` | `(byte)*(undefined4 *)((int)this + 0x76c) & 0xf` | +| `0x026` | `(byte)*(undefined4 *)((int)this + 0x770) & 0xf` | +| `0x027` | `(byte)*(undefined4 *)((int)this + 0x774) & 0xf` | +| `0x028` | `(byte)*(undefined4 *)((int)this + 0x778) & 0xf` | +| `0x029` | `(byte)*(undefined4 *)((int)this + 0x77c) & 0xf` | +| `0x02A` | `(byte)*(undefined4 *)((int)this + 0x780) & 0xf` | +| `0x02B` | `(byte)*(undefined4 *)((int)this + 0x784) & 0xf` | +| `0x02C` | `(byte)*(undefined4 *)((int)this + 0x788) & 0xf` | +| `0x02D` | `(byte)*(undefined4 *)((int)this + 0x78c) & 0xf` | +| `0x02E` | `(byte)*(undefined4 *)((int)this + 0x790) & 0xf` | +| `0x02F` | `(byte)*(undefined4 *)((int)this + 0x794) & 0xf` | +| `0x030` | `(byte)*(undefined4 *)((int)this + 0x798) & 0xf` | +| `0x031` | `0` | +| `0x032` | `0` | +| `0x033` | `0` | +| `0x035` | `0` | +| `0x036` | `0` | +| `0x037` | `0` | +| `0x038` | `0` | +| `0x039` | `0` | +| `0x03A` | `*(byte *)((int)this + 0x8035)` | +| `0x03B` | `*(byte *)((int)this + 0x8036)` | +| `0x03C` | `*(byte *)((int)this + 0x8037)` | +| `0x03D` | `0` | +| `0x03E` | `0` | +| `0x03F` | `((*(char *)((int)this + 0x810c) * '\x04' + *(char *)((int)this + 0x8114)) * '\x04' + *(char *)((int)this + 0x8115)) * '\b' + *(char *)((int)this + 0x82ec)` | +| `0x040` | `(*(char *)((int)this + 0x82b4) * '\x02' + *(char *)((int)this + 0x82bc)) * ' ' + *(char *)((int)this + 0x82c4)` | +| `0x042` | `(*(char *)((int)this + 0x82b8) * '\x02' + *(char *)((int)this + 0x82c0)) * ' ' + *(char *)((int)this + 0x82c8)` | +| `0x043` | `(((*(char *)((int)this + 0x80fc) * '\x02' + *(char *)((int)this + 0x82f0)) * '\x02' + *(char *)((int)this + 0x82f4)) * '\x02' + *(char *)((int)this + 0x80f4)) * '\x10' + cVar20` | +| `0x044` | `(*(char *)((int)this + 0x908) * '\x02' + *(char *)((int)this + 0x86c)) * ' ' + *(char *)((int)this + 0x803a)` | +| `0x045` | `(*(char *)((int)this + 0x909) * '\x02' + *(char *)((int)this + 0x870)) * ' ' + *(char *)((int)this + 0x803b)` | +| `0x046` | `(*(char *)((int)this + 0x90a) * '\x02' + *(char *)((int)this + 0x874)) * ' ' + *(char *)((int)this + 0x803c)` | +| `0x047` | `(*(char *)((int)this + 0x90b) * '\x02' + *(char *)((int)this + 0x878)) * ' ' + *(char *)((int)this + 0x803d)` | +| `0x048` | `((char)*(undefined4 *)((int)this + 0x87c) + *(char *)((int)this + 0x90c) * '\x02') * ' ' + *(char *)((int)this + 0x803e)` | +| `0x049` | `((char)*(undefined4 *)((int)this + 0x880) + *(char *)((int)this + 0x90d) * '\x02') * ' ' + *(char *)((int)this + 0x803f)` | +| `0x04A` | `((char)*(undefined4 *)((int)this + 0x884) + *(char *)((int)this + 0x90e) * '\x02') * ' ' + *(char *)((int)this + 0x8040)` | +| `0x04B` | `((char)*(undefined4 *)((int)this + 0x88c) + *(char *)((int)this + 0x910) * '\x02') * ' ' + *(char *)((int)this + 0x8042)` | +| `0x04D` | `((char)*(undefined4 *)((int)this + 0x890) + *(char *)((int)this + 0x911) * '\x02') * ' ' + *(char *)((int)this + 0x8043)` | +| `0x04E` | `((char)*(undefined4 *)((int)this + 0x894) + *(char *)((int)this + 0x912) * '\x02') * ' ' + *(char *)((int)this + 0x8044)` | +| `0x04F` | `((char)*(undefined4 *)((int)this + 0x89c) + *(char *)((int)this + 0x914) * '\x02') * ' ' + *(char *)((int)this + 0x8048)` | +| `0x051` | `((char)*(undefined4 *)((int)this + 0x8a0) + *(char *)((int)this + 0x915) * '\x02') * ' ' + *(char *)((int)this + 0x8049)` | +| `0x052` | `((char)*(undefined4 *)((int)this + 0x8a4) + *(char *)((int)this + 0x916) * '\x02') * ' ' + *(char *)((int)this + 0x804a)` | +| `0x053` | `((char)*(undefined4 *)((int)this + 0x8ac) + *(char *)((int)this + 0x918) * '\x02') * ' ' + *(char *)((int)this + 0x804c)` | +| `0x055` | `((char)*(undefined4 *)((int)this + 0x8b0) + *(char *)((int)this + 0x919) * '\x02') * ' ' + *(char *)((int)this + 0x804d)` | +| `0x056` | `((char)*(undefined4 *)((int)this + 0x8b4) + *(char *)((int)this + 0x91a) * '\x02') * ' ' + *(char *)((int)this + 0x804e)` | +| `0x057` | `((char)*(undefined4 *)((int)this + 0x8bc) + *(char *)((int)this + 0x91c) * '\x02') * ' ' + *(char *)((int)this + 0x8050)` | diff --git a/docs/devdock-functions.md b/docs/devdock-functions.md index 7743029..964d17d 100644 --- a/docs/devdock-functions.md +++ b/docs/devdock-functions.md @@ -1,98 +1,98 @@ -# DevDock function map (Sades Kaze A825) - -Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from -`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. - -The analysis database used the names below; the addresses are the evidence. - -| Address | Name | Role | -| --- | --- | --- | -| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | -| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | -| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | -| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | -| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` puts `byte[0x8104] & 3` in bits 4-3 above three flags; writing it did not change the measured report cadence. | -| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | -| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | -| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | -| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | -| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | -| `0x486FA0` | apply state collector | Collect UI state into the device object. | -| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | -| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | -| `0x460A60` | `MacroSenderThread` | Macro playback thread. | -| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | -| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | -| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | - -## Block write - -`A825_BlockWrite(this, handle, address, data, length)`: - -``` -07 18 03 -``` - -one frame per byte, then: - -``` -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Addresses are little-endian. The wait between the finish and commit frames is -12 ms. - -## Read - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → feature report byte 1 -07 18 00 00 00 00 -``` - -## Block mode - -`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then -`07 18 00 00 00 00 00 00`. - -## DPI frames - -`A825_LiveDpiAndButtons`: - -``` -07 12 mode 0 -07 12 other modes -07 11 -07 09 × 4 -``` - -The four `09` frames use: - -``` -byte2 = ((map >> 4) << 6) + profile -byte3 = (map << 4) + 8 + index -byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 -``` - -where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the -flags are `byte[0x79C..0x79F]`. - -## Configuration image - -`A825_BuildConfigImage` collects records with numeric ids: - -| Id | Value | -| --- | --- | -| 0 | `0x5A` | -| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | -| 2 | `0xA5` | -| 3 | `byte[0x8068]` | -| 4 | `byte 1 of the 32-bit value at 0x8068` | -| 5 | `byte[0x8064]` | -| 6 | `byte 1 of the 32-bit value at 0x8064` | -| 7 | `byte[0x802C]` (key map byte 0) | -| 8+ | lighting and stage fields | - -The record-to-image-address mapping is not resolved. +# DevDock function map (Sades Kaze A825) + +Binary: `DevDock.exe`, product `New825Tab`, 32-bit MSVC + DuiLib, from +`SadesKaze(A825).[20241009].exe`. Addresses are image-base relative. + +The analysis database used the names below; the addresses are the evidence. + +| Address | Name | Role | +| --- | --- | --- | +| `0x4554B0` | `A825_OpenDevice` | Enumerate HID interfaces with SetupDi and open the report-7 collection. | +| `0x455A40` | `A825_BlockWrite` | Write a config block: one `18 03` frame per byte, `18 09` finish, `18 00` commit. | +| `0x455BA0` | `A825_BlockMode` | Enter (`18 10`) and leave (`18 00`) block mode. | +| `0x480B00` | `A825_WriteLightingConfig` | Write lighting/configuration blocks at `0x1C`, `0x20`, `0x28`, `0x30`, `0x3A`, `0x3E`. | +| `0x481400` | `A825_BuildConfigImage` | Build the full image as id/value records; record `0x14` puts `byte[0x8104] & 3` in bits 4-3 above three flags; writing it did not change the measured report cadence. | +| `0x4862F0` | `A825_ReadInfo` | Read bytes through `18 03` / `18 00` / `18 05`. | +| `0x486440` | `A825_ButtonMap` | Send `09` button-map frames for the active profile. | +| `0x486630` | `A825_LiveDpiAndButtons` | Send `12` DPI, `11` commit, then four `09` frames. | +| `0x469EB0` | `A825_ApplyLighting` | Collect lighting fields and call `A825_WriteLightingConfig`. | +| `0x402700` | profile/mode switch | Set the active profile, call `A825_ButtonMap` and `A825_LiveDpiAndButtons`, send `13 7F …`. | +| `0x486FA0` | apply state collector | Collect UI state into the device object. | +| `0x454B30` | `A825_ButtonMapFrame` | One `09` frame: `byte2=map index`, `byte3=(action+8)*16+bit`. | +| `0x454BA0` | `A825_KeyCodeFrame` | One `17` frame carrying a 16-bit key/function code. | +| `0x460A60` | `MacroSenderThread` | Macro playback thread. | +| `0x4A3800` | `Keyboard_ApplyConfig` | Keyboard (not mouse) `14`/`13`/`18` frames. | +| `0x4A3A30` | `Keyboard_SetKeyColor` | Keyboard per-key colour. | +| `0x4A3BB0` | `Keyboard_KeyFrame` | Keyboard key/colour `13` frame. | + +## Block write + +`A825_BlockWrite(this, handle, address, data, length)`: + +``` +07 18 03 +``` + +one frame per byte, then: + +``` +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Addresses are little-endian. The wait between the finish and commit frames is +12 ms. + +## Read + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → feature report byte 1 +07 18 00 00 00 00 +``` + +## Block mode + +`A825_BlockMode` sends `07 18 10 00 00 00 00 00`, waits 5 ms, then +`07 18 00 00 00 00 00 00`. + +## DPI frames + +`A825_LiveDpiAndButtons`: + +``` +07 12 mode 0 +07 12 other modes +07 11 +07 09 × 4 +``` + +The four `09` frames use: + +``` +byte2 = ((map >> 4) << 6) + profile +byte3 = (map << 4) + 8 + index +byte4 = ((flag0 * 2 + flag1) * 2 + flag2) * 2 + flag3 +``` + +where `map` is `byte[0x7A2 + index]`, `profile` is `byte[0x750]`, and the +flags are `byte[0x79C..0x79F]`. + +## Configuration image + +`A825_BuildConfigImage` collects records with numeric ids: + +| Id | Value | +| --- | --- | +| 0 | `0x5A` | +| 1 | `(-(flag) & 3) + (byte[0x74C] & 3) * 32` | +| 2 | `0xA5` | +| 3 | `byte[0x8068]` | +| 4 | `byte 1 of the 32-bit value at 0x8068` | +| 5 | `byte[0x8064]` | +| 6 | `byte 1 of the 32-bit value at 0x8064` | +| 7 | `byte[0x802C]` (key map byte 0) | +| 8+ | lighting and stage fields | + +The record-to-image-address mapping is not resolved. diff --git a/docs/instant-a825.md b/docs/instant-a825.md index 6695c0b..9fcb1d2 100644 --- a/docs/instant-a825.md +++ b/docs/instant-a825.md @@ -1,202 +1,202 @@ -# Instant A825 - -Protocol of the Instant Microelectronics A825 control interface, reverse -engineered from the vendor `DevDock.exe` and verified on a Sades Kaze. - -## Identity and connection paths - -- Vendor: Wuxi Instant Microelectronics (A825 chipset). -- Tested model: Sades Kaze (Instant A825), wired USB. -- USB: VID `0x30FA`, PID `0x1440`; the vendor configuration also lists PID - `0x1E01`. Public A825 research lists PID `0x7F7F`. -- Product string `USB GAMING MOUSE`, manufacturer string `INSTANT`. -- Configuration collection: usage page `0xFF01`, usage `0x01`, interface 1. -- Report 7 is the only feature report. Windows reports an 8-byte feature - report; the same report returns a 32-byte status block. -- Firmware/build word in the status block: `0x0954`. - -## Evidence - -- `SadesKaze(A825).[20241009].exe` → `DevDock.exe`, product `New825Tab`, - 32-bit MSVC + DuiLib, SHA-256 - `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`. -- Chip vendor reference build: `Instant A825 Mouse Reference - Driver.[20250716]` from instant-sys.com, same `New825Tab` codebase with a - generic `Instant A825 Gaming Mouse` profile. -- Ghidra analysis of the Sades build; the function names below are the - annotated names in that database. `docs/devdock-functions.md` lists the - addresses; `docs/a825-config-records.md` lists every configuration record. -- A825 datasheet V1.01 (Instant Microelectronics). - -## Transport - -Commands are 8-byte feature reports: - -``` -07 -``` - -Status read on report 7: - -``` -07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... -``` - -`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed `24 5A A5` -marker. `state` and `n` change with device activity. - -## Block access - -Command `0x18` addresses a 16-bit little-endian configuration memory. Write: - -``` -07 18 03 -07 18 09 00 00 -07 18 00 00 00 00 -``` - -Read: - -``` -07 18 03 00 00 -07 18 00 00 00 00 -07 18 05 00 → reply byte 1 -07 18 00 00 00 00 -``` - -`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a -save. `A825_BlockWrite` is `0x455A40`; `A825_BlockMode` is `0x455BA0`. - -## Vendor command paths - -| Command | Path | Purpose | -| --- | --- | --- | -| `18` | `A825_BlockWrite` / `A825_BlockMode` | Read/write the configuration image | -| `12` | `A825_LiveDpiAndButtons` (`0x486630`) | Live DPI value | -| `11` | `A825_LiveDpiAndButtons` | Commit | -| `09` | `A825_ButtonMap` (`0x486440`), `A825_ButtonMapFrame` (`0x454B30`) | Button map | -| `17` | `A825_KeyCodeFrame` (`0x454BA0`) | 16-bit key/function code | -| `13` | profile switch (`0x402700`) | Lighting/mode | -| `18 10`/`18 00` | `A825_BlockMode` | Enter/leave save mode | - -`A825_BuildConfigImage` (`0x481400`) assembles the stored image as -offset/value records. `A825_WriteLightingConfig` (`0x480B00`) writes the -lighting blocks. `A825_ApplyLighting` (`0x469EB0`) collects the lighting UI -and calls the writer. - -## Stored configuration - -The tested unit's `0x0000-0x008F`: - -``` -0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 -0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 -0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF -0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 -0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 -0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 -0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 -0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 -0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 -``` - -`0x0400-0x04FF` holds repeated 32-byte records beginning -`01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`; -`0x0500-0x0FFF` is `FF` fill with `00 00` at every `0x100` boundary. - -Blocks written by the vendor application: - -| Address | Length | Meaning (from code) | -| --- | --- | --- | -| `0x0000` | 2 | Header | -| `0x0007` | 25 | Key map | -| `0x001C` | 2 | Stage-enable mask and flags | -| `0x0020` | 8 | Stage colours A | -| `0x0028` | 8 | Stage colours B | -| `0x0030` | 4 | Sensor options | -| `0x003A` | 1 | Lighting direction/symmetry | -| `0x003E` | 2 | Lighting | -| `0x0F80` | 2 | Trailer | - -`0x3A` holds -`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. -It is not the polling rate. - -## Polling rate - -Record `0x14` of `A825_BuildConfigImage` is: - -``` -(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 - + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) -``` - -Bits 4-3 of this record (`(byte >> 3) & 3`) are a 2-bit field. All four values -were written to `0x14` and read back correctly, but the measured report cadence -stayed at ~125 Hz for every value. The field is therefore not confirmed as the -polling rate; it may be applied only on save/reconnect or be a different -setting. - -## DPI - -`A825_LiveDpiAndButtons` sends: - -``` -07 12 00 00 00 00 00 mode 0 -07 12 … other modes -07 11 00 00 00 00 00 00 commit -07 09 … four button-map frames -``` - -The 23 DPI gears: - -``` -200 400 600 800 1000 1200 1400 1600 1800 2000 -2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 -10400 11200 12800 -``` - -Sending `0x12` on the tested unit did not change the stored image or the -status block. The six-stage CPI table was not found in `0x0000-0x0FFF`. - -## Lighting - -`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` -fields. `A825_ApplyLighting` collects `light_color`, `light_color_en`, -`light_brightness`, `light_speed`, `light_symmetry` and `light_direction`. -The profile switch also sends `07 13 7F 00 00 20 07`. - -## Validation - -| Claim | Result | -| --- | --- | -| VID/PID, `0xFF01:0x01`, report 7, 8-byte feature reports | Observed | -| 8-byte command frames accepted | Observed | -| Block write and read-back at `0x3A` (`0x0B → 0x0A → 0x0B`) | Observed | -| Stored image `0x0000-0x0FFF` read byte by byte | Observed | -| Rate field `0x14` write/read-back | Observed; effect on cadence not observed | -| DPI `0x12` effect | Not observed | -| Vendor Apply block sequence | Captured from the vendor app | - -## Not yet verified - -- The mapping from the `0x14` 2-bit field to 125/250/500/1000 Hz. -- The six-stage CPI table location. -- Button-map and lighting semantics beyond the frames listed here. - -## Devices - -The A825 is a chipset. Public A825 mice: - -- Sades Kaze (Instant A825) — tested. -- Ant Esports GM320 — public reverse-engineering project. -- AJAZZ NJ08. -- Kreo Harpy. -- Cybeart Ghost. - -## Sources - -- A825 datasheet V1.01, Instant Microelectronics. -- `SadesKaze(A825).[20241009].exe` (vendor application). -- `Instant A825 Mouse Reference Driver.[20250716]` (vendor reference build). -- `https://github.com/helllopratik/ant-gm320-linux-experimental`. +# Instant A825 + +Protocol of the Instant Microelectronics A825 control interface, reverse +engineered from the vendor `DevDock.exe` and verified on a Sades Kaze. + +## Identity and connection paths + +- Vendor: Wuxi Instant Microelectronics (A825 chipset). +- Tested model: Sades Kaze (Instant A825), wired USB. +- USB: VID `0x30FA`, PID `0x1440`; the vendor configuration also lists PID + `0x1E01`. Public A825 research lists PID `0x7F7F`. +- Product string `USB GAMING MOUSE`, manufacturer string `INSTANT`. +- Configuration collection: usage page `0xFF01`, usage `0x01`, interface 1. +- Report 7 is the only feature report. Windows reports an 8-byte feature + report; the same report returns a 32-byte status block. +- Firmware/build word in the status block: `0x0954`. + +## Evidence + +- `SadesKaze(A825).[20241009].exe` → `DevDock.exe`, product `New825Tab`, + 32-bit MSVC + DuiLib, SHA-256 + `b76c4dff76598dbd8e3874d382ab1875feaa0979754c1e3e5dc12507b8cf1b87`. +- Chip vendor reference build: `Instant A825 Mouse Reference + Driver.[20250716]` from instant-sys.com, same `New825Tab` codebase with a + generic `Instant A825 Gaming Mouse` profile. +- Ghidra analysis of the Sades build; the function names below are the + annotated names in that database. `docs/devdock-functions.md` lists the + addresses; `docs/a825-config-records.md` lists every configuration record. +- A825 datasheet V1.01 (Instant Microelectronics). + +## Transport + +Commands are 8-byte feature reports: + +``` +07 +``` + +Status read on report 7: + +``` +07 54 09 27 00 03 CB 11 00 00 00 10 24 5A A5 ... +``` + +`54 09` is the build word `0x0954`. Bytes 17-19 are the fixed `24 5A A5` +marker. `state` and `n` change with device activity. + +## Block access + +Command `0x18` addresses a 16-bit little-endian configuration memory. Write: + +``` +07 18 03 +07 18 09 00 00 +07 18 00 00 00 00 +``` + +Read: + +``` +07 18 03 00 00 +07 18 00 00 00 00 +07 18 05 00 → reply byte 1 +07 18 00 00 00 00 +``` + +`07 18 10` enters and `07 18 00` leaves the mode the vendor app uses after a +save. `A825_BlockWrite` is `0x455A40`; `A825_BlockMode` is `0x455BA0`. + +## Vendor command paths + +| Command | Path | Purpose | +| --- | --- | --- | +| `18` | `A825_BlockWrite` / `A825_BlockMode` | Read/write the configuration image | +| `12` | `A825_LiveDpiAndButtons` (`0x486630`) | Live DPI value | +| `11` | `A825_LiveDpiAndButtons` | Commit | +| `09` | `A825_ButtonMap` (`0x486440`), `A825_ButtonMapFrame` (`0x454B30`) | Button map | +| `17` | `A825_KeyCodeFrame` (`0x454BA0`) | 16-bit key/function code | +| `13` | profile switch (`0x402700`) | Lighting/mode | +| `18 10`/`18 00` | `A825_BlockMode` | Enter/leave save mode | + +`A825_BuildConfigImage` (`0x481400`) assembles the stored image as +offset/value records. `A825_WriteLightingConfig` (`0x480B00`) writes the +lighting blocks. `A825_ApplyLighting` (`0x469EB0`) collects the lighting UI +and calls the writer. + +## Stored configuration + +The tested unit's `0x0000-0x008F`: + +``` +0000: 5A 03 A5 40 14 FA 30 00 21 22 23 24 25 26 20 15 +0010: 00 00 00 32 08 41 DF 18 19 3F 06 00 F3 FF 00 00 +0020: 00 02 DF EF 5F 00 00 FF 41 FD 10 DF 00 FF FF FF +0030: 10 10 FF 3F 00 00 00 00 00 00 0B 00 00 00 00 00 +0040: 00 00 00 61 21 22 23 24 25 26 20 15 00 00 00 00 +0050: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 00 +0060: 21 22 23 24 25 26 20 15 00 00 00 00 00 00 00 04 +0070: 08 04 10 04 18 04 41 00 00 20 04 A0 0F 0D 01 02 +0080: 00 18 94 49 09 14 24 09 13 0A 09 08 00 00 00 00 +``` + +`0x0400-0x04FF` holds repeated 32-byte records beginning +`01 00 BB E3 7F 00 FC 08 06 E3 14 08 00 00 00 00`; +`0x0500-0x0FFF` is `FF` fill with `00 00` at every `0x100` boundary. + +Blocks written by the vendor application: + +| Address | Length | Meaning (from code) | +| --- | --- | --- | +| `0x0000` | 2 | Header | +| `0x0007` | 25 | Key map | +| `0x001C` | 2 | Stage-enable mask and flags | +| `0x0020` | 8 | Stage colours A | +| `0x0028` | 8 | Stage colours B | +| `0x0030` | 4 | Sensor options | +| `0x003A` | 1 | Lighting direction/symmetry | +| `0x003E` | 2 | Lighting | +| `0x0F80` | 2 | Trailer | + +`0x3A` holds +`((direction & 3) + (symmetry + flag * 2) * 4) * 16 + (count - 1)`. +It is not the polling rate. + +## Polling rate + +Record `0x14` of `A825_BuildConfigImage` is: + +``` +(((byte[0x8104] & 3) * 2 + (byte[0x8298] & 1)) * 2 + + (byte[0x829D] & 1)) * 2 + (byte[0x829C] & 1) +``` + +Bits 4-3 of this record (`(byte >> 3) & 3`) are a 2-bit field. All four values +were written to `0x14` and read back correctly, but the measured report cadence +stayed at ~125 Hz for every value. The field is therefore not confirmed as the +polling rate; it may be applied only on save/reconnect or be a different +setting. + +## DPI + +`A825_LiveDpiAndButtons` sends: + +``` +07 12 00 00 00 00 00 mode 0 +07 12 … other modes +07 11 00 00 00 00 00 00 commit +07 09 … four button-map frames +``` + +The 23 DPI gears: + +``` +200 400 600 800 1000 1200 1400 1600 1800 2000 +2400 3200 4000 4800 5600 6400 7200 8000 8800 9600 +10400 11200 12800 +``` + +Sending `0x12` on the tested unit did not change the stored image or the +status block. The six-stage CPI table was not found in `0x0000-0x0FFF`. + +## Lighting + +`A825_WriteLightingConfig` writes the stage colours and the `0x3A`/`0x3E` +fields. `A825_ApplyLighting` collects `light_color`, `light_color_en`, +`light_brightness`, `light_speed`, `light_symmetry` and `light_direction`. +The profile switch also sends `07 13 7F 00 00 20 07`. + +## Validation + +| Claim | Result | +| --- | --- | +| VID/PID, `0xFF01:0x01`, report 7, 8-byte feature reports | Observed | +| 8-byte command frames accepted | Observed | +| Block write and read-back at `0x3A` (`0x0B → 0x0A → 0x0B`) | Observed | +| Stored image `0x0000-0x0FFF` read byte by byte | Observed | +| Rate field `0x14` write/read-back | Observed; effect on cadence not observed | +| DPI `0x12` effect | Not observed | +| Vendor Apply block sequence | Captured from the vendor app | + +## Not yet verified + +- The mapping from the `0x14` 2-bit field to 125/250/500/1000 Hz. +- The six-stage CPI table location. +- Button-map and lighting semantics beyond the frames listed here. + +## Devices + +The A825 is a chipset. Public A825 mice: + +- Sades Kaze (Instant A825) — tested. +- Ant Esports GM320 — public reverse-engineering project. +- AJAZZ NJ08. +- Kreo Harpy. +- Cybeart Ghost. + +## Sources + +- A825 datasheet V1.01, Instant Microelectronics. +- `SadesKaze(A825).[20241009].exe` (vendor application). +- `Instant A825 Mouse Reference Driver.[20250716]` (vendor reference build). +- `https://github.com/helllopratik/ant-gm320-linux-experimental`. diff --git a/src/drivers/instant/a825-hid.test.ts b/src/drivers/instant/a825-hid.test.ts index a848656..c14a5c4 100644 --- a/src/drivers/instant/a825-hid.test.ts +++ b/src/drivers/instant/a825-hid.test.ts @@ -1,138 +1,138 @@ -import assert from "node:assert/strict"; -import test from "node:test"; - -import { - INSTANT_REPORT_ID, - INSTANT_USAGE, - INSTANT_USAGE_PAGE, - INSTANT_VENDOR_ID, -} from "@openmouse/protocol/instant"; -import { InstantA825HidClient } from "./a825-hid.ts"; - -function report(reportId: number): HIDReportInfo { - return { reportId, items: [] } as unknown as HIDReportInfo; -} - -function controlCollection(): HIDCollectionInfo { - return { - usagePage: INSTANT_USAGE_PAGE, - usage: INSTANT_USAGE, - type: 1, - children: [], - featureReports: [report(INSTANT_REPORT_ID)], - inputReports: [], - outputReports: [], - } as unknown as HIDCollectionInfo; -} - -const STATUS = Uint8Array.of( - 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, - 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, -); - -function fakeDevice(options: { - rate?: number; - productId?: number; - numberedReply?: boolean; -} = {}) { - let rate = options.rate ?? 0x0b; - let statusRead = false; - let readSetup = false; - const sent: Uint8Array[] = []; - let pendingWrite: { address: number; data: number[] } | null = null; - let writeFinished = false; - - const device = { - vendorId: INSTANT_VENDOR_ID, - productId: options.productId ?? 0x1440, - productName: "USB GAMING MOUSE", - opened: false, - collections: [controlCollection()], - async open() { - this.opened = true; - }, - async close() { - this.opened = false; - }, - async sendFeatureReport(_reportId: number, data: BufferSource) { - const view = ArrayBuffer.isView(data) - ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) - : new Uint8Array(data as ArrayBuffer); - const frame = Uint8Array.of(INSTANT_REPORT_ID, ...view); - sent.push(frame); - const address = frame[4]! | (frame[5]! << 8); - if (frame[1] === 0x18 && frame[2] === 0x03) { - readSetup = true; - if (frame[7] === 0) { - pendingWrite = { address, data: [frame[6]!] }; - } else if (pendingWrite?.address === address) { - pendingWrite.data[frame[3]!] = frame[6]!; - } - } - if (frame[1] === 0x18 && frame[2] === 0x09) { - writeFinished = true; - } - if (frame[1] === 0x18 && frame[2] === 0x00 && writeFinished) { - if (pendingWrite?.address === 0x3a) rate = pendingWrite.data[0]!; - pendingWrite = null; - writeFinished = false; - } - }, - async receiveFeatureReport(_reportId: number) { - if (readSetup) { - readSetup = false; - const body = options.numberedReply === false - ? Uint8Array.of(rate, 0, 0, 0, 0, 0, 0) - : Uint8Array.of(INSTANT_REPORT_ID, rate, 0, 0, 0, 0, 0, 0); - return new DataView(body.buffer); - } - statusRead = true; - return new DataView(STATUS.slice().buffer); - }, - } as unknown as HIDDevice; - - return { device, sent, get rate() { return rate; } }; -} - -test("A825 identifies the Sades Kaze control collection", () => { - const { device } = fakeDevice(); - assert.equal(InstantA825HidClient.isSupported(device), true); - assert.equal( - InstantA825HidClient.isSupported({ ...device, productId: 0x1234 } as HIDDevice), - false, - ); - assert.equal(InstantA825HidClient.isSupported({ ...device, vendorId: 0x1234 } as HIDDevice), false); -}); - -test("readStatus decodes firmware and stays read-only", async () => { - const { device } = fakeDevice({ rate: 0x0b }); - const client = new InstantA825HidClient(device); - const status = await client.readStatus(); - assert.equal(status.brand, "Sades"); - assert.equal(status.connectionType, "Wired"); - assert.equal(status.pollingRateHz, 0); - assert.equal(status.supportedPollingRates?.join(","), "125,250,500,1000"); - assert.equal(status.activeProfile, null); - assert.equal(status.dpi, 0); - assert.deepEqual(status.firmware, ["Build 0x0954"]); - assert.equal(status.ui?.settingsReady, false); - assert.equal(status.ui?.family, "sades-a825"); - assert.equal(status.ui?.valuesVerified, false); -}); - -test("readConfigImage keeps a partial read and a stored 0x07 byte", async () => { - const fake = fakeDevice({ rate: 0x07 }); - const client = new InstantA825HidClient(fake.device); - const image = await client.readConfigImage(1); - assert.equal(image.bytes.length, 1); - assert.equal(image.bytes[0], 0x07); - assert.equal(image.lightingDirectionByte, null); -}); - -test("readConfigImage accepts an unnumbered 7-byte reply", async () => { - const fake = fakeDevice({ rate: 0x07, numberedReply: false }); - const client = new InstantA825HidClient(fake.device); - const image = await client.readConfigImage(1); - assert.deepEqual(Array.from(image.bytes), [0x07]); -}); +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + INSTANT_REPORT_ID, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, +} from "@openmouse/protocol/instant"; +import { InstantA825HidClient } from "./a825-hid.ts"; + +function report(reportId: number): HIDReportInfo { + return { reportId, items: [] } as unknown as HIDReportInfo; +} + +function controlCollection(): HIDCollectionInfo { + return { + usagePage: INSTANT_USAGE_PAGE, + usage: INSTANT_USAGE, + type: 1, + children: [], + featureReports: [report(INSTANT_REPORT_ID)], + inputReports: [], + outputReports: [], + } as unknown as HIDCollectionInfo; +} + +const STATUS = Uint8Array.of( + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +); + +function fakeDevice(options: { + rate?: number; + productId?: number; + numberedReply?: boolean; +} = {}) { + let rate = options.rate ?? 0x0b; + let statusRead = false; + let readSetup = false; + const sent: Uint8Array[] = []; + let pendingWrite: { address: number; data: number[] } | null = null; + let writeFinished = false; + + const device = { + vendorId: INSTANT_VENDOR_ID, + productId: options.productId ?? 0x1440, + productName: "USB GAMING MOUSE", + opened: false, + collections: [controlCollection()], + async open() { + this.opened = true; + }, + async close() { + this.opened = false; + }, + async sendFeatureReport(_reportId: number, data: BufferSource) { + const view = ArrayBuffer.isView(data) + ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) + : new Uint8Array(data as ArrayBuffer); + const frame = Uint8Array.of(INSTANT_REPORT_ID, ...view); + sent.push(frame); + const address = frame[4]! | (frame[5]! << 8); + if (frame[1] === 0x18 && frame[2] === 0x03) { + readSetup = true; + if (frame[7] === 0) { + pendingWrite = { address, data: [frame[6]!] }; + } else if (pendingWrite?.address === address) { + pendingWrite.data[frame[3]!] = frame[6]!; + } + } + if (frame[1] === 0x18 && frame[2] === 0x09) { + writeFinished = true; + } + if (frame[1] === 0x18 && frame[2] === 0x00 && writeFinished) { + if (pendingWrite?.address === 0x3a) rate = pendingWrite.data[0]!; + pendingWrite = null; + writeFinished = false; + } + }, + async receiveFeatureReport(_reportId: number) { + if (readSetup) { + readSetup = false; + const body = options.numberedReply === false + ? Uint8Array.of(rate, 0, 0, 0, 0, 0, 0) + : Uint8Array.of(INSTANT_REPORT_ID, rate, 0, 0, 0, 0, 0, 0); + return new DataView(body.buffer); + } + statusRead = true; + return new DataView(STATUS.slice().buffer); + }, + } as unknown as HIDDevice; + + return { device, sent, get rate() { return rate; } }; +} + +test("A825 identifies the Sades Kaze control collection", () => { + const { device } = fakeDevice(); + assert.equal(InstantA825HidClient.isSupported(device), true); + assert.equal( + InstantA825HidClient.isSupported({ ...device, productId: 0x1234 } as HIDDevice), + false, + ); + assert.equal(InstantA825HidClient.isSupported({ ...device, vendorId: 0x1234 } as HIDDevice), false); +}); + +test("readStatus decodes firmware and stays read-only", async () => { + const { device } = fakeDevice({ rate: 0x0b }); + const client = new InstantA825HidClient(device); + const status = await client.readStatus(); + assert.equal(status.brand, "Sades"); + assert.equal(status.connectionType, "Wired"); + assert.equal(status.pollingRateHz, 0); + assert.equal(status.supportedPollingRates?.join(","), "125,250,500,1000"); + assert.equal(status.activeProfile, null); + assert.equal(status.dpi, 0); + assert.deepEqual(status.firmware, ["Build 0x0954"]); + assert.equal(status.ui?.settingsReady, false); + assert.equal(status.ui?.family, "sades-a825"); + assert.equal(status.ui?.valuesVerified, false); +}); + +test("readConfigImage keeps a partial read and a stored 0x07 byte", async () => { + const fake = fakeDevice({ rate: 0x07 }); + const client = new InstantA825HidClient(fake.device); + const image = await client.readConfigImage(1); + assert.equal(image.bytes.length, 1); + assert.equal(image.bytes[0], 0x07); + assert.equal(image.lightingDirectionByte, null); +}); + +test("readConfigImage accepts an unnumbered 7-byte reply", async () => { + const fake = fakeDevice({ rate: 0x07, numberedReply: false }); + const client = new InstantA825HidClient(fake.device); + const image = await client.readConfigImage(1); + assert.deepEqual(Array.from(image.bytes), [0x07]); +}); diff --git a/src/drivers/instant/a825-hid.ts b/src/drivers/instant/a825-hid.ts index 90eb587..c4ea5e8 100644 --- a/src/drivers/instant/a825-hid.ts +++ b/src/drivers/instant/a825-hid.ts @@ -1,292 +1,292 @@ -import type { MouseStatus } from "../mouse-types.ts"; -import { - decodeInstantConfig, - decodeInstantStatus, - instantBlockReadByteFrame, - instantBlockReadFrames, - instantFrame, - INSTANT_BLOCK, - INSTANT_COMMAND, - INSTANT_CONFIG_LENGTH, - INSTANT_DPI_GEARS, - INSTANT_FRAME_LENGTH, - INSTANT_POLLING_RATES, - INSTANT_PRODUCT_IDS, - INSTANT_REPORT_ID, - INSTANT_STATUS_LENGTH, - INSTANT_USAGE, - INSTANT_USAGE_PAGE, - INSTANT_VENDOR_ID, - instantDpiFrames, - type InstantConfigImage, -} from "@openmouse/protocol/instant"; - -function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { - return collections.some( - (collection) => - (collection.usagePage === INSTANT_USAGE_PAGE && - collection.usage === INSTANT_USAGE && - collection.featureReports.some( - (report) => report.reportId === INSTANT_REPORT_ID, - )) || - hasConfigCollection(collection.children), - ); -} - -function statusBytes(view: DataView, reportId: number): Uint8Array { - const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); - // The A825 reports are fixed-size: a numbered reply is 8 bytes for a command - // and 32 for the status block. A reply of 7 or 31 bytes has no report ID, so - // do not guess from the first byte (a stored value may itself be 0x07). - const numbered = - bytes.length === INSTANT_FRAME_LENGTH || bytes.length === INSTANT_STATUS_LENGTH; - if (numbered) { - if (bytes[0] !== reportId) { - throw new Error(`Unexpected A825 report ID: ${bytes[0]}`); - } - return bytes.slice(1); - } - return bytes.slice(); -} - -/** - * Sades Kaze / Instant A825 control client. - * - * Reads the 32-byte status block and the stored configuration image. Settings - * framing is implemented in `@openmouse/protocol/instant`. The DPI command has - * no observable read-back on this firmware and the polling-rate field is not yet - * mapped, so the panel shows this device as read-only. - */ -export class InstantA825HidClient { - readonly device: HIDDevice; - private config: InstantConfigImage | null = null; - private status: Uint8Array | null = null; - private queue: Promise = Promise.resolve(); - private generation = 0; - private opening: Promise | null = null; - private closing: Promise | null = null; - - constructor(device: HIDDevice) { - this.device = device; - } - - static isSupported(device: HIDDevice): boolean { - return ( - device.vendorId === INSTANT_VENDOR_ID && - INSTANT_PRODUCT_IDS.has(device.productId) && - hasConfigCollection(device.collections) - ); - } - - getDpiOptions(): number[] { - return [...INSTANT_DPI_GEARS]; - } - - getPollingRateOptions(): number[] { - return [...INSTANT_POLLING_RATES]; - } - - async open(): Promise { - if (!InstantA825HidClient.isSupported(this.device)) { - throw new Error("Unsupported A825 HID interface"); - } - if (this.closing) await this.closing; - if (this.opening) return this.opening; - if (this.device.opened) return; - const generation = this.generation; - const task = (async () => { - await this.device.open(); - if (generation !== this.generation) { - if (this.device.opened) await this.device.close(); - throw new Error("A825 disconnected while opening"); - } - })(); - this.opening = task; - try { - await task; - } finally { - if (this.opening === task) this.opening = null; - } - } - - async close(): Promise { - this.generation += 1; - this.config = null; - this.status = null; - this.queue = Promise.resolve(); - const task = (async () => { - await this.opening?.catch(() => undefined); - if (this.device.opened) await this.device.close(); - })(); - this.closing = task; - try { - await task; - } finally { - if (this.closing === task) this.closing = null; - } - } - - /** Raw 32-byte status report, including report ID 7. */ - getRawStatusReport(): Uint8Array | null { - return this.status?.slice() ?? null; - } - - /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ - getConfigImage(): InstantConfigImage | null { - return this.config - ? { - ...this.config, - bytes: this.config.bytes.slice(), - } - : null; - } - - private serialize(action: () => Promise): Promise { - const generation = this.generation; - const task = this.queue.then(() => { - if (generation !== this.generation) { - throw new Error("A825 disconnected before queued transfer"); - } - return action(); - }); - this.queue = task.then( - () => undefined, - () => undefined, - ); - return task; - } - - private async send(frame: Uint8Array): Promise { - await this.device.sendFeatureReport( - INSTANT_REPORT_ID, - frame.slice(1).buffer, - ); - } - - private async readStatusReport(): Promise { - const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); - return statusBytes(view, INSTANT_REPORT_ID); - } - - /** Read one byte from the configuration image, using the vendor read path. */ - private async readByte(address: number): Promise { - const setup = instantBlockReadFrames(address, 1); - for (const frame of setup) await this.send(frame); - await this.send(instantBlockReadByteFrame(address, 0, 1)); - const closeWindow = instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - address & 0xff, - (address >>> 8) & 0xff, - 0, - 0, - ]); - let report: Uint8Array; - try { - report = await this.readStatusReport(); - } catch (error) { - // The read window is open even when the reply is lost. Try to close it, - // but keep the original failure. - await this.send(closeWindow).catch(() => undefined); - throw error; - } - // The vendor closes the read window after every byte. - await this.send(closeWindow); - const full = new Uint8Array(report.length + 1); - full[0] = INSTANT_REPORT_ID; - full.set(report, 1); - const value = full.length > 1 ? full[1] : null; - if (value == null) throw new Error("A825 config read returned no data"); - return value; - } - - /** - * Read the stored configuration image. A full read is 0x1000 one-byte - * transfers; read a small range when only a few bytes matter. - */ - async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { - if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { - throw new RangeError(`Invalid A825 config length: ${length}`); - } - return this.serialize(async () => { - const generation = this.generation; - await this.open(); - if (generation !== this.generation) { - throw new Error("A825 disconnected while opening"); - } - const bytes = new Uint8Array(length); - for (let address = 0; address < length; address += 1) { - bytes[address] = await this.readByte(address); - } - if (generation !== this.generation) { - throw new Error("A825 disconnected during the configuration read"); - } - const image = decodeInstantConfig(bytes); - if (length === INSTANT_CONFIG_LENGTH) this.config = image; - return { - bytes: image.bytes.slice(), - lightingDirectionByte: image.lightingDirectionByte, - }; - }); - } - - async readStatus(): Promise { - return this.serialize(async () => { - const generation = this.generation; - await this.open(); - if (generation !== this.generation) { - throw new Error("A825 disconnected while opening"); - } - const report = await this.readStatusReport(); - if (generation !== this.generation) { - throw new Error("A825 disconnected during the status read"); - } - this.status = new Uint8Array(report.length + 1); - this.status[0] = INSTANT_REPORT_ID; - this.status.set(report, 1); - const decoded = decodeInstantStatus(this.status); - - return { - brand: "Sades", - name: this.device.productName || "Sades Kaze", - ui: { - family: "sades-a825", - settingsReady: false, - valuesVerified: false, - pollingReadOnly: true, - hideProcessingCard: true, - hideSignalCard: true, - hideSleepCard: true, - defaultDisplayName: "Sades Kaze", - statusNote: - "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", - }, - batteryPercent: null, - batteryState: "Unknown", - dpi: 0, - pollingRateHz: 0, - supportedPollingRates: [...INSTANT_POLLING_RATES], - activeProfile: null, - connectionType: "Wired", - connectionDetail: "USB", - liftOffDistance: null, - firmware: - decoded?.magicOk - ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] - : [], - }; - }); - } - - /** - * Send the vendor's live DPI command. Kept for protocol tooling; the panel - * does not expose it because this firmware gives no read-back for the value. - */ - async setLiveDpi(dpi: number, mode = 0): Promise { - return this.serialize(async () => { - await this.open(); - for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); - return dpi; - }); - } -} +import type { MouseStatus } from "../mouse-types.ts"; +import { + decodeInstantConfig, + decodeInstantStatus, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantFrame, + INSTANT_BLOCK, + INSTANT_COMMAND, + INSTANT_CONFIG_LENGTH, + INSTANT_DPI_GEARS, + INSTANT_FRAME_LENGTH, + INSTANT_POLLING_RATES, + INSTANT_PRODUCT_IDS, + INSTANT_REPORT_ID, + INSTANT_STATUS_LENGTH, + INSTANT_USAGE, + INSTANT_USAGE_PAGE, + INSTANT_VENDOR_ID, + instantDpiFrames, + type InstantConfigImage, +} from "@openmouse/protocol/instant"; + +function hasConfigCollection(collections: readonly HIDCollectionInfo[]): boolean { + return collections.some( + (collection) => + (collection.usagePage === INSTANT_USAGE_PAGE && + collection.usage === INSTANT_USAGE && + collection.featureReports.some( + (report) => report.reportId === INSTANT_REPORT_ID, + )) || + hasConfigCollection(collection.children), + ); +} + +function statusBytes(view: DataView, reportId: number): Uint8Array { + const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength); + // The A825 reports are fixed-size: a numbered reply is 8 bytes for a command + // and 32 for the status block. A reply of 7 or 31 bytes has no report ID, so + // do not guess from the first byte (a stored value may itself be 0x07). + const numbered = + bytes.length === INSTANT_FRAME_LENGTH || bytes.length === INSTANT_STATUS_LENGTH; + if (numbered) { + if (bytes[0] !== reportId) { + throw new Error(`Unexpected A825 report ID: ${bytes[0]}`); + } + return bytes.slice(1); + } + return bytes.slice(); +} + +/** + * Sades Kaze / Instant A825 control client. + * + * Reads the 32-byte status block and the stored configuration image. Settings + * framing is implemented in `@openmouse/protocol/instant`. The DPI command has + * no observable read-back on this firmware and the polling-rate field is not yet + * mapped, so the panel shows this device as read-only. + */ +export class InstantA825HidClient { + readonly device: HIDDevice; + private config: InstantConfigImage | null = null; + private status: Uint8Array | null = null; + private queue: Promise = Promise.resolve(); + private generation = 0; + private opening: Promise | null = null; + private closing: Promise | null = null; + + constructor(device: HIDDevice) { + this.device = device; + } + + static isSupported(device: HIDDevice): boolean { + return ( + device.vendorId === INSTANT_VENDOR_ID && + INSTANT_PRODUCT_IDS.has(device.productId) && + hasConfigCollection(device.collections) + ); + } + + getDpiOptions(): number[] { + return [...INSTANT_DPI_GEARS]; + } + + getPollingRateOptions(): number[] { + return [...INSTANT_POLLING_RATES]; + } + + async open(): Promise { + if (!InstantA825HidClient.isSupported(this.device)) { + throw new Error("Unsupported A825 HID interface"); + } + if (this.closing) await this.closing; + if (this.opening) return this.opening; + if (this.device.opened) return; + const generation = this.generation; + const task = (async () => { + await this.device.open(); + if (generation !== this.generation) { + if (this.device.opened) await this.device.close(); + throw new Error("A825 disconnected while opening"); + } + })(); + this.opening = task; + try { + await task; + } finally { + if (this.opening === task) this.opening = null; + } + } + + async close(): Promise { + this.generation += 1; + this.config = null; + this.status = null; + this.queue = Promise.resolve(); + const task = (async () => { + await this.opening?.catch(() => undefined); + if (this.device.opened) await this.device.close(); + })(); + this.closing = task; + try { + await task; + } finally { + if (this.closing === task) this.closing = null; + } + } + + /** Raw 32-byte status report, including report ID 7. */ + getRawStatusReport(): Uint8Array | null { + return this.status?.slice() ?? null; + } + + /** Cached 0x0000-0x02FF configuration image, or null before it is read. */ + getConfigImage(): InstantConfigImage | null { + return this.config + ? { + ...this.config, + bytes: this.config.bytes.slice(), + } + : null; + } + + private serialize(action: () => Promise): Promise { + const generation = this.generation; + const task = this.queue.then(() => { + if (generation !== this.generation) { + throw new Error("A825 disconnected before queued transfer"); + } + return action(); + }); + this.queue = task.then( + () => undefined, + () => undefined, + ); + return task; + } + + private async send(frame: Uint8Array): Promise { + await this.device.sendFeatureReport( + INSTANT_REPORT_ID, + frame.slice(1).buffer, + ); + } + + private async readStatusReport(): Promise { + const view = await this.device.receiveFeatureReport(INSTANT_REPORT_ID); + return statusBytes(view, INSTANT_REPORT_ID); + } + + /** Read one byte from the configuration image, using the vendor read path. */ + private async readByte(address: number): Promise { + const setup = instantBlockReadFrames(address, 1); + for (const frame of setup) await this.send(frame); + await this.send(instantBlockReadByteFrame(address, 0, 1)); + const closeWindow = instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + address & 0xff, + (address >>> 8) & 0xff, + 0, + 0, + ]); + let report: Uint8Array; + try { + report = await this.readStatusReport(); + } catch (error) { + // The read window is open even when the reply is lost. Try to close it, + // but keep the original failure. + await this.send(closeWindow).catch(() => undefined); + throw error; + } + // The vendor closes the read window after every byte. + await this.send(closeWindow); + const full = new Uint8Array(report.length + 1); + full[0] = INSTANT_REPORT_ID; + full.set(report, 1); + const value = full.length > 1 ? full[1] : null; + if (value == null) throw new Error("A825 config read returned no data"); + return value; + } + + /** + * Read the stored configuration image. A full read is 0x1000 one-byte + * transfers; read a small range when only a few bytes matter. + */ + async readConfigImage(length = INSTANT_CONFIG_LENGTH): Promise { + if (!Number.isInteger(length) || length < 1 || length > INSTANT_CONFIG_LENGTH) { + throw new RangeError(`Invalid A825 config length: ${length}`); + } + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const bytes = new Uint8Array(length); + for (let address = 0; address < length; address += 1) { + bytes[address] = await this.readByte(address); + } + if (generation !== this.generation) { + throw new Error("A825 disconnected during the configuration read"); + } + const image = decodeInstantConfig(bytes); + if (length === INSTANT_CONFIG_LENGTH) this.config = image; + return { + bytes: image.bytes.slice(), + lightingDirectionByte: image.lightingDirectionByte, + }; + }); + } + + async readStatus(): Promise { + return this.serialize(async () => { + const generation = this.generation; + await this.open(); + if (generation !== this.generation) { + throw new Error("A825 disconnected while opening"); + } + const report = await this.readStatusReport(); + if (generation !== this.generation) { + throw new Error("A825 disconnected during the status read"); + } + this.status = new Uint8Array(report.length + 1); + this.status[0] = INSTANT_REPORT_ID; + this.status.set(report, 1); + const decoded = decodeInstantStatus(this.status); + + return { + brand: "Sades", + name: this.device.productName || "Sades Kaze", + ui: { + family: "sades-a825", + settingsReady: false, + valuesVerified: false, + pollingReadOnly: true, + hideProcessingCard: true, + hideSignalCard: true, + hideSleepCard: true, + defaultDisplayName: "Sades Kaze", + statusNote: + "Instant A825 control protocol captured; DPI and lighting writes are not enabled until they can be verified by read-back.", + }, + batteryPercent: null, + batteryState: "Unknown", + dpi: 0, + pollingRateHz: 0, + supportedPollingRates: [...INSTANT_POLLING_RATES], + activeProfile: null, + connectionType: "Wired", + connectionDetail: "USB", + liftOffDistance: null, + firmware: + decoded?.magicOk + ? [`Build 0x${decoded.firmware.toString(16).padStart(4, "0")}`] + : [], + }; + }); + } + + /** + * Send the vendor's live DPI command. Kept for protocol tooling; the panel + * does not expose it because this firmware gives no read-back for the value. + */ + async setLiveDpi(dpi: number, mode = 0): Promise { + return this.serialize(async () => { + await this.open(); + for (const frame of instantDpiFrames(dpi, mode)) await this.send(frame); + return dpi; + }); + } +} diff --git a/src/instant/protocol.test.ts b/src/instant/protocol.test.ts index ac8350a..09ceede 100644 --- a/src/instant/protocol.test.ts +++ b/src/instant/protocol.test.ts @@ -1,121 +1,121 @@ -import assert from "node:assert/strict"; -import test from "node:test"; - -import { - decodeInstantConfig, - decodeInstantReadByte, - decodeInstantStatus, - INSTANT_CONFIG, - INSTANT_DPI_GEARS, - INSTANT_REPORT_ID, - instantBlockReadByteFrame, - instantBlockReadFrames, - instantBlockWriteFrames, - instantDpiFrames, - instantDpiGearIndex, - instantFrame, - instantModeFrames, -} from "./protocol.ts"; - -function hex(frame: Uint8Array): string { - return Buffer.from(frame).toString("hex"); -} - -test("instantFrame pads to an 8-byte report 7 frame", () => { - assert.equal(hex(instantFrame(0x18, [0x03, 0])), "0718030000000000"); - assert.equal(instantFrame(0x18).length, 8); - assert.equal(instantFrame(0x18)[0], INSTANT_REPORT_ID); - assert.throws(() => instantFrame(0x18, [1, 2, 3, 4, 5, 6, 7]), RangeError); -}); - -test("block write matches the vendor's captured Apply frames", () => { - const frames = instantBlockWriteFrames(0x0000, [0x5a, 0x03]); - assert.deepEqual(frames.map(hex), [ - "0718030000005a01", - "0718030100000301", - "0718090000000001", - "0718000000000000", - ]); - const high = instantBlockWriteFrames(0x003a, [0x0b]); - assert.equal(hex(high[0]!), "071803003a000b00"); - assert.equal(hex(high[1]!), "071809003a000000"); -}); - -test("block read uses little-endian addresses and a final commit", () => { - const frames = instantBlockReadFrames(0x003a, 2); - assert.equal(frames.length, 3); - assert.equal(hex(frames[0]!), "071803003a000001"); - assert.equal(hex(frames[1]!), "071803013a000001"); - assert.equal(hex(frames[2]!), "071800003a000000"); - assert.equal(hex(instantBlockReadByteFrame(0x003a, 1, 2)), "071805013a000001"); - assert.throws(() => instantBlockReadByteFrame(0x003a, 1, 1), RangeError); - assert.throws(() => instantBlockReadByteFrame(0x10000, 0, 1), RangeError); - assert.throws(() => instantBlockReadFrames(0x003a, Number.NaN), RangeError); - assert.equal(decodeInstantReadByte(new Uint8Array([0x07, 0x0b])), 0x0b); - assert.equal(decodeInstantReadByte(new Uint8Array([0x07])), null); -}); - -test("DPI frames match the vendor's 0x12 encoding", () => { - assert.deepEqual(instantDpiFrames(800).map(hex), [ - "0712640000000000", - "0711000000000000", - ]); - assert.deepEqual(instantDpiFrames(1600, 1).map(hex), [ - "0712006400000000", - "0711000000000000", - ]); - assert.throws(() => instantDpiFrames(300, 1), RangeError); - assert.throws(() => instantDpiFrames(123), RangeError); -}); - -test("mode frames enter and leave block mode", () => { - assert.equal(hex(instantModeFrames(true)[0]!), "0718100000000000"); - assert.equal(hex(instantModeFrames(false)[0]!), "0718000000000000"); -}); - -test("config decode keeps the lighting byte raw", () => { - // Ghidra: 0x3A packs light_direction/light_symmetry, not the polling rate. - const config = decodeInstantConfig(new Uint8Array([...new Uint8Array(0x3a), 0x0b])); - assert.equal(config.lightingDirectionByte, 0x0b); - assert.equal(config.bytes[0x3a], 0x0b); - assert.equal(decodeInstantConfig(new Uint8Array(0x3a)).lightingDirectionByte, null); -}); - -test("DPI table is the vendor's 23-value table", () => { - assert.equal(INSTANT_DPI_GEARS.length, 23); - assert.equal(instantDpiGearIndex(200), 1); - assert.equal(instantDpiGearIndex(12800), 23); - assert.equal(instantDpiGearIndex(300), null); -}); - -test("status decode keeps the vendor block markers", () => { - const report = new Uint8Array([ - 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, - 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, - 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, - ]); - assert.deepEqual(decodeInstantStatus(report), { - firmware: 0x0954, - state: 0x00, - sensorCpi: 0x0626, - magicOk: true, - }); - assert.equal(decodeInstantStatus(new Uint8Array(8)), null); - const broken = report.slice(); - broken[16] = 0x00; - assert.equal(decodeInstantStatus(broken)?.magicOk, false); -}); - -test("config address map is the vendor's Apply layout", () => { - assert.deepEqual(INSTANT_CONFIG, { - header: 0x0000, - keymap: 0x0007, - stageEnable: 0x001c, - stageColorsA: 0x0020, - stageColorsB: 0x0028, - sensor: 0x0030, - lightingDirection: 0x003a, - lighting: 0x003e, - trailer: 0x0f80, - }); -}); +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + decodeInstantConfig, + decodeInstantReadByte, + decodeInstantStatus, + INSTANT_CONFIG, + INSTANT_DPI_GEARS, + INSTANT_REPORT_ID, + instantBlockReadByteFrame, + instantBlockReadFrames, + instantBlockWriteFrames, + instantDpiFrames, + instantDpiGearIndex, + instantFrame, + instantModeFrames, +} from "./protocol.ts"; + +function hex(frame: Uint8Array): string { + return Buffer.from(frame).toString("hex"); +} + +test("instantFrame pads to an 8-byte report 7 frame", () => { + assert.equal(hex(instantFrame(0x18, [0x03, 0])), "0718030000000000"); + assert.equal(instantFrame(0x18).length, 8); + assert.equal(instantFrame(0x18)[0], INSTANT_REPORT_ID); + assert.throws(() => instantFrame(0x18, [1, 2, 3, 4, 5, 6, 7]), RangeError); +}); + +test("block write matches the vendor's captured Apply frames", () => { + const frames = instantBlockWriteFrames(0x0000, [0x5a, 0x03]); + assert.deepEqual(frames.map(hex), [ + "0718030000005a01", + "0718030100000301", + "0718090000000001", + "0718000000000000", + ]); + const high = instantBlockWriteFrames(0x003a, [0x0b]); + assert.equal(hex(high[0]!), "071803003a000b00"); + assert.equal(hex(high[1]!), "071809003a000000"); +}); + +test("block read uses little-endian addresses and a final commit", () => { + const frames = instantBlockReadFrames(0x003a, 2); + assert.equal(frames.length, 3); + assert.equal(hex(frames[0]!), "071803003a000001"); + assert.equal(hex(frames[1]!), "071803013a000001"); + assert.equal(hex(frames[2]!), "071800003a000000"); + assert.equal(hex(instantBlockReadByteFrame(0x003a, 1, 2)), "071805013a000001"); + assert.throws(() => instantBlockReadByteFrame(0x003a, 1, 1), RangeError); + assert.throws(() => instantBlockReadByteFrame(0x10000, 0, 1), RangeError); + assert.throws(() => instantBlockReadFrames(0x003a, Number.NaN), RangeError); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07, 0x0b])), 0x0b); + assert.equal(decodeInstantReadByte(new Uint8Array([0x07])), null); +}); + +test("DPI frames match the vendor's 0x12 encoding", () => { + assert.deepEqual(instantDpiFrames(800).map(hex), [ + "0712640000000000", + "0711000000000000", + ]); + assert.deepEqual(instantDpiFrames(1600, 1).map(hex), [ + "0712006400000000", + "0711000000000000", + ]); + assert.throws(() => instantDpiFrames(300, 1), RangeError); + assert.throws(() => instantDpiFrames(123), RangeError); +}); + +test("mode frames enter and leave block mode", () => { + assert.equal(hex(instantModeFrames(true)[0]!), "0718100000000000"); + assert.equal(hex(instantModeFrames(false)[0]!), "0718000000000000"); +}); + +test("config decode keeps the lighting byte raw", () => { + // Ghidra: 0x3A packs light_direction/light_symmetry, not the polling rate. + const config = decodeInstantConfig(new Uint8Array([...new Uint8Array(0x3a), 0x0b])); + assert.equal(config.lightingDirectionByte, 0x0b); + assert.equal(config.bytes[0x3a], 0x0b); + assert.equal(decodeInstantConfig(new Uint8Array(0x3a)).lightingDirectionByte, null); +}); + +test("DPI table is the vendor's 23-value table", () => { + assert.equal(INSTANT_DPI_GEARS.length, 23); + assert.equal(instantDpiGearIndex(200), 1); + assert.equal(instantDpiGearIndex(12800), 23); + assert.equal(instantDpiGearIndex(300), null); +}); + +test("status decode keeps the vendor block markers", () => { + const report = new Uint8Array([ + 0x07, 0x00, 0x54, 0x09, 0x27, 0x00, 0x03, 0xcb, 0x11, 0x02, 0x00, 0x26, + 0x06, 0x00, 0x00, 0x10, 0x24, 0x5a, 0xa5, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + ]); + assert.deepEqual(decodeInstantStatus(report), { + firmware: 0x0954, + state: 0x00, + sensorCpi: 0x0626, + magicOk: true, + }); + assert.equal(decodeInstantStatus(new Uint8Array(8)), null); + const broken = report.slice(); + broken[16] = 0x00; + assert.equal(decodeInstantStatus(broken)?.magicOk, false); +}); + +test("config address map is the vendor's Apply layout", () => { + assert.deepEqual(INSTANT_CONFIG, { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, + }); +}); diff --git a/src/instant/protocol.ts b/src/instant/protocol.ts index e9f0b9a..5dc5448 100644 --- a/src/instant/protocol.ts +++ b/src/instant/protocol.ts @@ -1,356 +1,356 @@ -/** - * Instant Microelectronics A825 configuration protocol. - * - * Reverse-engineered from the vendor control app shipped for the Sades Kaze - * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` - * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a - * Sades Kaze on VID 0x30FA / PID 0x1440. - * - * Transport - * --------- - * The control collection is usage page 0xFF01, usage 1, on interface 1. Its - * only feature report is report ID 7. The vendor app and the device both use - * 8-byte feature reports: - * - * [0x07, command, a, b, c, d, e, f] - * - * The same report also carries a 32-byte status block that the device returns - * from a feature read; only the first eight bytes are used for command replies. - * - * Block access (command 0x18) - * --------------------------- - * The device exposes a 16-bit, little-endian addressed configuration memory. - * A block is written as one frame per byte, then finished and committed: - * - * 07 18 03 - * 07 18 09 00 00 - * 07 18 00 00 00 00 - * - * A byte is read by issuing the same address/length setup and then one frame - * per byte: - * - * 07 18 03 00 00 - * 07 18 00 00 00 00 - * 07 18 05 00 → reply byte 1 - * 07 18 00 00 00 00 - * - * Verified on hardware: writing the byte at 0x3A and reading it back returns - * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not - * the polling rate. The 0x0000-0x0FFF image is readable with - * `instantBlockReadFrames`. - * - * Direct commands - * --------------- - * The vendor app also writes a DPI value and a button map directly: - * - * 07 12 00 00 00 00 00 (mode 0) - * 07 12 ... (other modes) - * 07 11 00 ... commit - * 07 09 ... button map - * 07 17 ... 16-bit key/function code - * 07 13 ... lighting/mode - * - * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the - * 0x0F80 trailer). The direct commands above are read from the vendor code; - * sending 0x12 on the tested unit changed neither the stored image nor the - * status block. - */ - -export const INSTANT_VENDOR_ID = 0x30fa; - -/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ -export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ - 0x1440, 0x1e01, 0x7f7f, -]); - -export const INSTANT_USAGE_PAGE = 0xff01; -export const INSTANT_USAGE = 0x01; -export const INSTANT_INTERFACE = 1; - -export const INSTANT_REPORT_ID = 0x07; -export const INSTANT_FRAME_LENGTH = 8; -/** Status block returned by a feature read on report 7. */ -export const INSTANT_STATUS_LENGTH = 32; - -export const INSTANT_COMMAND = { - block: 0x18, - dpi: 0x12, - apply: 0x11, - buttonMap: 0x09, - keyCode: 0x17, - notice: 0x13, -} as const; - -export const INSTANT_BLOCK = { - write: 0x03, - read: 0x05, - finish: 0x09, - commit: 0x00, - mode: 0x10, -} as const; - -/** - * Configuration image addresses written by the vendor app's - * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes - * between blocks are untouched. - */ -export const INSTANT_CONFIG = { - header: 0x0000, - keymap: 0x0007, - stageEnable: 0x001c, - stageColorsA: 0x0020, - stageColorsB: 0x0028, - sensor: 0x0030, - lightingDirection: 0x003a, - lighting: 0x003e, - trailer: 0x0f80, -} as const; - -/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ -export const INSTANT_CONFIG_LENGTH = 0x1000; - -/** - * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array - * index + 1 is the on-wire gear index (the value the vendor app stores in a - * DPI stage); the second number in the INI is a separate firmware code. - */ -export const INSTANT_DPI_GEARS: readonly number[] = [ - 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, - 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, -]; - -export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; - -export function instantDpiGearIndex(dpi: number): number | null { - const index = INSTANT_DPI_GEARS.indexOf(dpi); - return index < 0 ? null : index + 1; -} - -function byte(value: number, name: string): number { - if (!Number.isInteger(value) || value < 0 || value > 0xff) { - throw new RangeError(`${name} is not a byte: ${value}`); - } - return value; -} - -/** Build one 8-byte report. `params` fills bytes 2..7. */ -export function instantFrame( - command: number, - params: readonly number[] = [], -): Uint8Array { - if (params.length > 6) { - throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); - } - const frame = new Uint8Array(INSTANT_FRAME_LENGTH); - frame[0] = INSTANT_REPORT_ID; - frame[1] = byte(command, "command"); - params.forEach((value, index) => { - frame[2 + index] = byte(value, `parameter ${index}`); - }); - return frame; -} - -/** Frames that write `data` to `address`, followed by finish and commit. */ -export function instantBlockWriteFrames( - address: number, - data: readonly number[], -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (data.length === 0 || data.length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${data.length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = data.length - 1; - const frames = data.map((value, index) => - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - byte(value, `data byte ${index}`), - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.finish, - 0, - low, - high, - 0, - last, - ]), - ); - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frames that prepare and read `length` bytes from `address`. */ -export function instantBlockReadFrames( - address: number, - length: number, -): Uint8Array[] { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (!Number.isInteger(length) || length < 1 || length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${length}`); - } - const low = address & 0xff; - const high = (address >>> 8) & 0xff; - const last = length - 1; - const frames: Uint8Array[] = []; - for (let index = 0; index < length; index += 1) { - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.write, - index, - low, - high, - 0, - last, - ]), - ); - } - frames.push( - instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.commit, - 0, - low, - high, - 0, - 0, - ]), - ); - return frames; -} - -/** Frame that requests byte `index` of the prepared read block. */ -export function instantBlockReadByteFrame( - address: number, - index: number, - length: number, -): Uint8Array { - if (!Number.isInteger(address) || address < 0 || address > 0xffff) { - throw new RangeError(`Invalid Instant block address: ${address}`); - } - if (!Number.isInteger(length) || length < 1 || length > 0x100) { - throw new RangeError(`Invalid Instant block length: ${length}`); - } - if (!Number.isInteger(index) || index < 0 || index >= length) { - throw new RangeError(`Instant block index ${index} is outside a ${length}-byte block`); - } - return instantFrame(INSTANT_COMMAND.block, [ - INSTANT_BLOCK.read, - index, - address & 0xff, - (address >>> 8) & 0xff, - 0, - length - 1, - ]); -} - -/** The value returned by a read byte frame lives at report byte 1. */ -export function decodeInstantReadByte(report: Uint8Array): number | null { - return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; -} - -/** Frames that set a live DPI value and commit it. */ -export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { - const gear = instantDpiGearIndex(dpi); - if (gear == null) { - throw new RangeError(`Unsupported A825 DPI: ${dpi}`); - } - if (mode === 0) { - const units = Math.round(dpi / 8); - if (units > 0xff) { - throw new RangeError( - `A825 mode 0 stores DPI/8 in one byte; ${dpi} needs the 16-bit mode`, - ); - } - return [ - instantFrame(INSTANT_COMMAND.dpi, [units, 0, 0, 0, 0, 0]), - instantFrame(INSTANT_COMMAND.apply), - ]; - } - const units = Math.round(dpi / 16); - return [ - instantFrame(INSTANT_COMMAND.dpi, [ - (units >>> 8) & 0xff, - units & 0xff, - 0, - 0, - 0, - 0, - ]), - instantFrame(INSTANT_COMMAND.apply), - ]; -} - -/** Enter or leave the block-write mode used at the end of an Apply. */ -export function instantModeFrames(enter: boolean): Uint8Array[] { - return [ - instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), - ]; -} - -export interface InstantConfigImage { - /** Bytes read from the configuration image; the array length is the requested range. */ - bytes: Uint8Array; - /** - * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and - * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); - * it is NOT the polling rate. Kept raw until the layout is fully named. - */ - lightingDirectionByte: number | null; -} - -export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { - return { - bytes, - lightingDirectionByte: - bytes.length > INSTANT_CONFIG.lightingDirection - ? bytes[INSTANT_CONFIG.lightingDirection]! - : null, - }; -} - -export interface InstantStatus { - /** Firmware/build word at bytes 2-3, little-endian (0x0954 on the Kaze). */ - firmware: number; - /** State byte 1; changes with device activity. */ - state: number; - /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ - sensorCpi: number; - /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ - magicOk: boolean; -} - -export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { - if (report.length < 20) return null; - const hasReportId = report.length === INSTANT_STATUS_LENGTH; - const offset = hasReportId ? 1 : 0; - if (hasReportId && report[0] !== INSTANT_REPORT_ID) return null; - if (report.length < offset + 19) return null; - return { - firmware: report[offset + 1]! | (report[offset + 2]! << 8), - state: report[offset]!, - sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), - magicOk: - report[offset + 15] === 0x24 && - report[offset + 16] === 0x5a && - report[offset + 17] === 0xa5, - }; -} +/** + * Instant Microelectronics A825 configuration protocol. + * + * Reverse-engineered from the vendor control app shipped for the Sades Kaze + * (Instant A825), `SadesKaze(A825).[20241009].exe` → `DevDock.exe` + * (product "New825Tab", VID 0x30FA, PIDs 0x1440/0x1E01), and verified against a + * Sades Kaze on VID 0x30FA / PID 0x1440. + * + * Transport + * --------- + * The control collection is usage page 0xFF01, usage 1, on interface 1. Its + * only feature report is report ID 7. The vendor app and the device both use + * 8-byte feature reports: + * + * [0x07, command, a, b, c, d, e, f] + * + * The same report also carries a 32-byte status block that the device returns + * from a feature read; only the first eight bytes are used for command replies. + * + * Block access (command 0x18) + * --------------------------- + * The device exposes a 16-bit, little-endian addressed configuration memory. + * A block is written as one frame per byte, then finished and committed: + * + * 07 18 03 + * 07 18 09 00 00 + * 07 18 00 00 00 00 + * + * A byte is read by issuing the same address/length setup and then one frame + * per byte: + * + * 07 18 03 00 00 + * 07 18 00 00 00 00 + * 07 18 05 00 → reply byte 1 + * 07 18 00 00 00 00 + * + * Verified on hardware: writing the byte at 0x3A and reading it back returns + * the written value (0x0B → 0x0A → 0x0B). That byte is a lighting field, not + * the polling rate. The 0x0000-0x0FFF image is readable with + * `instantBlockReadFrames`. + * + * Direct commands + * --------------- + * The vendor app also writes a DPI value and a button map directly: + * + * 07 12 00 00 00 00 00 (mode 0) + * 07 12 ... (other modes) + * 07 11 00 ... commit + * 07 09 ... button map + * 07 17 ... 16-bit key/function code + * 07 13 ... lighting/mode + * + * The vendor app's Apply writes the stored image (0x0000-0x02FF plus the + * 0x0F80 trailer). The direct commands above are read from the vendor code; + * sending 0x12 on the tested unit changed neither the stored image nor the + * status block. + */ + +export const INSTANT_VENDOR_ID = 0x30fa; + +/** PIDs seen on A825 controls. 0x7F7F comes from public GM320 research. */ +export const INSTANT_PRODUCT_IDS: ReadonlySet = new Set([ + 0x1440, 0x1e01, 0x7f7f, +]); + +export const INSTANT_USAGE_PAGE = 0xff01; +export const INSTANT_USAGE = 0x01; +export const INSTANT_INTERFACE = 1; + +export const INSTANT_REPORT_ID = 0x07; +export const INSTANT_FRAME_LENGTH = 8; +/** Status block returned by a feature read on report 7. */ +export const INSTANT_STATUS_LENGTH = 32; + +export const INSTANT_COMMAND = { + block: 0x18, + dpi: 0x12, + apply: 0x11, + buttonMap: 0x09, + keyCode: 0x17, + notice: 0x13, +} as const; + +export const INSTANT_BLOCK = { + write: 0x03, + read: 0x05, + finish: 0x09, + commit: 0x00, + mode: 0x10, +} as const; + +/** + * Configuration image addresses written by the vendor app's + * `A825_WriteLightingConfig` (0x480B00). Every write is a named block; bytes + * between blocks are untouched. + */ +export const INSTANT_CONFIG = { + header: 0x0000, + keymap: 0x0007, + stageEnable: 0x001c, + stageColorsA: 0x0020, + stageColorsB: 0x0028, + sensor: 0x0030, + lightingDirection: 0x003a, + lighting: 0x003e, + trailer: 0x0f80, +} as const; + +/** Readable configuration window; the vendor app writes 0x0000-0x02FF. */ +export const INSTANT_CONFIG_LENGTH = 0x1000; + +/** + * DPI gears from the vendor's `DeviceFeature.ini` `[Chip]` table. The array + * index + 1 is the on-wire gear index (the value the vendor app stores in a + * DPI stage); the second number in the INI is a separate firmware code. + */ +export const INSTANT_DPI_GEARS: readonly number[] = [ + 200, 400, 600, 800, 1000, 1200, 1400, 1600, 1800, 2000, 2400, 3200, 4000, + 4800, 5600, 6400, 7200, 8000, 8800, 9600, 10400, 11200, 12800, +]; + +export const INSTANT_POLLING_RATES: readonly number[] = [125, 250, 500, 1000]; + +export function instantDpiGearIndex(dpi: number): number | null { + const index = INSTANT_DPI_GEARS.indexOf(dpi); + return index < 0 ? null : index + 1; +} + +function byte(value: number, name: string): number { + if (!Number.isInteger(value) || value < 0 || value > 0xff) { + throw new RangeError(`${name} is not a byte: ${value}`); + } + return value; +} + +/** Build one 8-byte report. `params` fills bytes 2..7. */ +export function instantFrame( + command: number, + params: readonly number[] = [], +): Uint8Array { + if (params.length > 6) { + throw new RangeError(`Instant frame takes at most 6 parameters, got ${params.length}`); + } + const frame = new Uint8Array(INSTANT_FRAME_LENGTH); + frame[0] = INSTANT_REPORT_ID; + frame[1] = byte(command, "command"); + params.forEach((value, index) => { + frame[2 + index] = byte(value, `parameter ${index}`); + }); + return frame; +} + +/** Frames that write `data` to `address`, followed by finish and commit. */ +export function instantBlockWriteFrames( + address: number, + data: readonly number[], +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (data.length === 0 || data.length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${data.length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = data.length - 1; + const frames = data.map((value, index) => + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + byte(value, `data byte ${index}`), + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.finish, + 0, + low, + high, + 0, + last, + ]), + ); + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frames that prepare and read `length` bytes from `address`. */ +export function instantBlockReadFrames( + address: number, + length: number, +): Uint8Array[] { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (!Number.isInteger(length) || length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + const low = address & 0xff; + const high = (address >>> 8) & 0xff; + const last = length - 1; + const frames: Uint8Array[] = []; + for (let index = 0; index < length; index += 1) { + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.write, + index, + low, + high, + 0, + last, + ]), + ); + } + frames.push( + instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.commit, + 0, + low, + high, + 0, + 0, + ]), + ); + return frames; +} + +/** Frame that requests byte `index` of the prepared read block. */ +export function instantBlockReadByteFrame( + address: number, + index: number, + length: number, +): Uint8Array { + if (!Number.isInteger(address) || address < 0 || address > 0xffff) { + throw new RangeError(`Invalid Instant block address: ${address}`); + } + if (!Number.isInteger(length) || length < 1 || length > 0x100) { + throw new RangeError(`Invalid Instant block length: ${length}`); + } + if (!Number.isInteger(index) || index < 0 || index >= length) { + throw new RangeError(`Instant block index ${index} is outside a ${length}-byte block`); + } + return instantFrame(INSTANT_COMMAND.block, [ + INSTANT_BLOCK.read, + index, + address & 0xff, + (address >>> 8) & 0xff, + 0, + length - 1, + ]); +} + +/** The value returned by a read byte frame lives at report byte 1. */ +export function decodeInstantReadByte(report: Uint8Array): number | null { + return report.length > 1 && report[0] === INSTANT_REPORT_ID ? report[1] : null; +} + +/** Frames that set a live DPI value and commit it. */ +export function instantDpiFrames(dpi: number, mode = 0): Uint8Array[] { + const gear = instantDpiGearIndex(dpi); + if (gear == null) { + throw new RangeError(`Unsupported A825 DPI: ${dpi}`); + } + if (mode === 0) { + const units = Math.round(dpi / 8); + if (units > 0xff) { + throw new RangeError( + `A825 mode 0 stores DPI/8 in one byte; ${dpi} needs the 16-bit mode`, + ); + } + return [ + instantFrame(INSTANT_COMMAND.dpi, [units, 0, 0, 0, 0, 0]), + instantFrame(INSTANT_COMMAND.apply), + ]; + } + const units = Math.round(dpi / 16); + return [ + instantFrame(INSTANT_COMMAND.dpi, [ + (units >>> 8) & 0xff, + units & 0xff, + 0, + 0, + 0, + 0, + ]), + instantFrame(INSTANT_COMMAND.apply), + ]; +} + +/** Enter or leave the block-write mode used at the end of an Apply. */ +export function instantModeFrames(enter: boolean): Uint8Array[] { + return [ + instantFrame(INSTANT_COMMAND.block, [enter ? INSTANT_BLOCK.mode : 0, 0, 0, 0, 0, 0]), + ]; +} + +export interface InstantConfigImage { + /** Bytes read from the configuration image; the array length is the requested range. */ + bytes: Uint8Array; + /** + * Byte at 0x3A. Ghidra shows it packs the lighting direction, symmetry and + * a stage count (`FUN_00480b00` reads light_direction/light_symmetry here); + * it is NOT the polling rate. Kept raw until the layout is fully named. + */ + lightingDirectionByte: number | null; +} + +export function decodeInstantConfig(bytes: Uint8Array): InstantConfigImage { + return { + bytes, + lightingDirectionByte: + bytes.length > INSTANT_CONFIG.lightingDirection + ? bytes[INSTANT_CONFIG.lightingDirection]! + : null, + }; +} + +export interface InstantStatus { + /** Firmware/build word at bytes 2-3, little-endian (0x0954 on the Kaze). */ + firmware: number; + /** State byte 1; changes with device activity. */ + state: number; + /** Sensor value at bytes 11-12, little-endian; near the active DPI. */ + sensorCpi: number; + /** Bytes 17-19 are the fixed 0x24 0x5A 0xA5 marker. */ + magicOk: boolean; +} + +export function decodeInstantStatus(report: Uint8Array): InstantStatus | null { + if (report.length < 20) return null; + const hasReportId = report.length === INSTANT_STATUS_LENGTH; + const offset = hasReportId ? 1 : 0; + if (hasReportId && report[0] !== INSTANT_REPORT_ID) return null; + if (report.length < offset + 19) return null; + return { + firmware: report[offset + 1]! | (report[offset + 2]! << 8), + state: report[offset]!, + sensorCpi: report[offset + 10]! | (report[offset + 11]! << 8), + magicOk: + report[offset + 15] === 0x24 && + report[offset + 16] === 0x5a && + report[offset + 17] === 0xa5, + }; +}