ESP32 USB HID鼠标位移溢出问题解决方案

1. 项目背景与问题剖析

在ESP32物联网设备开发中，我们经常需要实现USB HID设备功能，特别是鼠标控制场景。最近在基于esp-iot-solution开发USB HID鼠标设备时，遇到了一个看似简单却影响用户体验的关键问题——鼠标位移值溢出。这个问题会导致鼠标指针突然"跳变"或"卡在屏幕边缘"，严重影响操作流畅性。

鼠标位移溢出实际上分为两个层面：

协议层溢出：TinyUSB库的HID鼠标上报接口tinyusb_hid_mouse_move_report使用int8_t类型（-127~127）传递位移值。当我们需要上报大位移（比如快速移动鼠标）时，直接传入大数值会导致数据截断。例如，传入300会被截断为44（300-256），鼠标指针会朝完全错误的方向移动。

逻辑层溢出：即使协议层正确处理了位移值，如果不对鼠标的累计坐标进行边界检查，鼠标指针可能会"移出屏幕"或在屏幕边缘产生异常跳动。这个问题在触摸屏转USB鼠标等应用中尤为明显。

2. 协议层溢出解决方案

2.1 位移拆分算法设计

针对协议层的int8_t限制，我们设计了位移拆分算法。核心思想是将大位移分解为多个不超过±127的小位移，通过多次上报实现大距离移动。算法需要考虑：

1. 正负方向处理
2. 剩余位移计算
3. 上报间隔控制

以下是优化后的实现代码：

c复制void safe_hid_mouse_move(int32_t total_delta_x, int32_t total_delta_y, 
                        int8_t vertical, int8_t horizontal)
{
    // 先处理滚轮，只在上报第一次位移时携带滚轮数据
    bool first_report = true;
    
    // 使用do-while确保至少上报一次（即使位移为0）
    do {
        int8_t step_x = 0;
        if (total_delta_x > 0) {
            step_x = (total_delta_x > 127) ? 127 : (int8_t)total_delta_x;
            total_delta_x -= step_x;
        } else if (total_delta_x < 0) {
            step_x = (total_delta_x < -127) ? -127 : (int8_t)total_delta_x;
            total_delta_x -= step_x;
        }

        int8_t step_y = 0;
        if (total_delta_y > 0) {
            step_y = (total_delta_y > 127) ? 127 : (int8_t)total_delta_y;
            total_delta_y -= step_y;
        } else if (total_delta_y < 0) {
            step_y = (total_delta_y < -127) ? -127 :