BLE HID库：嵌入式设备实现HID-over-GATT的轻量级方案

1. BLE_HID 库概述面向嵌入式设备的 HID-over-GATT 实现BLE_HID 是一个专为资源受限嵌入式平台设计的轻量级开源库其核心目标是将传统 USB HIDHuman Interface Device协议栈无缝迁移至 Bluetooth Low EnergyBLE物理层通过 GATTGeneric Attribute Profile协议实现键盘、鼠标、游戏手柄等输入设备的无线化。该库不依赖特定芯片厂商的 BLE 协议栈而是以标准 BLE API 为抽象接口向上提供符合 HID 规范的语义化 API向下可对接 Nordic nRF52/nRF53 系列、ST BlueNRG、ESP32-BLE、Dialog DA1458x 等主流 BLE SoC 的底层驱动。与通用 BLE 外设库不同BLE_HID 的工程价值在于其协议栈分层解耦设计它不实现 Link Layer 或 Host Controller InterfaceHCI而是假设上层已具备完整的 BLE Host 功能如通过 SoftDevice、NimBLE、Zephyr BLE Host 或 ESP-IDF BLE Stack 提供仅聚焦于 HID Profile 的 GATT 层建模与 HID Report Descriptor 的运行时解析/生成。这种设计使开发者无需深入 BLE 协议细节即可在数小时内完成一个符合蓝牙 SIG 认证要求的 HID 设备原型。从硬件工程师视角看BLE_HID 的本质是一个“GATT 服务编排器”与“HID 报文序列化引擎”的组合体。它将 HID 设备的逻辑功能如按键扫描、坐标上报、LED 状态同步映射为标准化的 GATT 特征值Characteristic并通过预定义的 UUID 和属性权限确保与主机端Windows/macOS/iOS/Android的即插即用兼容性。其最小内存占用可控制在 RAM 2KB、Flash 8KB 范围内适用于 Cortex-M0/M3/M4 内核的 MCU。1.1 核心设计哲学协议合规性优先于功能堆砌BLE_HID 的代码结构严格遵循蓝牙 SIG 发布的《HID over GATT Specification v1.0》及《HID Usage Tables v1.22》。这意味着所有 GATT Service、Characteristic、Descriptor 的 UUID 均采用标准 16-bit 蓝牙基 UUID0000xxxx-0000-1000-8000-00805F9B34FB而非厂商自定义 UUIDReport Map 特征值0x2A4B强制要求以完整 HID Report Descriptor 二进制流形式提供且必须通过HID_Usage_Page、HID_Usage、HID_Logical_Min/Max等条目精确描述数据格式Boot Protocol 模式Boot Keyboard/Boot Mouse被显式支持确保在 BIOS/UEFI 环境下仍可被识别Security Manager ProtocolSMP配对流程由底层 BLE Host 自动处理BLE_HID 仅需声明Authentication Required属性位。这种“向标准低头”的设计看似限制了灵活性实则大幅降低了认证失败风险。在实际项目中我们曾观察到某款基于自定义 UUID 的 BLE 键盘在 macOS Monterey 上无法触发 Caps Lock LED 同步根源正是其 Report Map 中遗漏了HID_Report_ID字段——而 BLE_HID 的 Report Descriptor 生成器内置了该字段的自动注入逻辑。1.2 典型应用场景与硬件约束BLE_HID 的典型部署场景包括场景硬件约束关键配置项超低功耗无线键盘CR2032 电池供电平均电流 10μA启用HID_PROTOCOL_MODE_BOOT禁用HID_INFORMATIONDescriptor工业级防爆鼠标-40℃~85℃宽温工作需抗 ESD 干扰配置HID_REPORT_INTERVAL_MS 88ms 报告间隔启用HID_EXTERNAL_REPORT_REF_DESC医疗康复手柄需通过 FDA 认证固件不可升级固化 Report Descriptor 到 Flash禁用HID_CONTROL_POINTCharacteristic值得注意的是BLE_HID 对硬件外设无强依赖它不直接操作 GPIO 或 ADC而是通过回调函数Callback机制接收原始输入事件。例如键盘扫描矩阵的消抖后按键码、鼠标光学传感器的 ΔX/ΔY 增量、手柄摇杆的 ADC 采样值均由用户代码采集并调用ble_hid_send_report()提交。这种解耦使同一套 BLE_HID 集成代码可复用于不同 PCB 设计。2. GATT 服务架构与关键特性详解BLE_HID 的 GATT 服务模型严格遵循蓝牙 SIG 定义包含一个必需的 HID Service0x1812及多个可选子服务。其拓扑结构如下图所示文字描述HID Service (0x1812) ├── HID Information Characteristic (0x2A4A) —— 只读含 bcdHID、bCountryCode、flags ├── Report Map Characteristic (0x2A4B) —— 只读二进制 Report Descriptor ├── HID Control Point Characteristic (0x2A4C) —— 写入用于重置报告/进入休眠 ├── Report Characteristic (0x2A4D) —— 通知/写入承载实际 HID 报文 │ ├── Client Characteristic Configuration Descriptor (0x2902) —— 控制通知开关 │ └── Report Reference Descriptor (0x2908) —— 标识 Report ID 与类型 ├── Protocol Mode Characteristic (0x2A4E) —— 读写切换 Report/Boot 协议 └── Boot Keyboard Input Report (0x2A22) —— 通知Boot 模式专用可选 └── Client Characteristic Configuration Descriptor (0x2902)2.1 HID Information Characteristic0x2A4A该特征值以 4 字节固定格式提供设备基础信息其结构定义如下字节偏移字段名长度说明典型值十六进制0-1bcdHID2 字节HID 规范版本号BCD 编码0x0111v1.112bCountryCode1 字节国家代码0x00未指定0x21US0x003flags1 字节功能标志位0x03支持 Boot Protocol Non-Boot Protocol在初始化阶段开发者需通过ble_hid_set_hid_info()函数设置该值。若flags的 Bit 0Remote Wake置位则需确保 MCU 的 BLE 中断能唤醒睡眠内核Bit 1Normally Connectable置位表示设备支持快速重连。2.2 Report Map Characteristic0x2A4B这是 BLE_HID 的核心数据契约。Report Descriptor 必须以完整、合法的 HID 语法描述所有上报数据的结构。BLE_HID 提供两种生成方式静态数组模式将预编译的 Descriptor 定义为const uint8_t report_map[]通过ble_hid_set_report_map(report_map, sizeof(report_map))注册动态构建模式调用hid_descriptor_builder_init()创建构建器链式调用add_usage_page()、add_usage()、add_logical_range()等函数生成二进制流。以下是一个标准 6 键无修饰键键盘的 Report Descriptor 示例16 进制0x05, 0x01, // USAGE_PAGE (Generic Desktop) 0x09, 0x06, // USAGE (Keyboard) 0xA1, 0x01, // COLLECTION (Application) 0x05, 0x07, // USAGE_PAGE (Keyboard/Keypad) 0x19, 0xE0, // USAGE_MINIMUM (Keyboard LeftControl) 0x29, 0xE7, // USAGE_MAXIMUM (Keyboard Right GUI) 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x25, 0x01, // LOGICAL_MAXIMUM (1) 0x75, 0x01, // REPORT_SIZE (1) 0x95, 0x08, // REPORT_COUNT (8) 0x81, 0x02, // INPUT (Data,Var,Abs) 0x95, 0x01, // REPORT_COUNT (1) 0x75, 0x08, // REPORT_SIZE (8) 0x81, 0x03, // INPUT (Const,Var,Abs) 0x95, 0x06, // REPORT_COUNT (6) 0x75, 0x08, // REPORT_SIZE (8) 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x25, 0x65, // LOGICAL_MAXIMUM (101) 0x05, 0x07, // USAGE_PAGE (Keyboard/Keypad) 0x19, 0x00, // USAGE_MINIMUM (Reserved (no event indicated)) 0x29, 0x65, // USAGE_MAXIMUM (Keyboard Application) 0x81, 0x00, // INPUT (Data,Ary,Abs) 0xC0 // END_COLLECTION该 Descriptor 定义了8 位修饰键Ctrl/Shift/Alt/GUI位图1 字节常量填充对齐字节边界6 字节按键码数组支持同时按下 6 个键。BLE_HID 在运行时会校验 Descriptor 的语法合法性如COLLECTION/END_COLLECTION匹配、REPORT_COUNT总和不超过 64 字节非法 Descriptor 将导致ble_hid_init()返回错误码BLE_HID_ERR_INVALID_DESCRIPTOR。2.3 Report Characteristic0x2A4D与数据通路Report Characteristic 是 HID 数据的实际载体。其行为由 Report Reference Descriptor0x2908决定该 Descriptor 的值为 2 字节格式为[Report ID][Report Type]其中Report Type为0x01Input、0x02Output、0x03Feature。当设备需上报输入事件时调用ble_hid_send_report(uint8_t report_id, const uint8_t* data, uint16_t len)。该函数执行以下操作查找匹配report_id的 Report Characteristic校验data长度是否等于 Descriptor 中声明的该 Report 的REPORT_SIZE × REPORT_COUNT若启用了通知Notification则通过ble_gatt_notify()向连接主机发送数据若主机写入 Output Report则触发用户注册的on_output_report_received回调。以下为 STM32 HAL NimBLE 的典型调用示例// 定义键盘 Report ID 1长度 8 字节 static uint8_t keyboard_report[8] {0}; void send_keypress(uint8_t keycode) { // 清空修饰键位 keyboard_report[0] 0; // 设置按键码第 3 字节起为按键数组 keyboard_report[2] keycode; // 发送 Report ID1 的 Input Report ble_hid_send_report(1, keyboard_report, sizeof(keyboard_report)); } // 主机写入 LED 状态Output Report ID2 static void on_output_report_cb(uint8_t report_id, const uint8_t* data, uint16_t len) { if (report_id 2 len 1) { // data[0] 的 Bit0NumLock, Bit1CapsLock, Bit2ScrollLock update_leds(data[0]); } }3. API 接口规范与嵌入式集成实践BLE_HID 提供一套精简但完备的 C API所有函数均以ble_hid_为前缀避免命名冲突。其头文件ble_hid.h仅依赖stdint.h和底层 BLE API 的抽象层如ble_hs.h或esp_ble.h无 STL 或 POSIX 依赖。3.1 初始化与生命周期管理函数原型参数说明返回值工程要点ble_hid_init(const ble_hid_cfg_t* cfg)cfg指向配置结构体含 Report Map、回调函数指针、GATT 服务句柄等0成功负值为错误码必须在 BLE Host 初始化完成后调用cfg-gatt_svc_handle需由用户通过ble_gatts_count_services()获取ble_hid_start_advertising(void)无参数0成功内部调用ble_gap_adv_start()广播数据中自动添加0x1812HID Service UUIDble_hid_disconnect(void)无参数0成功主动断开当前连接触发on_disconnect回调配置结构体ble_hid_cfg_t的关键字段typedef struct { const uint8_t* report_map; // Report Descriptor 地址 uint16_t report_map_len; // Descriptor 长度 ble_hid_event_handler_t on_connect; // 连接建立回调 ble_hid_event_handler_t on_disconnect; // 连接断开回调 ble_hid_output_report_handler_t on_output_report; // Output Report 接收回调 uint16_t gatt_svc_handle; // GATT 服务句柄由 BLE Host 分配 } ble_hid_cfg_t;3.2 报文传输 API函数原型参数说明返回值注意事项ble_hid_send_report(uint8_t report_id, const uint8_t* data, uint16_t len)report_id: Report IDdata: 数据缓冲区len: 数据长度0成功BLE_HID_ERR_NO_CONN未连接BLE_HID_ERR_INVALID_LEN长度不匹配数据长度必须严格匹配 Report Descriptor 中对应 Report 的总字节数若连接断开数据将被丢弃不缓存ble_hid_set_protocol_mode(uint8_t mode)mode:HID_PROTOCOL_MODE_REPORT或HID_PROTOCOL_MODE_BOOT0成功切换模式后主机需重新枚举 HID 设备Boot 模式下 Report ID 被忽略固定使用 8 字节格式3.3 与 FreeRTOS 的协同设计在多任务环境中BLE_HID 的回调函数如on_output_report通常在 BLE Host 的中断上下文或高优先级任务中执行。为避免阻塞 BLE 协议栈推荐采用队列任务的方式处理耗时操作// 定义队列存储 Output Report QueueHandle_t output_report_queue; void on_output_report_cb(uint8_t report_id, const uint8_t* data, uint16_t len) { output_report_t pkt; pkt.report_id report_id; pkt.len (len sizeof(pkt.data)) ? sizeof(pkt.data) : len; memcpy(pkt.data, data, pkt.len); // 发送至队列由独立任务处理 xQueueSend(output_report_queue, pkt, portMAX_DELAY); } // 独立任务处理 LED 更新 void output_report_task(void* pvParameters) { output_report_t pkt; while (1) { if (xQueueReceive(output_report_queue, pkt, portMAX_DELAY) pdTRUE) { process_output_report(pkt); // 实际 LED 控制逻辑 } } }此设计将 BLE 协议栈的实时性要求与应用层的复杂逻辑分离符合嵌入式系统分层设计原则。4. 硬件适配指南从原理图到固件4.1 电源与射频布局要点BLE_HID 设备的续航能力直接受射频性能影响。在 PCB 设计中必须遵守天线匹配网络严格按芯片参考设计放置 π 型匹配电路L1/C1/C2使用 0201 封装器件走线长度 ≤ 5mm电源去耦VDD_PA功率放大器电源需独立 LDO 供电并在芯片引脚处放置 100pF 1nF 陶瓷电容数字噪声隔离MCU 的 SWD 调试接口、USB 接口应远离天线区域地平面保持完整避免分割。我们曾调试一款因 USB 2.0 数据线串扰导致 BLE 连接频繁断开的键盘最终通过在 USB PHY 电源入口增加 10Ω 电阻 100nF 电容滤波解决。4.2 输入信号调理电路BLE_HID 不处理模拟信号但需确保输入源满足数字接口要求机械键盘矩阵采用 74HC244 或 SN74LVC244A 作为扫描驱动输出高电平 ≥ 0.7×VCC灌电流能力 ≥ 20mA光学鼠标传感器ADNS-9800 等芯片的Motion引脚需接 10kΩ 上拉PS2_CLK/DATA信号边沿时间 100ns游戏手柄摇杆双轴电位器输出经 RC 低通滤波R10kΩ, C100nF后接入 MCU ADC采样率 ≥ 1kHz。4.3 固件启动流程一个健壮的 BLE_HID 固件启动顺序应为graph TD A[上电复位] -- B[时钟初始化brHSI/PLL/HSE] B -- C[GPIO 初始化br按键/LED/传感器] C -- D[ADC/TIMER 初始化br用于输入采样] D -- E[BLE Host 初始化brSoftDevice/NimBLE] E -- F[ble_hid_init()] F -- G[启动广播brble_hid_start_advertising()] G -- H[进入低功耗循环brWFI 指令]在WFI循环中需使能以下中断源BLE_EVENT_IRQBLE 协议栈事件EXTI_KEY_IRQ按键外部中断TIMER_CC_IRQ定时器捕获鼠标运动。5. 故障诊断与性能优化5.1 常见连接问题排查现象可能原因诊断方法主机发现设备但无法连接HID Information中flags未置位0x03使用 nRF Connect App 读取0x2A4A特征值检查第 4 字节连接后无按键响应Report Descriptor 中REPORT_COUNT与send_report()长度不匹配用 Wireshark BLE sniffer 抓包比对ATT Write Request数据长度与 Descriptor 声明macOS 上 Caps Lock 不同步未实现HID_CONTROL_POINT特征值的写入处理检查on_write_request回调是否注册0x2A4C是否可写5.2 低功耗优化策略连接间隔动态调整空闲时调用ble_gap_conn_update()将conn_itvl_min/max设为0x00C8200ms活动时切回0x00067.5ms广播参数优化非连接态使用ADV_IND类型adv_int_min/max设为0x08001.28s降低平均功耗RTC 唤醒替代轮询用 RTC Alarm 替代HAL_Delay()实现 10ms 定时唤醒电流从 100μA 降至 1.2μA。在一款 CR2032 供电的键盘中上述优化使理论续航从 3 个月提升至 18 个月。BLE_HID 库的价值不在于其代码行数而在于它将蓝牙 SIG 数百页的协议规范压缩为 5 个核心 API 和一份可验证的 Report Descriptor。当你的键盘在 Windows 设备管理器中显示为“HID 兼容设备”当 macOS 的蓝牙菜单栏出现鼠标图标当 Android 的无障碍服务成功捕获按键事件——那一刻你写的不是代码而是嵌入式工程师与数字世界最朴素的握手协议。