TinyMouse 是一款基于 WCH CH592F 蓝牙低功耗（BLE）芯片的 五向遥控 + 空中鼠标 设备。通过内置 QMI8658 六轴 IMU，可在「媒体遥控」与「空中鼠标」两种模式间切换，支持自定义按键映射、多 Profile、宏序列，以及网页蓝牙配置与 OTA 固件升级。
当前固件版本：v5.5（硬件版本 v1）
目录
硬件与规格
| 项目 | 说明 |
|---|---|
| 主控 | WCH CH592F（RISC-V，448 KB Flash，26 KB SRAM，集成 BLE 5.x） |
| 传感器 | QMI8658A 六轴 IMU（I2C 地址 0x6A，PB14=SDA / PB15=SCL） |
| 按键 | 五向键：上 / 下 / 左 / 右 + 中央 OK |
| 指示灯 | RGB 三色 LED（共阴，高电平点亮） |
| 蓝牙名称 | 默认 TinyMouse-XXXX（XXXX 为 MAC 后四位，可自定义） |
| HID 能力 | 蓝牙 HID：键盘、Consumer 媒体键、鼠标（含空中移动） |
设备作为标准 BLE HID 外设，配对后可在 Windows / macOS / Linux / Android / iOS 上被识别为蓝牙键盘/鼠标，无需安装专用驱动（配置面板除外）。
功能概览
- 双模式：媒体遥控模式 + 空中鼠标模式，可按键或网页切换
- 5 套 Profile：每套含 9 个独立按键事件（方向键短/长按 + OK 短按），互不影响
- 多步宏：每个事件最多 4 步 HID 序列（如 Ctrl+C → 等待 100ms → Ctrl+V）
- 持久化配置：按键映射、时序参数、鼠标算法参数、陀螺仪校准均写入 Flash
- 网页配置：Flask + Web Bluetooth 配置面板，浏览器直连设备 BLE，无需桌面客户端
- OTA 升级：支持在线或本地
.bin固件蓝牙升级 - 省电设计：空闲自动关机；鼠标模式才持续读取 IMU
快速开始
1. 开机与配对
- 按任意键唤醒设备（若已关机，GPIO 下降沿唤醒）
- 设备进入蓝牙广播，LED 以 红 → 绿 → 蓝 三色循环闪烁（未连接状态）
- 在电脑或手机的 系统蓝牙设置 中搜索并配对
TinyMouse-xxxx - 配对成功后 LED 熄灭；设备即可作为 HID 键鼠使用
提示：网页配置面板的「连接设备」与系统蓝牙配对是 两回事。网页连接用于读写配置；日常使用媒体键/鼠标只需系统配对即可。
2. 首次使用建议
- 登录后点击「连接设备」，完成 BLE 配置通道连接
- 用 Chrome / Edge 打开配置面板（见 网页配置面板）
- 在「鼠标参数」中确认陀螺仪已校准；若显示未校准，点击「重新校准」并保持设备静止约 2 秒
- 按需修改 Profile 0 的按键映射，或切换到其他 Profile
3. 关机与唤醒
| 状态 | 无操作超时（默认） | 行为 |
|---|---|---|
| 已连接 | 3 分钟 | 当前模式色闪 3 次后关机 |
| 未连接（广播中） | 1 分钟 | 同上 |
| 网页配置会话中 | 5 分钟无配置写入 | 恢复普通过期后关机 |
任意按键可再次唤醒设备。
工作模式
媒体模式（默认）
五向键发送 键盘键 或 Consumer 媒体键，适合控制音乐、视频、PPT、手机等。具体动作由当前活跃 Profile 决定。
鼠标模式
| 操作 | 功能 |
|---|---|
| 手腕移动 | 空中移动光标（IMU 驱动） |
| LEFT | 鼠标左键（支持按住拖拽） |
| RIGHT | 鼠标右键 |
| OK | 鼠标中键 |
| UP / DOWN | 键盘 PageUp / PageDown（长按自动重复，方便翻页） |
进入鼠标模式后，设备会加载 Flash 中已保存的陀螺仪零偏；切换模式本身不会重新校准。若未校准，LED 红灯持续闪烁，鼠标移动与按键会被屏蔽。
模式切换方式
| 方式 | 操作 | 条件 |
|---|---|---|
| 按键组合 | 同时按住OK + LEFT + DOWN 约 8 秒 | 须已连接；UP / RIGHT 不能按下 |
| 网页 | 配置面板顶部「媒体 / 鼠标」切换按钮 | 须网页 BLE 已连接 |
切换成功时 LED 会 R → G → B 各亮一次。
按键操作详解
媒体模式下的按键逻辑
- 短按：松手时触发一次
- 长按：按住达到阈值（默认 800ms）立即触发；继续按住则按间隔（默认 400ms）重复发送
- 单键原则（solo）：按压期间若有其他键同时按下，该键的短/长按动作会被取消，避免误触
鼠标模式下的按键逻辑
- 左/右键：按下立即发送、松开立即释放，支持多键同时按住
- 按键时会短暂抑制 IMU 移动（默认 200ms），防止按键震动导致光标乱跳
系统保留组合键（不可通过网页修改）
以下组合键在固件中硬编码，Profile 映射无法覆盖：
| 组合键 | 按住时长（默认） | 功能 | 连接要求 |
|---|---|---|---|
| OK 长按 | 3 秒 | 切换到下一个已配置 的 Profile | 已连接 |
| OK + LEFT + DOWN | 8 秒 | 切换媒体 / 鼠标模式 | 已连接 |
| OK + UP + RIGHT | 10 秒 | 恢复出厂（配置回默认、清除配对、重新校准） | 未连接也可用 |
| OK + DOWN | 10 秒 | 清除设备端配对并重新广播（保留配置） | 未连接也可用；已连接时须为媒体模式 |
OK 长按 在媒体模式下用于 Profile 切换，因此 OK 长按事件不可自定义（网页中显示为「系统：切换 Profile」）。
恢复出厂 vs 清除配对
| 操作 | 配置 | 配对记录 | 蓝牙名称 | 陀螺仪校准 |
|---|---|---|---|---|
| 网页「恢复出厂」 | 回默认 | 清除 | 保留 | 自动重新校准 |
| 设备OK+UP+RIGHT 10 秒 | 回默认 | 清除 | 保留 | 自动重新校准 |
| 设备OK+DOWN 10 秒 | 保留 | 清除 | 保留 | 保留 |
| 网页「断开连接」 | 保留 | 保留 | 保留 | 保留 |
若仅在手机/电脑系统设置里删除了 TinyMouse，设备端可能仍保留旧配对，导致无法重连。此时可 未连接状态下 按住 OK+DOWN 约 10 秒清除设备端 Bond，再在系统中重新配对。
Profile 与默认映射
设备内置 5 套 Profile，通过不同 LED 颜色区分（媒体模式下按键反馈色）：
| Profile | LED 颜色 | 出厂默认内容 |
|---|---|---|
| 0 | 黄 | 经典音乐媒体控制（见下表） |
| 1 | 绿 | 空（所有按键无动作） |
| 2 | 青 | 空 |
| 3 | 蓝 | 空 |
| 4 | 紫（品红 R+B） | 空 |
Profile 3 标注为「橙」，因板载 LED 为数字三色（无 PWM），无法用 RGB 混出橙色，固件以蓝色代替以保证五色互不相同。
Profile 0 出厂默认映射
| 按键 | 短按 | 长按 |
|---|---|---|
| UP | 键盘 ↑ | 音量 + |
| DOWN | 键盘 ↓ | 音量 − |
| LEFT | 键盘 ←（视频后退数秒） | 上一曲 |
| RIGHT | 键盘 →（视频前进数秒） | 下一曲 |
| OK | 播放 / 暂停 | 系统：切换 Profile |
左右短按使用键盘方向键而非 Consumer「快进/快退」，是因为多数播放器对点按 seek 不响应，而方向键在 YouTube、VLC、网页播放器上通用。
Profile 切换
- 按键：媒体模式下 OK 单键长按（默认 3 秒）→ 跳转到下一个 至少有一个按键已配置 的 Profile
- 网页：Profile 标签页 →「设为活跃」
- 切换后 LED 闪两下对应 Profile 颜色，配置立即生效并写入 Flash
可将 Profile 1~4 配置为 PPT 演讲、短视频浏览、办公快捷键等场景，通过 OK 长按或网页快速切换。
LED 状态说明
| 状态 | LED 表现 |
|---|---|
| 未连接 / 广播中 | 红 → 绿 → 蓝 循环（每种约 1 秒） |
| 已连接 | 熄灭（按键时可能短暂闪烁，取决于设置） |
| 模式 / Profile 切换 | R → G → B 各亮一次 |
| 组合键计时中 | R/G/B 各亮 1 秒、灭 1 秒循环 |
| 即将关机 | 当前活动色闪 3 次 |
| 鼠标模式未校准 | 红灯持续慢闪（250ms 亮/灭） |
| IMU 读取故障 | 红灯急促闪（100ms 亮/灭） |
| HID 通道异常 | 红灯常亮 1 秒 |
| OTA 写入中 | 每收到一包固件蓝灯闪一下 |
活动色规则：媒体模式 = 当前 Profile 颜色；鼠标模式 = 蓝色。纯红色 reserved 用于错误提醒，不作为 Profile 正常色。
可在网页「鼠标参数」中关闭「按键 LED 闪烁」（仅影响已连接时的按键反馈，未连接三色动画不受影响）。
网页配置面板
配置面板位于 tools/configurator/，采用 Flask 后端 + Web Bluetooth 前端 架构：
- 后端：用户登录 / 注册 / 管理（SQLite）
- 前端：通过浏览器 Web Bluetooth API 直连设备，配置数据不经过服务器
浏览器要求
Web Bluetooth 目前仅 Chromium 内核 支持：
| 平台 | 推荐浏览器 |
|---|---|
| Windows / Linux | Chrome、Edge、Brave |
| macOS | Chrome、Edge、Brave |
| Android | Chrome、Edge |
| iOS / iPadOS | Bluefy（Safari 不支持 Web Bluetooth） |
访问地址须为 https:// 或 http://localhost（本地开发默认 http://localhost:8080）。
本地运行
cd tools/configurator
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
python app.py
默认管理员：admin / admin123（首次登录强制改密）
生产部署、Docker、HTTPS 反代等详见 tools/configurator/README.md。
配置面板功能一览
| 功能区 | 说明 |
|---|---|
| 设备连接 | Web Bluetooth 连接、断开、刷新设备信息 |
| 模式切换 | 媒体 / 鼠标模式远程切换 |
| 蓝牙名称 | 自定义广播名（最多 14 字节），留空恢复默认 |
| 信号诊断 | 实时 RSSI 曲线，判断连接质量 |
| Profile | 5 套配置切换、设为活跃、清空、JSON 导入/导出、恢复出厂 |
| 按键映射 | 五向键可视化布局，短/长按独立编辑，支持多步宏 |
| 系统参数 | 休眠时间、长按阈值、模式切换阈值等（毫秒级，逐项保存） |
| 鼠标参数 | 反转/互换/倾斜补偿/灵敏度/死区/平滑/指针加速度、陀螺仪重新校准 |
| 固件升级 | 在线检查更新或本地 .bin OTA |
| 通信日志 | TX/RX/ACK 实时着色，便于调试 |
配置备份建议
固件 跨配置结构版本 OTA 升级 时，除陀螺仪校准和自定义蓝牙名外，其余配置可能恢复默认。升级前请使用 导出 JSON 备份 Profile 与参数。
固件升级 OTA
- 网页 BLE 连接设备
- 打开「固件升级」卡片
- 选择 在线升级（检查并下载最新版）或 本地升级（选择 ImageA 固件
.bin） - 升级过程中 请勿断电或断开蓝牙，LED 蓝灯随包闪烁表示写入进度
- 完成后设备自动重启
OTA 期间设备不会进入自动关机。若升级失败，可重新连接后再次尝试；必要时使用 WCH 官方工具通过 SWD 烧录救砖。
开发者指南
项目结构
TinyMouse/
├── APP/ # 应用层源码（HID、按键、空中鼠标算法）
│ ├── hidmouse_main.c # 主循环、按键处理、IMU 鼠标
│ ├── hidmouse.c # BLE HID 设备层
│ └── Profile/ # GATT 服务（配置、OTA、电池等）
├── CH592/ # WCH MRS 工程（链接 APP/ 目录）
│ ├── CH592.wvproj # MounRiver Studio 工程文件
│ └── obj/CH592.hex # 编译产物
├── tools/
│ ├── configurator/ # 网页配置面板
│ └── ota_led_test/ # OTA LED 测试工具
├── BLE_PROTOCOL.md # BLE 配置协议 v2 完整说明
└── README.md # 本文档
编译固件
- 安装 MounRiver Studio 及 WCH RISC-V 工具链
- 用 MRS 打开
CH592/CH592.wvproj - 编译生成
CH592/obj/CH592.hex（或.bin用于 OTA）
修改固件版本号
编辑 APP/include/tinymouse_version.h：
#define TINYMOUSE_FW_MAJOR 5
#define TINYMOUSE_FW_MINOR 5
#define TINYMOUSE_FW_VERSION_STR "v5.5"
FW_MAJOR/FW_MINOR与VERSION_STR须保持一致，否则网页显示版本可能不正确。
BLE 配置协议
设备暴露自定义 GATT 服务：
| 项目 | UUID |
|---|---|
| Config Service | 0xFFF0 |
| RX（写入命令） | 0xFFF1 |
| TX（读取/通知） | 0xFFF2 |
协议详情、HID 编码表、JavaScript/Python 示例见 BLE_PROTOCOL.md。
默认系统参数（可网页修改）
| 参数 | 默认值 | 说明 |
|---|---|---|
| 连接超时关机 | 180000 ms（3 分钟） | 已连接无操作 |
| 断开超时关机 | 60000 ms（1 分钟） | 未连接广播 |
| 长按阈值 | 800 ms | 媒体模式方向键 |
| 长按重复间隔 | 400 ms | 长按持续按住 |
| 模式切换阈值 | 8000 ms | OK+LEFT+DOWN |
| 恢复出厂阈值 | 10000 ms | OK+UP+RIGHT |
| Profile 切换阈值 | 3000 ms | OK 单键长按 |
| 清配对阈值 | 10000 ms | OK+DOWN |
| 鼠标轮询间隔 | 10 ms | 100 Hz |
| 鼠标校准时长 | 2000 ms | 静止采样 |
| 按键抑制时长 | 200 ms | 鼠标模式按键后冻结移动 |
默认鼠标参数
| 参数 | 默认值 |
|---|---|
| 灵敏度 | 100（范围 1~200） |
| 死区 | 40 LSB |
| 平滑度 (EMA) | 160 |
| 默认标志 | Y 反转 + 倾斜补偿 + 按键 LED 闪烁 + 指针加速度 |
注意事项
使用方面
- 两种连接：系统蓝牙配对用于 HID 键鼠；网页 Web Bluetooth 用于配置。网页「断开连接」不会清除系统配对。
- iOS 限制：Safari 不支持 Web Bluetooth，请用 Bluefy；Consumer 键在 iOS 上部分可用（如音量、播放），「返回」键无效。
- Android 返回键：Consumer
AC Back (0x0224)在 Android 有效，iOS 无效。 - Windows Y 轴：若电脑与手机光标 Y 轴方向相反，在网页勾选「Y 反转」并保存。
- 空中鼠标校准：校准时请保持设备 完全静止；手持晃动会导致零偏错误、光标漂移。
- 组合键互斥：执行组合键计时期间，相关单键动作会被屏蔽，须等全部按键松开。
- 省电：长时间不用会自动关机；连接状态下比广播状态等待更久才关机。
配对与重连
- 仅在系统侧删除配对 → 设备端可能仍记旧 Bond → 用 OK+DOWN 清除
- 清配对 不会 清除按键配置；恢复出厂 会 清除配置但 保留 自定义蓝牙名
- 恢复出厂或 OTA 后若无法连接，先在设备上清配对，再在系统中删除并重新配对
升级与数据
- 大版本 OTA 可能重置按键映射（保留校准和蓝牙名），请提前 导出 JSON
- OTA 过程中禁止断电
- 恢复出厂会触发陀螺仪重新校准（约 2 秒静止）；若此时设备在动，会尽量保留上一次有效校准
开发调试
- 串口日志默认 关闭（
g_enable_uart_log = 0），开启可能影响 BLE 连接稳定性 - 诊断信息（RSSI、断连原因等）可通过网页读取，无需串口
常见问题 FAQ
Q：配对后按键没反应？
A：确认系统蓝牙显示已连接；检查当前是媒体还是鼠标模式；媒体模式下确认当前 Profile 有配置（Profile 1~4 出厂为空）。
Q：鼠标模式光标不动？
A：可能未校准——看是否红灯慢闪；打开网页点击「重新校准」并静止 2 秒。须 已连接 且处于鼠标模式 IMU 才会工作。
Q：光标漂移怎么办？
A：增大「死区」、开启「倾斜补偿」、重新校准；确保校准后不要立刻移动设备。
Q：网页连不上设备？
A：检查浏览器是否支持 Web Bluetooth；须 HTTPS 或 localhost；Windows 需开启蓝牙权限；尝试关闭其他占用 BLE 的页面。
Q：换电脑后连不上？
A：BLE 设备通常只能记住有限配对数。新电脑配对前，可在旧设备上 OK+DOWN 清配对，或 OK+UP+RIGHT 恢复出厂。
Q：Profile 切换没反应？
A：OK 长按只切换到 已配置 的 Profile；若仅 Profile 0 有内容则不会变化。可通过网页先配置 Profile 1 或手动「设为活跃」。
Q：如何配置 PPT 翻页？
A：新建 Profile，将 LEFT 短按设为 ←、RIGHT 短按设为 →，OK 短按设为 F5 等；参考 BLE_PROTOCOL.md 第 13 节宏示例。
Q：能否同时连网页和当键鼠用？
A：可以。网页连接占用配置 GATT 通道，HID 键鼠走标准 HID 服务，两者可并存（同一 BLE 连接）。
许可证
本项目基于 WCH 官方 BLE 示例开发，部分文件遵循 Apache-2.0 许可证（见源文件头注释）。
评论区