RigZeeel/KeyAxis

## 这支持我的键盘吗？ **仅当 Windows 将其显示为 `VID 0416` / `PID 7372` 时有效。** 这包括 Redragon M68 / E-YOOSO HZ-68，以及同一主板更换品牌后的各种衍生名称。 检查方法：设备管理器 → 键盘 → 你的键盘 → 详细信息 → *硬件 ID*。 你需要找到 `HID\VID_0416&PID_7372`。 | 主板 | VID | PID | 状态 | |-------|-----|-----|--------| | Redragon M68 / E-YOOSO HZ-68 | `0x0416` | `0x7372` | ✅ 验证可用 | | *你的主板在这里* | — | — | [欢迎贡献](#adding-your-own-board) | 其他磁轴键盘（Wooting、Keychron、其他 Sinowealth 芯片）各自使用 其专有的通信协议，**无法直接使用** —— 但设备层是 可插拔的，因此添加新设备是一项相对独立的工作。详见下文。 ## 为什么会有这个项目 磁轴（"Hall-effect" / 霍尔效应）键盘不仅知道按键被按下 —— 它们还知道 **按键确切按下了多深**，大约在 0 到 4 毫米之间，分为 40 个步进。这完全满足了 油门踏板所需的一切条件。 该键盘将这些数据锁在内部，只使用只有厂商的网页配置工具才能听懂的私有协议进行通信。KeyAxis 的原理是对该通信进行“窃听”，破解其“常用语手册”，然后直接向键盘询问同样的问题。它会读取原始的约 1000 Hz 行程数据流，应用你设置的 死区和响应曲线，并将其馈送给**虚拟 Xbox 控制器**，而所有游戏都已经知道如何与之交互。 目前没有其他工具能在该键盘上实现这一点。 ## 安装说明 ### 简单方法 从 [Releases](../../releases) 下载 **`KeyAxis-Setup.exe`**。它会安装 应用程序，提示安装 ViGEmBus 驱动，并应用针对 Game Bar 弹窗的修复。 无需 Python。 ### 从源码安装 ``` python -m pip install -r requirements.txt python app.py ``` 或者直接双击 **`KeyAxis.bat`**，它会在首次运行时自动安装依赖项。 **系统要求：** Windows 10/11 64 位、Python 3.9+（仅源码运行需要），以及用于踏板输出的 [ViGEmBus 驱动](https://github.com/nefarius/ViGEmBus/releases)。Monitor 选项卡无需 ViGEmBus 即可工作。 ## 快速入门 1. **连接** —— 插入键盘，点击“连接”。 2. **校准一次**（约 1 分钟）—— 向导会学习每个按键对应的物理开关以及其实际最大按下深度。数据将永久保存，即使重装也会保留。 3. **绑定踏板** —— 点击 **Bind key**，然后只需*按下你想绑定的键* （或在屏幕上的键盘中点击它）。选择一个轴，调整死区和曲线。 4. **启动踏板** —— 虚拟控制器将会出现。像使用任何方向盘或手柄一样，在你的模拟器中绑定它。 应用内的 **Guide** 选项卡提供了图表、针对各款模拟器的配置指南和故障排除说明。 ## 唯一真正的陷阱：扳机合并 在现代的 **XInput** 游戏中，Xbox 的**扳机**（RT/LT）是保持独立的 —— 但在较老的 **DirectInput** 游戏中，它们会**合并到一个共享的 Z 轴上**。如果在旧版模拟器中将两个踏板分别绑定到 RT 和 LT，它们就会互相干扰。 | 游戏 | API | 配置指南 | |------|-----|--------| | **BeamNG.drive** | XInput | 油门 → **RT**，刹车 → **LT**。完美运行。 ✅ | | **Live for Speed** | DirectInput | 使用**摇杆**轴 —— 油门 → LSY，刹车 → RSY，离合 → RSX。 | | **MX Bikes** | DirectInput | 部分支持。它需要 **5** 个独立轴；而 Xbox 手柄无法提供五个。目前 3-4 个可以正常工作；完整支持需要计划中的 vJoy 输出模式。 | 如果两个踏板互相抵消了作用，那就是这个原因。把其中一个移到摇杆轴上即可。 ## 工作原理 - 打开键盘的**厂商 HID 接口**（即枚举出的 `usage_page == 0xff1b` 条目）。 - 发送 **ARM** 指令；当按键深度发生变化时，主板会流式传输事件驱动的数据帧。 - 每一帧都带有 **row**（行）、**col**（列）和 **depth 0–40** → 0.0–4.0 mm。 - 将行程深度针对该校准过的按键峰值进行归一化，然后应用死区 / 曲线 / - 反转，最后将其写入虚拟手柄的轴。 - 一个守护线程专门管理硬件和手柄。UI 仅轮询显示 - 状态，因此输入延迟完全不受界面影响。 - 在停止、断开连接和退出时总是会发送 **DISARM** 指令。 - 瞬时的 USB 断开（这块主板偶尔会出现此情况）会进行原位修复，而 - 不是直接断开你的连接。 UI 是原生 pywebview 窗口（WebView2）中的一个 HTML 页面。JS 通过 `window.pywebview.api.*` 与 Python 通信。这不使用 WebHID —— 因为 Chromium 屏蔽了对键盘的 HID 读取权限，这正是硬件层采用 Python 实现的原因。 ## 添加你自己的键盘 这是本项目中比较有趣的部分，也是我们采用 MIT 协议的原因。 每一把磁轴键盘都有自己专属的激活指令和数据帧布局，但其*基本形式*几乎总是相同的：发送指令激活数据流，接收 `(row, col, depth)`。 整个设备的定义在 [`app.py`](app.py) 中对应为一个 `DeviceProfile` —— 包含 VID、PID、usage page、arm bytes、disarm bytes 和 max depth。 要添加一款键盘： 1. 找到其厂商接口，并在其自带软件运行“行程测试”或类似功能时抓取通信流量（如果厂商工具是 Web 应用，使用 WebHID 控制台嗅探器效果很好）。 2. 识别出 ARM 写入指令以及包含 row/col/depth 的数据帧。 3. 添加一个 `DeviceProfile` 并将其附加到 `SUPPORTED_PROFILES` 中。 即使你无法独立完成后续开发，也请带上你的抓包数据提交一个 Issue —— 一份原始日志往往就足以让其他人帮你完成闭环。 ## 项目结构 | 文件 | 作用 | |------|-----------| | `app.py` | 后端：HID 读取线程，ViGEm 手柄，校准，JS↔Python API | | `ui.html` | 整个界面（内联 CSS + JS） | | `keysuppress.py` | 可选的低级钩子，用于阻止作为踏板的按键输入其原本的字母 | | `KeyAxis.spec` | PyInstaller 构建定义 | | `installer/KeyAxis.iss` | Inno Setup 安装脚本 | | `fix_gamebar.bat` | 终止 `ms-gamebar` 弹窗（可逆；使用 `undo_gamebar.bat` 恢复） | | `tools/assets.py` | 构建时的素材助手 —— 不随程序发布，运行也不需要 | 从源码运行时，用户数据（`calibration.json`、`settings.json`）保存在 `app.py` 所在的目录下，安装后则保存在 `%LOCALAPPDATA%\KeyAxis` 中。 ## 常见问题 **当按键作为踏板时，它还会输入原本的字母吗？** 是的，默认情况下会 —— 而且通常这正是你想要的，因为游戏经常将同一个按键用于其他功能（例如 BeamNG 中 W 键的作用不仅仅是油门）。如果你确实需要屏蔽字母输入，请在“设置”中开启 **suppress pedal keys**。这是一个全局钩子，因此最适合用在比赛过程中你不需要打字的按键上。 **总是会弹出一个 Microsoft Store 的窗口。** 每当虚拟控制器出现时，Windows 就会询问用于打开 `ms-gamebar` 的应用程序。运行一次 `fix_gamebar.bat` 即可解决。该操作完全可逆。 **提示“ViGEm not available”。** 请安装 [ViGEmBus](https://github.com/nefarius/ViGEmBus/releases) 并重启计算机。 **控制器在我的游戏中没有出现。** 首先检查 `joy.cpl`。如果轴在那里能移动，那仅仅是游戏内绑定的问题。如果在那里也看不到，说明 ViGEmBus 未安装或踏板尚未启动。 **这会损坏我的键盘吗？** 不会。KeyAxis 仅读取行程数据流，并发送文档中记录的 arm/disarm 指令。它绝不会写入固件或更改已保存的设置。 ## 路线图 - **vJoy 输出模式** —— 8 个真正独立的轴，这将彻底支持 MX Bikes。 - 通过可插拔的设备层支持更多键盘。 - 可拖拽的响应曲线编辑器。 - 多个同时运行的虚拟控制器。 ## 许可证 MIT —— 见 [`LICENSE`](LICENSE)。随意使用、复刻或发布。

标签：云资产清单, 后端开发, 游戏外设, 漏洞挖掘, 硬件适配, 虚拟手柄, 输入设备模拟, 逆向工具, 逆向工程, 霍尔效应键盘