SupperTomato/d06-pro-ring-mouse-toolkit
GitHub: SupperTomato/d06-pro-ring-mouse-toolkit
为 D06 Pro 指环鼠标提供 Android 输入解码 SDK 与 Linux 抓包检查工具，帮助开发者和用户在移动端及桌面端理解、测试和重新映射该设备的按键与手势输入。
Stars: 0 | Forks: 0
# D06 Pro 指环鼠标工具包
语言：English | [简体中文](README.zh-CN.md)
本项目旨在帮助大家了解并在 Android 和 Linux 上使用 D06 Pro 指环鼠标。
简单来说：D06 Pro 的行为就像一个普通的蓝牙或 USB 鼠标。本仓库记录了每个按键和手势发送的信号，提供了一个 Android SDK/示例应用，并包含用于检查指环鼠标状态的 Linux 工具。
有关 SDK 各个部分、命令和事件所能实现功能的通俗说明，请参阅 [FUNCTIONS.md](FUNCTIONS.md) 或 [简体中文](FUNCTIONS.zh-CN.md)。
有关 SDK 性能优化建议，请参阅 [PERFORMANCE.md](PERFORMANCE.md) 或 [简体中文](PERFORMANCE.zh-CN.md)。
## 适用人群
- 想了解各按键实际功能的 D06 Pro 用户。
- 希望在手机或平板上测试指环鼠标的 Android 用户。
- 希望在应用内解码 D06 输入的 Android 应用开发者。
- 希望检查或转换 D06 输入事件的 Linux 用户。
- 需要捕获的 HID/BLE 证据的逆向工程用户。
## 当前状态
已支持功能：
- 左键、右键和中键点击解码
- 上/下滚动解码
- 触控板移动方向映射
- 触控板点击/双击观察
- Android 输入解码器 SDK
- Android 示例应用
- Linux `evdev` 解码器
- Linux `hidraw` 和 BLE/GATT 检查工具
- Linux 上的 USB 接收器检测
仍有限制：
- 原生 Android 应用无法在全局范围内替换所有的硬件鼠标事件
- 在 HID 层级上，触控板点击与物理左键点击可能看起来完全相同
- 隐藏的按键 4/5、键盘模式和媒体模式仍需更多真机抓包数据
- 故意不支持对厂商/Telink 的写入操作
## 简易 Android 用法
用于常规测试：
1. 通过蓝牙将 D06 Pro 与您的 Android 设备配对，或通过 USB-OTG 连接 2.4 GHz 接收器。
2. 编译并安装示例应用：
```
cd android-sdk
./gradlew :d06-sample:installDebug
```
3. 打开 **D06 SDK Sample**。
4. 按下按键并滑动触控板。应用将显示解码后的 D06 事件。
目前，本仓库中尚未提供打包好的应用发行版（APK）。您仍然需要使用 Gradle/Android Studio，或者请他人为您编译示例 APK。
## 简易 Linux 用法
列出可能的 D06 输入设备：
```
python3 tools/linux/d06_evdev.py --list
```
打印解码后的事件：
```
python3 tools/linux/d06_evdev.py --seconds 30
```
如果 Linux 阻止了对 `/dev/input/event*` 的访问，请使用 `sudo` 运行、加入 `input` 用户组，或者安装位于 `tools/linux/99-d06-pro.rules` 的 udev 规则模板。
该 Linux 工具仅打印事件。它不会接管鼠标，也不会阻止指针的正常移动。
## 按键和手势映射表
| D06 动作 | 主机看到的内容 | SDK 事件 |
| --- | --- | --- |
| 左键点击 | 鼠标左键按下/抬起 | `LeftDown`, `LeftUp` |
| 右键点击 | 鼠标右键按下/抬起 | `RightDown`, `RightUp` |
| 中键点击 | 鼠标中键按下/抬起 | `MiddleDown`, `MiddleUp` |
| 向上滚动 | 鼠标滚轮正向步进 | `Scroll(Up, units)` |
| 向下滚动 | 鼠标滚轮负向步进 | `Scroll(Down, units)` |
| 触控板向右 | 相对 `+X` 移动 | `MousepadMove(+dx, 0)` |
| 触控板向左 | 相对 `-X` 移动 | `MousepadMove(-dx, 0)` |
| 触控板向上 | 相对 `-Y` 移动 | `MousepadMove(0, -dy)` |
| 触控板向下 | 相对 `+Y` 移动 | `MousepadMove(0, +dy)` |
| 触控板点击 | 与左键点击模式相同 | 仅在启用了点击检测时触发 `MousepadTap` |
| 触控板双击 | 重复的左键点击对 | 重复的点击/按键事件 |
相关说明书可能会描述诸如“下一个视频”、“点赞”或“相机”之类的应用操作。在设备底层，这些通常都是普通的鼠标、键盘或媒体控制事件。这些事件的具体含义由应用自行决定。
## 面向开发者的 Android SDK
SDK 位于 `android-sdk/` 目录下。
| 模块 | 用途 |
| --- | --- |
| `d06-core` | 纯 Kotlin 编写的 D06 事件模型和映射器 |
| `d06-input` | Android `MotionEvent` / `KeyEvent` 解码器 |
| `d06-ble` | BLE/GATT 元数据和电量助手 |
| `d06-remapper` | 功能受限的 AccessibilityService 重映射助手 |
| `d06-sample` | 用于真机测试的示例应用 |
编译所有内容：
```
cd android-sdk
./gradlew test assembleDebug
```
发布到 Maven local：
```
cd android-sdk
./gradlew publishToMavenLocal
```
如需基于本地源码开发，可以通过邻近的克隆仓库引入这些模块：
```
include(":d06-core")
project(":d06-core").projectDir = file("../d06-pro-ring-mouse-toolkit/android-sdk/d06-core")
include(":d06-input")
project(":d06-input").projectDir = file("../d06-pro-ring-mouse-toolkit/android-sdk/d06-input")
include(":d06-ble")
project(":d06-ble").projectDir = file("../d06-pro-ring-mouse-toolkit/android-sdk/d06-ble")
```
基础解码器用法：
```
class MainActivity : Activity() {
private val d06 = D06Input(
D06InputConfig(detectMousepadTap = true)
) { event ->
// Handle LeftDown, Scroll, MousepadMove, MousepadTap, etc.
}
override fun dispatchGenericMotionEvent(ev: MotionEvent): Boolean {
return d06.dispatch(ev) || super.dispatchGenericMotionEvent(ev)
}
override fun dispatchKeyEvent(event: KeyEvent): Boolean {
return d06.dispatch(event) || super.dispatchKeyEvent(event)
}
}
```
有关完整的 SDK 用法、重映射预设、诊断以及 BLE 权限说明，请参阅 [android-sdk/README.md](android-sdk/README.md)。
## Linux 和 Android 抓包工具
Linux：
```
python3 tools/linux/d06_evdev.py --list
python3 tools/linux/d06_evdev.py --seconds 10
python3 tools/linux/d06_hid.py --list
sudo python3 tools/linux/d06_hid.py --dump --out artifacts/linux/hid/hid_caps.json
python3 tools/linux/dump_d06_gatt.py --address AA:BB:CC:DD:EE:FF --out-dir artifacts/linux/gatt
```
在 Linux 主机上通过 USB 或无线调试连接 Android：
```
tools/android/d06_android_input.sh list
tools/android/d06_android_input.sh capture --seconds 10 --out artifacts/android/getevent/android_getevent.txt
tools/android/d06_android_input.sh dump-input --out artifacts/android/dumpsys/input.txt
```
## 仓库目录说明
| 路径 | 包含内容 |
| --- | --- |
| `android-sdk/` | Android SDK 模块和示例应用 |
| `tools/` | Linux 和 Android 抓包工具 |
| `artifacts/` | 来自 Android、Linux 以及历史主机抓包的分组数据 |
| `FUNCTIONS.md` / `FUNCTIONS.zh-CN.md` | 工具包功能和特性的通俗指南 |
| `PERFORMANCE.md` / `PERFORMANCE.zh-CN.md` | SDK 性能优化指南 |
| `D06_PRO_RE.md` | 详细的逆向工程笔记 |
| `docs/research/` | SDK 功能研究 |
| `docs/superpowers/` | 实现规格和计划 |
## 安全与隐私
- 本项目不会刷入固件。
- 本项目不会对厂商/Telink 服务执行写入操作。
- 抓包文件可能包含设备名称、硬件 ID 或蓝牙地址。
- Android 重映射机制有意设计得比较保守，因为原生 Android 系统不允许普通应用在系统范围内替换所有的硬件鼠标输入。
标签：Android, DSL, 云资产清单, 后台面板检测, 硬件工具包, 蓝牙, 输入设备, 逆向工具, 逆向工程, 鼠标