开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：Korvo S3 · 工程
02.beginner.usb_hid_mouse· targetesp32s3
前置：USB HID 键盘
学习时长：约 20 分钟 · 难度：★★☆☆☆
学习目标
完成本节后，你将能够：
- 理解 HID 鼠标报告描述符与键盘描述符的区别
- 掌握鼠标报告格式（按键 + 相对位移 + 滚轮）
- 了解 CherryUSB/TinyUSB 发送 HID 报告的方法
- 为 USB 复合设备（键盘 + 鼠标）打基础
1. 这个例子在干嘛
把 Korvo 变成一个 USB 鼠标，USB 口连接电脑后被识别为标准鼠标设备。可以用代码控制鼠标移动方向、速度和按键点击。
生活类比：给电脑接了一个"程序员控制的鼠标"——你写什么代码，鼠标就怎么动。
┌──────────┐ USB ┌──────────┐ HID 报告 ┌──────────┐
│ ESP32-S3 │───────────→│ 电脑 │───────────→│ 鼠标光标 │
│ HID 设备 │ D+/D- │ USB 主机 │ 按键+位移 │ 移动/点击│
└──────────┘ └──────────┘ └──────────┘
2. HID 鼠标报告格式
每次发送 3~4 字节的报告：
字节 0: 按键状态
├── bit 0 = 左键（1=按下, 0=松开）
├── bit 1 = 右键
└── bit 2 = 中键
字节 1: X 轴相对位移（-127 ~ +127）
├── 正值 → 光标右移
└── 负值 → 光标左移
字节 2: Y 轴相对位移（-127 ~ +127）
├── 正值 → 光标下移
└── 负值 → 光标上移
字节 3: 滚轮（可选，-127 ~ +127）
├── 正值 → 向上滚动
└── 负值 → 向下滚动
与键盘报告的对比
| 对比 | HID 键盘 | HID 鼠标 |
|---|---|---|
| 报告大小 | 8 字节 | 3~4 字节 |
| 位移类型 | — | 相对位移（增量） |
| 按键表示 | Key Code 数组 | 位掩码 |
| 使用场景 | 打字/快捷键 | 移动/点击 |
3. 编译烧录
cd Korvo_Firmware\02.beginner.usb_hid_mouse
idf.py set-target esp32s3
idf.py build flash monitor
重要：用 USB 口（非 UART 口）连接电脑。
4. 运行效果
烧录后电脑应识别出新鼠标设备。默认可能不会自动移动——需要在代码中调用 hid_mouse_test() 或启用定时发送报告才能看到光标移动。
5. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 电脑无反应 | 连错口 | 确认用 USB 口（非 UART） |
| 识别但不动 | 代码未发送报告 | 确认 hid_mouse_test() 被调用 |
| 光标抖动 | X/Y 偏移值过大 | 减小数值（如 ±5） |
| 光标飞走 | 报告发送太快 | 加延时（10~50ms） |
| Windows 提示驱动 | 描述符错误 | 检查 Report Descriptor |
6. 动手改造建议
- ADC 按键控制：用 Korvo 的 ADC 按键控制鼠标上下左右
- 触摸板模式：触摸屏坐标差值映射为鼠标相对位移
- 自动画圆：用三角函数生成圆形轨迹的 X/Y 偏移
- 复合设备：同一个 USB 设备同时报告键盘 + 鼠标（需合并描述符）
- 体感鼠标：接 IMU 传感器，倾斜角度控制鼠标移动
7. 知识延伸
- 相对 vs 绝对位移：鼠标用相对位移（每次偏移多少），绘图板用绝对位移（当前位置坐标）
- HID 报告速率：USB Low Speed（1.5Mbps）最快 10ms/报告，Full Speed（12Mbps）最快 1ms
- 报告描述符：告诉主机"我的报告长什么样、每个字节代表什么"——这段二进制数据决定了设备类型
- 游戏鼠标 vs 普通鼠标：游戏鼠标可达 1000Hz 报告率（1ms），本例通常 10ms
8. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| USB 键盘 | USB HID Keyboard | 键盘设备 |
| USB 串口 | USB CDC | 虚拟串口 |
| P4C5 对比 | P4C5 USB 鼠标 | CherryUSB 版 |
酷世DIY · Kevincoooool