diff --git a/README.md b/README.md index 0fcd87a..ff70d4a 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ checklist. | 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` | diff --git a/docs/a825-config-records.md b/docs/a825-config-records.md new file mode 100644 index 0000000..1f8f2f4 --- /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 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 new file mode 100644 index 0000000..964d17d --- /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` 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 new file mode 100644 index 0000000..9fcb1d2 --- /dev/null +++ b/docs/instant-a825.md @@ -0,0 +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`. 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..c14a5c4 --- /dev/null +++ b/src/drivers/instant/a825-hid.test.ts @@ -0,0 +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]); +}); diff --git a/src/drivers/instant/a825-hid.ts b/src/drivers/instant/a825-hid.ts new file mode 100644 index 0000000..c4ea5e8 --- /dev/null +++ b/src/drivers/instant/a825-hid.ts @@ -0,0 +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; + }); + } +} 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/index.ts b/src/index.ts index ce0629f..c7df9b1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -33,6 +33,7 @@ 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"; 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..09ceede --- /dev/null +++ b/src/instant/protocol.test.ts @@ -0,0 +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, + }); +}); diff --git a/src/instant/protocol.ts b/src/instant/protocol.ts new file mode 100644 index 0000000..5dc5448 --- /dev/null +++ b/src/instant/protocol.ts @@ -0,0 +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, + }; +}