ESP32-S3 USB HID 鼠标固件

这是一个精简版 ESP32-S3 USB HID 鼠标项目。电脑端通过 ESP32-S3 Native USB 识别为 USB HID 鼠标，另一侧通过 USB-UART 串口发送控制命令。

上位机相关说明：

• https://www.52pojie.cn/forum.php?mod=viewthread&tid=2052369

硬件说明

推荐双 Type-C 结构：

• Type-C A：连接 ESP32-S3 Native USB，作为 USB HID 鼠标接入电脑。
• Type-C B：连接 USB-UART 芯片，用于发送 UART 控制命令。

ESP32-S3 只有一个 Native USB OTG 外设，不能在固件里虚拟出两个独立的原生 USB Device。第二个 Type-C 需要接 USB-UART 芯片，例如 CH343、CP2102、CH340、FT232，或者开发板自带的 USB-UART 电路。

ESP32-S3 Native USB 引脚固定为：

• USB D- / DN：GPIO19
• USB D+ / DP：GPIO20

如果其他 ESP32-S3 硬件标注为 USB DN2 = GPIO19、USB DP2 = GPIO20，就对应本固件使用的 Native USB。TinyUSB 不需要额外配置 USB DP/DN 引脚。

UART 控制口

默认控制口配置：

• UART：UART0
• 波特率：256000
• 行结尾：\n
• 命令前缀：@HID
• 协议版本：hid-v4

命令示例

@HID STATUS
@HID STATUS2
@HID MOVE 10 -5
@HID MOVE2 200 -80 40 5
@HID CLICK LEFT
@HID CLICK RIGHT
@HID CLICK MIDDLE
@HID DOWN LEFT
@HID UP
@HID KEY A
@HID COMBO CTRL ALT DELETE
@HID TEXT hello
@HID RELEASE_ALL
@HID DRAG 8 0
@HID DRAG2 200 0 50 5
@HID SCROLL 1
@HID RELEASE

路径移动命令：

@HID PATH 1 4 5 MOVE
@HID PATHD 1 0 4 20 0 20 0 -10 5 -10 5
@HID PATHRUN 1
@HID PATHCLEAR

返回示例

@ACK STATUS protocol=hid-v4 ready=1 mounted=1 active=1 installed=1
@ACK STATUS2 protocol=hid-v4 ready=1 mounted=1 active=1 installed=1 left_down=0 key_down=0 caps="mouse,path,keyboard,ascii_text,combo,release_all" stage="minimal" last_error="" last_reset=""
@ACK MOVE
@ERR HID_NOT_READY USB HID is not mounted
@ERR BAD_ARG MOVE needs dx dy

协议说明

• @ACK 表示 HID 命令已经执行成功，不只是入队成功。
• MOVE / DRAG 单次移动会限制在 -20..20，方便平滑控制。
• MOVE2 / DRAG2 格式为 dx dy steps interval_ms，总位移限制为 -4096..4096，步数限制为 1..240，间隔限制为 2..50 ms。
• PATH 用于准备路径缓存，格式为 @HID PATH <id> <count> <interval_ms> <MOVE|DRAG>。
• PATHD 每行最多写入 8 个 dx dy 点，总路径最多 1024 点，每个点限制为 -127..127。
• PATHRUN <id> 执行缓存路径，执行成功后返回 @ACK PATHRUN。
• SCROLL 滚轮值限制为 -10..10。
• 按键长按超过 5 秒会自动释放，避免鼠标按钮一直保持按下。

项目范围

本项目只包含 USB HID 鼠标和 UART 控制功能