Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
88 changes: 88 additions & 0 deletions docs/a825-config-records.md
Original file line number Diff line number Diff line change
@@ -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)` |
98 changes: 98 additions & 0 deletions docs/devdock-functions.md
Original file line number Diff line number Diff line change
@@ -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 <index> <addrLo> <addrHi> <data> <length-1>
```

one frame per byte, then:

```
07 18 09 00 <addrLo> <addrHi> 00 <length-1>
07 18 00 00 <addrLo> <addrHi> 00 00
```

Addresses are little-endian. The wait between the finish and commit frames is
12 ms.

## Read

```
07 18 03 00 <addrLo> <addrHi> 00 <length-1>
07 18 00 00 <addrLo> <addrHi> 00 00
07 18 05 <index> <addrLo> <addrHi> 00 <length-1> → feature report byte 1
07 18 00 00 <addrLo> <addrHi> 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 <DPI/8> mode 0
07 12 <DPI/16 high> <DPI/16 low> 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.
202 changes: 202 additions & 0 deletions docs/instant-a825.md
Original file line number Diff line number Diff line change
@@ -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 <command> <p1> <p2> <p3> <p4> <p5> <p6>
```

Status read on report 7:

```
07 <state> 54 09 27 00 03 CB 11 <n> 00 <cpiLo> <cpiHi> 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 <index> <addrLo> <addrHi> <data> <length-1>
07 18 09 00 <addrLo> <addrHi> 00 <length-1>
07 18 00 00 <addrLo> <addrHi> 00 00
```

Read:

```
07 18 03 00 <addrLo> <addrHi> 00 <length-1>
07 18 00 00 <addrLo> <addrHi> 00 00
07 18 05 <index> <addrLo> <addrHi> 00 <length-1> → reply byte 1
07 18 00 00 <addrLo> <addrHi> 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 <DPI/8> 00 00 00 00 00 mode 0
07 12 <DPI/16 high> <DPI/16 low> … 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 <byte> 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`.
Loading
Loading