CH376做USB HID主机：操作鼠标键盘的完整实践

简介面向嵌入式开发者与单片机爱好者的CH376鼠标键盘操作资源包围绕CH376芯片的USB HID通信展开解决如何用C语言实现键盘按键模拟、鼠标移动与点击等实际控制需求。压缩包共22个文件大小约115KB主要包含C源码、H头文件、OBJ目标文件及Keil的UV2工程配置另附编译生成的HEX固件与LST列表文件便于直接阅读代码、修改项目或烧录到开发板验证效果。资源中可看到CH376初始化、键盘扫描码发送、鼠标位移指令等典型函数示例并涉及命令集调用、等待就绪和基本错误处理流程帮助理解USB设备控制的核心机制。文件结构清晰紧凑配套Keil工程和HEX固件便于对比源码与编译结果适合具备基础C语言和单片机知识的学习者根据注释和示例代码深入实践可延伸用于自制USB键鼠适配器、自动化测试工具或嵌入式交互项目。目前已有497人学习下载是熟悉CH376操作HID设备的实用参考资料。1. CH376 操作鼠标键盘一块 USB Host 芯片做 HID 主机比想象中省事也更讲究时序很多人第一次听到 CH376 是用来读 U 盘实际上把它拿来操作鼠标键盘才是这个芯片最耐玩的使用方式。你不必在单片机里堆 USB 协议栈CH376 已经把物理层、事务层吃掉一大半你要做的是学会用 SPI 或者并口和它对话。但这块芯片不是插上就能出数据命令时序、枚举顺序、HID 描述符解析、端点轮询每一步都藏着能让数据变成 0xFF 或 0x00 的坑。这份资源做的就是把这套流程从零到能用串通起来适合正在做键盘鼠标转发、远程控制硬件、USB 设备测试工具的从业者。2. 硬件接线与 SPI 初始化三根信号线加一个中断脚命令时序先理顺2.1 管脚分配与电平匹配3.3V 还是 5V决定要不要加转换器CH376 的供电范围横跨 3.3V 和 5V但这不意味着你可以随便接。芯片的 SPI 接口电平跟着 VCC 走如果 MCU 是 3.3V 而 CH376 直接吃了 5V那 MOSI、SCK、CS 这几个输出脚就可能把 CH376 的输入脚打出过压长期工作容易出偶发错误。在实际项目里我一般把 CH376 拉在 3.3VMCU 也统一 3.3V这是最省事也最稳的接法。信号CH376 管脚方向说明SCKSCKMCU→CH376SPI 时钟默认空闲低电平MOSIDIMCU→CH376命令和数据输入MISODOCH376→MCU数据输出CSCS#MCU→CH376片选低电平有效INTINT#CH376→MCU中断请求低电平有效RSTRST#MCU→CH376复位低电平有效如果你的板子只有 5V 电源也别顺手把 CH376 插在 5V 上加一个低压差稳压器降到 3.3V 更划算。RST 脚建议由 MCU 的 GPIO 控制不要直接搭一个 RC 复位电路完事因为后面调试时你会频繁需要软复位 CH376用代码拉一下 RST 再拉高比断电重来快得多。初始化 GPIO 的代码长这样// CH376 管脚配置以某国产 MCU 为例 void CH376_GPIO_Init(void) { // CS、SCK、MOSI、RST 设为推挽输出初始状态拉高 gpio_set_mode(CS_PORT, CS_PIN, GPIO_MODE_OUTPUT_PP); gpio_set_mode(SCK_PORT, SCK_PIN, GPIO_MODE_OUTPUT_PP); gpio_set_mode(MOSI_PORT, MOSI_PIN, GPIO_MODE_OUTPUT_PP); gpio_set_mode(RST_PORT, RST_PIN, GPIO_MODE_OUTPUT_PP); gpio_write(CS_PORT, CS_PIN, 1); // 片选默认拉高避免误触发 gpio_write(SCK_PORT, SCK_PIN, 0); // 时钟空闲为低 gpio_write(RST_PORT, RST_PIN, 1); // 复位脚先释放 // MISO 设为浮空输入或上拉输入具体看 MCU 内部上拉能力 gpio_set_mode(MISO_PORT, MISO_PIN, GPIO_MODE_INPUT_PULLUP); // INT 设为下降沿输入中断或直接轮询读取 gpio_set_mode(INT_PORT, INT_PIN, GPIO_MODE_INPUT_PULLUP); gpio_enable_irq(INT_PORT, INT_PIN, GPIO_IRQ_TRIGGER_FALLING); }这段代码有一件事很多人第一次会忽略片选默认必须拉高。CH376 只要 CS 一拉低就会认为你要开始发命令如果上电瞬间 CS 悬空或者被干扰拉低芯片会收到一堆垃圾字节后续状态全乱。INT 用下降沿中断是最常见的做法但也有项目图省事直接轮询只要轮询周期不超过命令超时时间也能跑。2.2 SPI 模式与速率SCK 空闲电平、采样沿和位序是三个隐藏坑CH376 的 SPI 接口不是所有 MCU 都能直接拿来就用它对时序的要求和普通 SPI Flash 不一样。第一次调通之前不要急着把速率拉到 8MHz、16MHz先用 1MHz 以下跑通整个命令流程再逐步往上加。常见配置是 SPI Mode 0也就是 CPOL0、CPHA0SCK 空闲为低、上升沿采样。位序方面要注意CH376 收发数据是低位在前也就是 LSB first。而不少 MCU 的 SPI 外设默认是 MSB first不做处理的话你发出去的 0x15 到芯片那里就变成了 0xA8芯片会直接忽略这个“不存在的命令”。// 初始化 CH376 使用的 SPI 外设 void CH376_SPI_Init(void) { spi_handle_t hspi; hspi.mode SPI_MODE_0; // CPOL0, CPHA0 hspi.speed_hz 1000000; // 先跑 1MHz稳定后再提速率 hspi.bit_order SPI_ORDER_LSB_FIRST; // CH376 要求低位在前 spi_init(SPI1, hspi); spi_set_active(SPI1, true); }为什么推荐 1MHzCH376 的命令交互频率并不高每次枚举、每次读键盘数据也就几十个字节1MHz 下整个交互也就几百微秒对鼠标键盘这种低频 HID 设备完全够用。真正限制速率的不是芯片能力而是你的 PCB 走线和跳线质量。飞线连接时SCK 边沿会振铃采样沿稍微偏移一点点就会出现偶发错误而且这种错误极难复现。速率参数要改也很简单把speed_hz提到 4000000然后反复插拔设备跑压力测试。如果你发现 10 次里有 1 次命令超时就降回 1MHz不用犹豫。2.3 一次握手的最小闭环发命令、等中断、读状态CH376 和 MCU 的交互不是“发一个字节收一个字节”那种透明通道而是命令-中断-状态三段式。每次你发一条命令芯片处理完后会拉低 INT 脚MCU 再发 CMD_GET_STATUS 读回处理结果根据状态值决定下一步走哪个分支。// 向 CH376 发送命令并等待处理完成带超时保护 uint8_t CH376_Send_Cmd(uint8_t cmd, uint8_t *ret_status, uint32_t timeout_ms) { uint32_t tick get_tick(); gpio_write(CS_PORT, CS_PIN, 0); spi_transfer_byte(SPI1, cmd); gpio_write(CS_PORT, CS_PIN, 1); // 等待 INT 拉低表示芯片已处理完命令 while (gpio_read(INT_PORT, INT_PIN) ! 0) { if (get_tick() - tick timeout_ms) { *ret_status 0x00; return ERR_TIMEOUT; } } // 读取状态先发 CMD_GET_STATUS再读一个字节 gpio_write(CS_PORT, CS_PIN, 0); spi_transfer_byte(SPI1, CMD_GET_STATUS); *ret_status spi_transfer_byte(SPI1, 0xFF); gpio_write(CS_PORT, CS_PIN, 1); return ERR_OK; }注意看这段代码里的三处细节。第一CS 在命令阶段和处理阶段都是拉低的但中途不能有别的 SPI 操作否则芯片会认为你在发新命令。第二INT 是边沿触发还是电平触发不重要重要的是读状态之前一定要先等 INT 有效跳过等待直接读状态拿到的往往还是上一次的结果。第三CMD_GET_STATUS 这个命令发完后不需要再等待中断状态值就在紧接着的那个字节里。我习惯把超时设成 100ms。CH376 处理一条命令理论上只要几十微秒但你在等设备连接、等设备响应控制传输时耗时会远高于这个值。超时太长会让系统卡顿太短又会在设备枚举慢时误判失败100ms 是个比较平衡的经验值。3. USB 主机与 HID 枚举从复位总线到 Set_Configuration八个步骤不能乱3.1 外置固件主机模式下的枚举步骤为什么 HID 不能靠内置固件模式CH376 有两种 USB 主机固件模式这是很多第一次用它的人会搞混的地方。内置固件模式是芯片自己完成 U 盘枚举、文件系统挂载这些事MCU 只要发“挂载”命令就能读文件但这种模式只支持固定类型的设备鼠标键盘不在它支持的范围内。操作 HID 设备必须把 CH376 设成外置固件主机模式也就是让 MCU 来主导枚举过程。// 设置 CH376 进入外置固件主机模式 #define CMD_SET_USB_MODE 0x15 #define USB_MODE_HOST_EXTERN 0x06 uint8_t status 0; CH376_Send_Cmd(CMD_SET_USB_MODE, NULL, 100); gpio_write(CS_PORT, CS_PIN, 0); spi_transfer_byte(SPI1, USB_MODE_HOST_EXTERN); // 写模式参数 gpio_write(CS_PORT, CS_PIN, 1); // 等待设备连接中断再开始枚举这个模式切换是枚举流程的起点。设为 0x06 之后CH376 会开始检测 USB 总线上的设备连接一旦检测到设备插入INT 会触发一次连接中断。这个时候再去读设备描述符才有意义。需要说明的是CH376 是 USB 全速主机也就是它自己工作在 12Mbps 全速模式。市面上的有线键盘鼠标绝大多数是全速设备没问题但如果你插了一个 USB 3.0 的高速 HUB 再挂设备HUB 与 CH376 之间会协商成全速能识别但稳定性看运气。这不是芯片坏是 USB 规范里高速设备向下兼容全速时的固有开销。3.2 从配置描述符里找键盘和鼠标接口类、子类、协议号怎么用枚举的完整流程顺序比较固定总线复位、设置地址、读设备描述符、读配置描述符、设置配置。CH376 的固件层把总线复位做了大半MCU 要管的是拿到描述符之后怎么解析。配置描述符是一个 TLV 结构你得顺着它把 配置描述符 → 接口描述符 → 端点描述符 → HID 描述符 逐层读出来。判断一个接口是键盘还是鼠标看三个字段字段键盘鼠标bInterfaceClass0x03 (HID)0x03 (HID)bInterfaceSubClass0x01 (Boot)0x01 (Boot)bInterfaceProtocol0x01 (Keyboard)0x02 (Mouse)我用一段代码把“找键盘”的逻辑写出来。它做的是很直白的事情从配置描述符缓冲区里先跳到接口描述符再判断三个关键字节。// 从配置描述符数据中查找键盘接口 // 返回值键盘接口所在偏移-1 表示未找到 int HID_Find_Keyboard_Interface(uint8_t *cfg_desc, uint16_t total_len) { uint16_t offset 0; while (offset total_len) { uint8_t desc_len cfg_desc[offset]; uint8_t desc_type cfg_desc[offset 1]; if (desc_type 0x04) { // 0x04 表示接口描述符 if (cfg_desc[offset 5] 0x03 // bInterfaceClassHID cfg_desc[offset 7] 0x01) { // bInterfaceProtocolKeyboard return offset; } } offset desc_len; // 跳到下一个描述符 } return -1; }offset 5是 bInterfaceClass 的位置offset 7是 bInterfaceProtocol 的位置。实际描述符里中间还有 bInterfaceSubClass正好对应offset 6。如果你要同时支持鼠标就多判断一个cfg_desc[offset 7] 0x02然后保存不同的接口类型。这个阶段最大的迷惑点在于配置描述符不一定只有 9 字节它后面跟着一串接口描述符、端点描述符甚至还有 HID 描述符。不能粗暴地认为偏移 0 就是配置描述符、偏移 9 就是接口描述符一定要用desc_len做跳转否则遇到带多个接口的复合设备就会解析错位。3.3 枚举后的端点准备Set_Idle 与中断 IN 端点的轮询参数找到键盘接口之后枚举还差最后一步配置设备然后找到它的中断 IN 端点。HID 键盘鼠标都是中断传输数据从设备往主机走这个端点方向是 IN也就是设备到主机。端点描述符里bEndpointAddress的高位如果为 1就表示 IN 端点。// 找到接口描述符后查找中断 IN 端点 int HID_Find_InterruptIn_Endpoint(uint8_t *cfg_desc, int iface_offset) { int offset iface_offset cfg_desc[iface_offset]; // 跳到第一个端点描述符 for (int i 0; i 4; i) { uint8_t desc_type cfg_desc[offset 1]; if (desc_type ! 0x05) break; // 0x05 是端点描述符 if ((cfg_desc[offset 2] 0x80) // bEndpointAddress 的 IN 位 (cfg_desc[offset 3] 0x03) 0x03) { // bmAttributes Interrupt return cfg_desc[offset 2] 0x0F; // 返回端点号 } offset cfg_desc[offset]; } return -1; }找到端点号之后先别急着进轮询循环。很多人漏掉了一个控制传输Set_Idle。HID 规范要求主机通过 Set_Idle 控制请求设置设备在总线上无数据时的空闲重试周期如果不对设备发这个请求部分键盘鼠标会在枚举完成后不触发中断 IN数据就一直不来。Set_Idle 的请求结构是 bmRequestType0x21bRequest0x0AwValue 低字节写 0wIndex 写接口编号。我一般直接把 wValue 设成 0表示设备进入无限期空闲重试这样设备即使没按键也会以每 10ms 一次的节奏回报空数据方便你区分“设备在线但没按键”和“设备断开了”。4. HID 数据解析把 8 字节键盘报文和 4 字节鼠标报文变成实际键值4.1 键盘报文 8 字节modifier、保留字节与六个按键的查表转码标准 USB 键盘的输入报告固定 8 字节。第 0 字节是 modifier 修饰键第 1 字节是保留字节第 2 到 7 字节是六个按键的 Usage ID表示当前按下的普通键。注意是普通键修饰键的状态已经放在第 0 字节里不会出现在这六个字节中。// 键盘报告结构体 typedef struct { uint8_t modifier; // 第 0 字节Ctrl/Shift/Alt 等组合键 uint8_t reserved; // 第 1 字节厂商自定义忽略 uint8_t keys[6]; // 第 2~7 字节按键 Usage ID } USB_Keyboard_Report;解析逻辑说穿了就是把 Usage ID 映射成你需要的字符或者功能码。USB HID 的 Usage ID 不是 ASCII0x04 对应键盘上的 A0x05 对应 B0x28 是 Enter。如果你直接把收上来的字节往串口打印 ASCII拿到的就是乱码。Usage ID按键Usage ID按键0x04A0x28Enter0x05B0x29Esc0x1E10x2ABackspace0x1F20x2BTab0x28Enter0x2CSpace组合键的判断不依赖按键列表直接读 modifier 的位掩码。bit0 对应左 Ctrlbit1 对应左 Shiftbit2 对应左 Altbit3 对应左 GUI。右手的对应关系在 bit4 到 bit7顺序相同。我在实际代码里会做一个掩码预判优先处理 CtrlAlt 这类组合键因为热键类场景最关心的是这种状态。4.2 鼠标报文 4 字节相对位移、滚轮与五键注意有符号数标准鼠标的输入报告通常 4 到 5 字节。最简形式是 3 字节第 0 字节是按键状态第 1 字节是 X 轴相对位移第 2 字节是 Y 轴相对位移。带滚轮的鼠标会把报告扩成 4 字节第 3 字节是滚轮数据。五键鼠标则会在第 0 字节的 bit0 到 bit4 上扩展出左键、右键、中键、侧键上、侧键下。// 标准四字节鼠标报告 typedef struct { uint8_t buttons; // bit0左键, bit1右键, bit2中键, bit3侧键1, bit4侧键2 int8_t x; // X 方向相对位移向左为负 int8_t y; // Y 方向相对位移向下为负 int8_t wheel; // 滚轮向上为正一格等于 1 } USB_Mouse_Report;解析鼠标数据最容易被坑的地方是把 X、Y、滚轮当成无符号数读。鼠标位移是带符号的往左移动时 X 是负值加大分辨率或者快速甩鼠标时位移量甚至会超过 127 的 int8_t 范围。稳妥的做法是读完原始字节后按 int16_t 扩展或者直接按 int8_t 读在应用层做夹紧。// 鼠标数据处理按有符号数解析并做边界保护 void Mouse_Process(uint8_t *raw) { USB_Mouse_Report report; report.buttons raw[0]; report.x (int8_t)raw[1]; // 强制转有符号负位移才有意义 report.y (int8_t)raw[2]; report.wheel (int8_t)raw[3]; // 位移过大时夹紧防止异常数据导致光标乱跳 if (report.x 100) report.x 100; if (report.x -100) report.x -100; if (report.y 100) report.y 100; if (report.y -100) report.y -100; }int8_t强转是关键。如果你读到的原始字节是 0xFE按uint8_t看是 254按位移看其实是 -2。鼠标往左轻轻动一格位移值通常是 -1 或 -2丢了这个符号位光标就会变成只往右和往下跑的残废状态。这个问题在初学者提交的代码里出现频率极高几乎每次都能在论坛里刷到。4.3 组合键与多按键的状态机报关键字的边沿检测键盘的六个按键槽是“无冲”设计可以同时容纳六个普通键但这不代表应用层可以无脑把六个键都拿去当按键事件。同一个键按下、按住、释放会产生三组不同的报告按下时按键出现在列表中按住时列表保持不变释放后按键从列表消失。你要做的是边沿检测不是电平检测。// 按键状态机检测某个键是否刚被按下 #define KEY_STATE_IDLE 0 #define KEY_STATE_PRESSED 1 uint8_t Key_State KEY_STATE_IDLE; uint8_t last_keys[6] {0}; int Key_Detect_Press(uint8_t *current_keys) { int press_count 0; for (int i 0; i 6; i) { int is_present 0; for (int j 0; j 6; j) { if (current_keys[j] last_keys[i]) { is_present 1; break; } } if (last_keys[i] ! 0 !is_present) { press_count; } } memcpy(last_keys, current_keys, 6); return press_count; }这段代码做的事情是拿上一次的按键列表和当前列表做差集把“从列表里消失”的键当成一次完整按键事件。为什么这么处理因为一个键的按下和释放恰好对应一次从无到有再到无的过程如果你在“从无到有”就触发事件很多应用里会因为按键抖动导致重复触发。我一般会加上一个 20ms 的去抖窗口也就是同一键两次按下事件之间至少间隔 20ms低于这个间隔的短触发直接丢弃。5. 避坑CH376 在鼠标键盘场景下的常见问题与排查手法5.1 读回数据全是 0xFF 或 0x00先怀疑 SPI 模式再怀疑位序现象枚举过程好像正常但读回来的数据要么全部是 0xFF要么全是 0x00命令状态返回值也对不上。原因SPI 的 CPOL/CPHA 配置和 CH376 的要求不匹配或者位序反了。CH376 要求 LSB first但很多 ARM 内核 MCU 的 SPI 外设默认是 MSB first。如果模式反了命令字节本身就读不对后续所有状态都无从谈起。解决先把 SPI 速率降到 1MHz用CMD_GET_IC_VER读芯片版本号能读回正确值说明 SPI 通路没问题再往下走。如果版本号也读不出来就用逻辑分析仪挂在 SCK 和 MOSI 上看首字节的 bit0 到底是先出还是后出一帧波形就能判断位序问题。5.2 枚举正常但中断 IN 一直不触发Idle 没配好或端点找错现象设备描述符读到了配置也设置成功了但轮询循环里永远等不到中断 IN 触发设备像睡着了一样。原因最常见的是漏发 Set_Idle。另一部分情况是设备有多个接口比如带数码管的键盘代码只找了第一个接口而中断 IN 端点挂在第二个接口上数据当然不会从第一个接口冒出来。解决枚举完成后先发一次 Set_Idle 控制请求wValue 设 0然后再进轮询。如果仍不触发把配置描述符完整打印出来确认你要找的接口号和端点号跟实际设备一致。遇到复合设备按接口数量做循环搜索不要默认键盘一定在接口 0。5.3 无线键鼠能枚举但收不到数据轮询节奏和设备功耗策略冲突现象同一套代码插有线键盘一切正常换无线鼠标后能枚举成功但数据就是不来或者要等好几秒才来一条。原因无线键鼠的接收器为了省电在主机长时间不发唤醒请求时会进入低功耗状态CH376 的中断 IN 轮询如果间隔太长设备认为总线空闲就睡了。解决把轮询周期压短到 10ms 以内。CH376 每条中断 IN 传输的开销在几十微秒级别10ms 轮询完全不吃 CPU。另外如果无线接收器自带 HUB 结构枚举时要注意它内部还有一层设备需要先复位一次 HUB 再枚举下游设备这一步没做就会卡在“能枚举但没数据”。5.4 键盘部分按键无反应Usage ID 直接当 ASCII 用现象字母键和数字键能出来回车、空格、Backspace 出不来或者按 ShiftA 出来的是两个字符而不是大写 A。原因键盘报告里传的是 Usage ID不是 ASCII。0x28 在 ASCII 里是左括号在 HID Usage Table 里是 Enter。把 Usage ID 直接塞进字符串处理逻辑等于对表表错。解决先建一张 Usage ID 到字符的映射表再从表里查出字符最后根据 modifier 的 Shift 位决定是否要切换大小写或符号层。我在实际代码里会为普通层、Shift 层、Alt 层各建一张表查表时先看 modifier 属于哪个层再查对应表。5.5 偶发命令失败且很难复现SPI 频率和退避节奏的问题现象长时间运行后偶尔出现一次命令超时重新初始化又好了频率不高但没法接受。原因SPI 速率过高时飞线或插座接触导致的边沿振铃会偶尔破坏数据。另一个隐藏原因是你在上一次命令还没处理完时发了下一条命令CH376 内部状态机被冲掉了。解决SPI 速率固定降到 1MHz同时给每次命令之间加 1ms 左右的操作间隙。发命令前先读一次 INT 状态确认芯片空闲再操作。如果还偶发失败就把命令交互做成带重试的封装函数连续失败 3 次才复位 CH376这比一次失败就全盘重来稳健得多。6. 把 HID 报文接到 RTOS 消息队列一个低成本事件分发方案6.1 用消息队列把 HID 数据和业务解耦当你的项目开始跑 RTOS 之后第一件要习惯的事就是不要再在中断里处理业务逻辑。CH376 的中断只是告诉你“有数据了”真正读数据和解析 HID 报文的动作应该放到一个独立任务里。我这里给出一个直接把 HID 数据送进消息队列的写法你可以根据自己的 RTOS 接口微调。// HID 读取任务轮询 CH376 端点数据进队列后通知业务任务 void HID_Read_Task(void *param) { USB_MSG msg; uint8_t raw_buf[8]; while (1) { if (CH376_Wait_Interrupt(10) ERR_OK) { uint8_t len CH376_Read_Data(raw_buf, sizeof(raw_buf)); if (len 0) { msg.type current_hid_type; // 1键盘, 2鼠标 msg.len len; memcpy(msg.data, raw_buf, len); os_message_queue_send(hid_queue, msg, 0); } } os_task_delay(2); // 2ms 轮询周期既有响应速度又不吃 CPU } }这段代码里比较重要的是os_task_delay(2)。2ms 意味着轮询频率 500Hz鼠标的刷新率一般 125Hz 到 1000Hz键盘更慢所以这个节奏不会丢数据又给其他任务留足了 CPU。消息队列做了解耦之后业务任务拿到报文只需要解析不再关心数据是从 CH376 来的还是从模拟器来的这给后续做自动测试、脚本注入留了很大余地。验证这套链路是否通我习惯在业务任务里放一个计数器和灰度日志每收到一条键盘报告计数器加一但只在报告内容变化时才打印。这样既能确认消息队列没有积压又能确认解析逻辑没有把持续按住的键重复上报。跑一段时间后看计数和实际按键次数是否一致如果差太多基本都是去抖参数问题。从那以后我每次初始化 CH376 都强制走一遍固定检查顺序先读版本号确认 SPI再跑一次 Set_Idle 握手最后开轮询。这套习惯救过我至少三次莫名其妙的“昨天还好好的今天不行”的现场问题。希望帮到你。本文还有配套的精品资源点击获取