CharlesMod/adventurer-k812-ist83025b
GitHub: CharlesMod/adventurer-k812-ist83025b
一份完整记录如何对基于 IST83025B 芯片的 Adventurer K812 键盘进行逆向工程、按键宏重映射及 RGB 配置的实用指南与配套工具。
Stars: 0 | Forks: 0
# 破解 Adventurer K812 RGB 键盘（无锡芯开微电子 **IST83025B**）
一份完整且可复现的指南，用于在 *Adventurer K812* 有线小键盘/宏键盘上**重映射按键、宏和 RGB**——并且更广泛地适用于任何基于**无锡芯开微电子（Wuxi Instant Microelectronics）** MCU 构建的廉价国产 RGB 键盘。
本文档记录了从“带有伪装标识的神秘芯片”到可用的自定义按键布局的完整逆向工程路径，那些会浪费你数小时时间的**隐蔽陷阱**（内置的 *Copy/Paste* 无法使用；宏仅在 *Game Mode* 下运行），以及一组用于从主机端识别任何 HID 键盘的只读 Python 工具。
## 硬件信息
| 项目 | 详情 |
|---|---|
| 产品 | "Adventurer K812" RGB 有线小键盘（数字小键盘 + 旋钮） |
| 芯片丝印 | `Inster 201` — **伪装/内部标识**，请忽略它 |
| 实际 MCU | **无锡芯开微电子 `IST83025B`**（8051 / MCS‑51 内核） |
| 存储 | 64K EEPROM（配置烧录在此处；固件本身为厂商掩模/闪存） |
| 常规 USB ID | `VID 0x30FA PID 0x2350`（产品字符串 "USB Keyboard"，制造商 "INSTANT"） |
| ISP/bootloader USB ID | `VID 0x30FA PID 0x2330`（烧录时设备重新枚举为此 ID） |
| 数据手册 | `https://www.instant-sys.com/uploads/pdf/norm/SPEC/IST83025B_Spec_CN_V1.02.pdf`（中文） |
| *此* 主板供应商 | "SHI XING SHENG" (海星升) |
`VID 0x30FA` **注册归属于无锡芯开微电子**——正因为物理芯片被打磨重标，这单一事实成为了识别其真实硅片核心的依据。"Inster" 仅仅是 "**Inst**ant" 的草率音译。
## 准备工作
1. **厂商烧录/配置工具** —— 一款名为 `英斯特IST83025B烧录程序V2.01.exe` 的 Windows 应用程序（"Instant IST83025B 烧录程序"）。
它既能**配置**键盘映射/LED/宏，又能将其**烧录**到芯片中。
由主板供应商销售/分发；搜索型号 + "烧录工具"，或直接向卖家索取。（这是一个原生 Delphi 应用；作为普通 HID 设备与主机通信，无需额外驱动。）
2. **Windows**（该工具仅限 Windows 使用）。
3. *（可选）* Python 3 + `pywinusb`，用于 [`tools/`](tools/) 中的主机端识别工具。
## 速成课程：工具 UI（中文 → 英文）
| 中文 | 英文 | 备注 |
|---|---|---|
| `普通模式` / `游戏模式` | Normal Mode / **Game Mode** | **两套独立的键盘映射。** 宏仅在 Game Mode 下运行 |
| `导入配置` / `导出配置` | Import / Export config | 读取/写入一个包含 `ExpOrImpFiles` 的 `.zip` 压缩包 |
| `保存配置` / `复位配置` | Save / Reset config | |
| `烧录` | **Burn / Flash** | 将配置写入设备 |
| `读取配置` | Read config (from device) | |
| `高级设置>>` | Advanced settings | 标签页包含：Fn/滚轮、**宏管理 (Macros)**、LED |
| `按键拷贝` → `拷贝按键` | "Key copy" → **Copy Keys** | 将 Normal-mode 的布局克隆到 Game Mode |
| `宏管理` | Macro management | 录制/存储宏 |
| `键盘录制` | Keyboard record | 将按键序列录制为宏 |
| `存储宏赋值` / `存储宏1..20` | Storage-macro assignment / slots 1–20 | 将录制好的宏绑定到指定插槽 |
| `常规重复` / `重复直到按键释放` / `重复直到再次按下` | Normal repeat (count) / repeat-until-release / repeat-until-pressed-again | **Ctrl+C/V 请使用 Normal repeat = 1** |
| `滚轮功能选择` `顺时`/`逆时` | Scroll-wheel function, CW/CCW | 旋钮功能（默认为音量 +/−） |
| `保存` / `确定` / `取消` | Save / OK / Cancel | |
工具的截图位于 [`screenshots/`](screenshots/)。
## 必须首先理解的关键概念
### 1. 矩阵以及配置如何索引按键
配置将按键寻址为 `KD__`（Key‑Down）和 `KU__`（Fn layer），其中芯片支持 8×20 矩阵。**K812 仅占用了 `r=0` 列**，因此它的 20 个按键为 `KD_0_0` … `KD_0_19`。在工具的网格中，这对应于**最左侧的数据列 (R0)**，行号为 **C0–C19**。
### 2. 三种“按键功能” —— 以及哪些真正有效
- **普通按键 / 修饰键**（例如 `Esc`, `F2`, `KeyPad 0`, `L-Alt`）：在 `KD_0_c` 中存储为**标准 USB-HID usage code**。它们能正常工作。 ✅
- **内置 `Copy` / `Paste` / 媒体键**：这些会发出 **HID *Consumer* usages**（AC Copy `0x021C`, AC Paste `0x021D` 等）。**Windows 和大多数应用程序会忽略它们** —— 按键看起来“毫无反应”。 ❌ *不要将这些用于 Ctrl+C/V。*
- **宏**：一段录制好的序列（例如 `Ctrl↓ C↓ C↑ Ctrl↑`），会发送真实的击键。 ✅ **但是宏仅在 Game Mode 下执行**（见下文）。
### 3. Normal Mode 与 Game Mode（重中之重）
这里有**两套独立的键盘映射**。宏是 Game Mode 的专属功能；绑定到宏的按键在 Normal Mode 下是无效的。为了日常使用宏，你需要让键盘保持在 **Game Mode**（通过 **FN+M** 切换；启用 **`FN+M模式保存`/mode-save** 使其在拔插后依然保持）。使用 **Copy Keys (`拷贝按键`)** 可以将你完整的 Normal-Mode 布局克隆到 Game Mode，这样*所有其他按键*在那里也能继续正常工作。
## 操作演示 —— 我们在 K812 上的配置
物理布局（4列；旋钮 = 音量；右下角的 **Enter 为 2 格高**）：
```
┌──────────┬──────────┬──────────┬──────────────┐ matrix col (R0 / C#):
│ C0 │ C1 │ C2 │ C3 │
│ LedMode │ KeyPad / │ KeyPad * │ Backspace │
├──────────┼──────────┼──────────┼──────────────┤
│ C4 KP7 │ C5 KP8 │ C6 KP9 │ C7 KP- │
├──────────┼──────────┼──────────┼──────────────┤
│ C8 KP4 │ C9 KP5 │ C10 KP6 │ C11 KP+ │
├──────────┼──────────┼──────────┼──────────────┤
│ C12 KP1 │ C13 KP2 │ C14 KP3 │ C15 KP Enter │
├──────────┼──────────┼──────────┤ (2-tall) │
│ C16 KP0 │ C17 "00" │ C18 KP. │ │
└──────────┴──────────┴──────────┴──────────────┘
```
三个“特殊”按键分别是 `C0 = LedMode`、`C17 = 00`（双零）、`C19 = KBD Mode`（它们不发出标准的键盘事件——属于厂商功能）。`C19` 不在上方的 4×5 物理网格中；它是额外的旋钮/按键。
### 我们的重映射（示例）
| 单元格 | 原厂设置 | 新设置 | 类型 |
|---|---|---|---|
| C0 | LedMode | **Esc** (HID 41) | plain |
| C3 | Backspace | **F2** (HID 59) | plain |
| C11 | KeyPad + | **L-Alt** (HID 226) | plain |
| C16 | KeyPad 0 | **Ctrl+C** | macro |
| C17 | 00 | **Ctrl+V** | macro |
| C18 | KeyPad . | **KeyPad 0** (HID 98) | plain |
### 步骤 1 — 加载你的主板配置
**以管理员身份**打开工具，插上小键盘，**`导入配置` (Import)** 你的主板原厂配置压缩包（或者从设备中**`读取配置`/Read**）。最左侧的列现在应该显示为 `KeyPad /`, `KeyPad *`, …，这证明加载成功。
### 步骤 2 — 设置普通按键
在 **R0** 列中，使用每个单元格的下拉菜单：C0→`ESCAPE`，C3→`F2`，C11→`L-Alt`，C18→`KeyPad 0`。（从长下拉菜单中按名称选择功能。）
### 步骤 3 — 录制宏
`高级设置>>` → **`宏管理`** 标签页：
1. `新建` (New) → 命名，例如 **Copy** → `键盘录制>>` → 点击 `录制` (Record) →
在键盘上按下 **Ctrl+C** → `停止` (Stop) → `确定`。步骤列表应该显示为 `[↓]L‑CTRL [↓]C [↑]C [↑]L‑CTRL`。将每个延迟修剪为 **~10 ms**。
2. 将重复选项设置为 **`常规重复` (Normal repeat) = 1**（否则它会一直狂按）。
3. 在 **`存储宏赋值`** 中，设置 **`存储宏1` → Copy**。为 **Paste** (Ctrl+V) 重复此过程 →
**`存储宏2`**。点击 `保存` 然后点击 `确定`。
### 步骤 4 — 在 **Game Mode** 中绑定宏
1. 将网格切换到 **Game Mode**（`按键拷贝` 框中的 `游戏模式` 单选框；
标题栏会显示 `[游戏模式]`）。
2. 点击 **`拷贝按键` (Copy Keys)**，将你的 Normal-Mode 布局克隆到 Game Mode
（这样 Esc/F2/Alt/KeyPad-0 和所有数字键都会被保留）。
3. 现在下拉菜单会暴露出你的宏 —— 设置 **C16 → `Copy1`**，**C17 → `Paste1`**。
### 步骤 5 — 烧录 & 将设备切换到 Game Mode
1. **`烧录` (Burn)**。成功的提示看起来像 `检测到64K EEPROM!` → `烧录完成`。
2. 在小键盘上按下 **FN + M** 进入 Game Mode（模式保存会让它保持在这个状态）。
如果你启用了 "WinLock light → mode indicator"，模式指示灯会发生变化。
3. 测试：选中文本 → **Copy 键** → 点击别处 → **Paste 键**。 🎉
## 参考
### 常用的 USB-HID 键盘 usage codes（存放在 `KD_0_c` 中的值）
```
4–29 = a–z 41 = Esc 58–69 = F1–F12
30–39 = 1 2 3 4 5 6 7 8 9 0 (top row) 40 = Enter 42 = Backspace
84 KP/ 85 KP* 86 KP- 87 KP+ 88 KP-Enter
89–97 = KP1..KP9 98 = KP0 99 = KP.
224 LCtrl 225 LShift 226 LAlt 227 LGui 228 RCtrl 229 RShift 230 RAlt 231 RGui
255 = unused/NULL 254 = "User Define" (macro key; only fires in Game Mode)
```
代码 ≥ ~125 且不是修饰键的通常是**厂商/消费者**功能
（Copy/Paste/媒体/LedMode/KBD-Mode）—— 理论上很方便，但在正常应用程序中，许多功能并不会如你预期的那样工作。
### `config.ini`（位于导出的 `ExpOrImpFiles.zip` 内）
- `[Init]` 块：`VID1/PID1` = **烧录** IDs (`0x30FA/0x2330`)，`VID2/PID2` =
**常规** IDs (`0x30FA/0x2350`)，`EEPROM=4`，以及主板/芯片名称。
- `[Config1]`：键盘映射 `KD_0_*` (基础层) 和 `KU_0_*` (Fn 层)，`DSCROLL0/1`
(旋钮)，`MACRO_MAP*` (宏插槽激活)，以及一大块 LED 配置
(`LED_COL_*` 4-bit RGB 调色板，`HR_/HG_/HB_*` 特效层，包括按键反应、区域，以及 `BOOT_LED` 原始动画帧)。
- 宏按键会设置 `KD_0_c = 254`；录制的步骤存在于二进制文件 `macro.dat` 中。
原厂 K812 导出文件包含在
[`reference/stock_ExpOrImpFiles/`](reference/stock_ExpOrImpFiles/) 中，可用于对比参考。
## 主机端工具（只读，不写入设备）
均位于 [`tools/`](tools/)，Python 3 + `pip install pywinusb`：
| 脚本 | 用途 |
|---|---|
| `oskeylog.py` | 全局低级键盘钩子；打印每个按键的 **scancode → HID code → matrix index**。这是映射物理按键的可靠方法，因为 Windows 占用了 HID 键盘集合，导致你无法直接读取它。 |
| `key_sniffer.py` | 枚举设备的 HID 集合并尝试读取原始输入报告（展示了为什么键盘集合不可读；但对厂商集合仍然有用）。 |
| `bootloader_watch.py` |监视 USB 枚举，以便你能捕捉到 `PID 0x2330` bootloader 的出现（例如在探测组合键进入 ISP 时）。 |
| `pe_recon.py` | 对厂商 `.exe` 进行静态的、只读的 PE 分析（导入表、字符串、嵌入的 blob）—— 我们就是这样得知它是基于 HID 传输且为原生 Delphi 应用的。 |
| `build_config.py` | 将重映射字典应用到原厂 `ExpOrImpFiles` 的副本上（这是针对*普通*按键的基于文件的路径）。 |
### 如何从主机端识别*任何*未知的 HID 键盘
```
# 列出 HID/USB 设备及其 VID:PID；制造商的 VID 标识了硅片
Get-PnpDevice -PresentOnly | ? { $_.Class -in 'HIDClass','USB','Keyboard' } |
Select Status,Class,FriendlyName,InstanceId
```
然后查找 VID（例如 the‑sz.com / devicehunt.com）。被打磨重标的芯片会撒谎；
**但 USB VID 通常不会。**
## 陷阱 / 故障排除
- **导入时提示 `备份失败!`** → **以管理员身份**运行此工具（它会在自己的安装目录中写入备份）。
- **重映射的按键“毫无反应”** → 你可能使用了 **consumer** 功能
(`Copy`/`Paste`/媒体)。请使用**宏**来实现真实的击键组合。
- **宏按键毫无反应** → 设备不在 **Game Mode** 下。按下 **FN+M**；
启用 **`FN+M模式保存`** 让设置保持生效；确保你在 **Game-Mode** 网格中绑定了宏，并使用了 **`拷贝按键`** 将你其他的布局带过来。
- **按住宏按键时一直狂按** → 将重复设置为 **`常规重复` = 1**。
- **宏执行后修饰键卡住** → 确保录制的步骤包含每个修饰键的**释放**事件 (`[↑]`)。
- 不要相信芯片的丝印标识；要相信 **USB VID**。
## 推导过程（给充满好奇心的读者 / LLMs）
1. 枚举 USB → 发现 `30FA:2350`；VID `0x30FA` = **Wuxi Instant**，因此 `Inster 201` 标识是假的。
2. 从厂商配置文件的 ReadMe 和数据手册中发现芯片是 **IST83025B** (8051)；从 `config.ini` 的 `[Init]` 注释中得知 bootloader 为 `PID 0x2330`。
3. 静态分析烧录 `.exe`（原生 Delphi，HID 传输 —— 因此刷写是 HID-ISP，无需焊接）。
4. 使用 **低级键盘钩子** (`oskeylog.py`) 映射物理按键 → 矩阵索引，解码 **scancodes**（与 NumLock 无关） → HID → 配置索引。
5. 对比导出的配置文件，以了解其数据格式（`KD_0_c` = HID code；`254` = 宏按键；宏位于 `macro.dat` 中）。
6. 通过经验发现了两个陷阱：内置的 Copy/Paste 发送的是 **consumer** usages（记录为*无键盘事件*），而宏**仅在 Game Mode 下**运行。
## 致谢 / 许可证
由社区为了互操作性和可维修性进行逆向工程并编写文档。厂商工具和固件归无锡芯开微电子 / 主板供应商所有；本仓库**不包含**任何厂商二进制文件 —— 仅包含主机端工具、笔记和配置参考。
基于 **MIT License** 发布（见 `LICENSE`）。非常欢迎为其他基于 Instant 微控制器的主板（不同的按键数量、LED 布局）提供贡献。
标签：HID工具, 云资产清单, 外设客制化, 宏键盘, 嵌入式开发, 硬件极客, 逆向工具, 逆向工程