BLE HID嵌入式实现：基于GATT的轻量级键盘鼠标无线方案

1. BLE_HID 库深度解析基于 GATT 的嵌入式 HID 设备实现方案1.1 技术定位与工程价值BLE_HID 是一个面向嵌入式平台的轻量级 HID-over-GATT 协议栈实现库其核心目标是将传统 USB HID 设备如键盘、鼠标、游戏手柄的功能无缝迁移至 Bluetooth Low EnergyBLE无线通道。该库不依赖完整蓝牙协议栈如 BlueZ 或 NimBLE Host而是直接构建在厂商提供的 BLE API 层之上通过标准 GATT 服务定义与特征值操作完成 HID 功能抽象。在工业控制、医疗外设、智能办公终端等场景中BLE_HID 具有明确的工程优势低功耗确定性相比经典蓝牙 HIDHID over BR/EDRBLE 连接建立时间更短 100ms广播/连接态电流可控制在 15–30μA深度睡眠与 5–8mA活跃通信之间免驱动部署Windows 10/11、macOS 12、Android 6.0 均内置 BLE HID 客户端驱动无需用户安装额外驱动程序资源占用可控典型实现仅需 8–12KB Flash含 GATT DB 定义与 HID Report Descriptor 解析逻辑、3–5KB RAM含输入报告缓冲区与连接上下文硬件适配灵活支持 STM32WB 系列HAL BLE Stack、nRF52832/52840Nordic SDK、ESP32ESP-IDF BLE Host等主流 BLE SoC 平台。该库的本质并非独立协议栈而是对 BLE 规范中HID Service (0x1812)与HID Information (0x2A4A)、Report Map (0x2A4B)、Report (0x2A4D)、Protocol Mode (0x2A4E)等标准化特征值的封装层其价值在于将晦涩的 GATT 属性操作转化为面向 HID 设备开发者的语义化接口。2. BLE HID 协议栈架构与 GATT 服务映射2.1 标准 BLE HID 服务结构根据 Bluetooth SIG Adopted Specification v5.2 第 5 卷 GATT 部分HID ServiceUUID:00001812-0000-1000-8000-00805F9B34FB必须包含以下强制性特征值Characteristic特征值 UUID名称属性说明00002A4A-0000-1000-8000-00805F9B34FBHID InformationRead返回 HID 版本号BcdHID、国家代码Country Code、未启用标志Flags0x0000002A4B-0000-1000-8000-00805F9B34FBReport MapRead包含 HID Report Descriptor 的二进制数据USB HID 1.11 格式00002A4D-0000-1000-8000-00805F9B34FBReportRead/Write/Notify输入/输出/特征报告载体需绑定到 Report Reference 描述符00002A4E-0000-1000-8000-00805F9B34FBProtocol ModeRead/Write设置协议模式0x00Boot Protocol, 0x01Report Protocol00002A4C-0000-1000-8000-00805F9B34FBControl PointWrite控制 HID 设备行为如挂起/唤醒此外每个 Report 特征值必须关联一个Report Reference 描述符Descriptor UUID:00002908-0000-1000-8000-00805F9B34FB用于标识该 Report 的类型Input/Output/Feature与 IDReport ID。此描述符为必需项缺失将导致主机端无法解析报告内容。BLE_HID 库的核心职责即为构建符合规范的 GATT 数据库GATT DB实现 Report Map 的静态/动态加载提供线程安全的 Report 数据提交接口触发 Notify处理主机端对 Protocol Mode 与 Control Point 的写请求。2.2 BLE_HID 库的分层设计该库采用三层抽象模型兼顾可移植性与性能--------------------- | Application Layer | ← 用户调用blehid_send_keyboard_report() | (Device Logic) | ------------------ ↓ --------------------- | BLE_HID Core Layer | ← 协议逻辑Report 封装、GATT 事件分发 | (HID Service Logic) | ------------------ ↓ --------------------- | BLE API Adapter | ← 平台适配HAL_UART_Transmit → BLE Stack API | (Vendor Abstraction) | ---------------------Application Layer由开发者实现负责采集物理输入GPIO 中断、ADC 采样、I²C 传感器读取并调用blehid_send_*_report()接口提交数据Core Layer库主体维护 HID Service 上下文当前连接句柄、报告缓冲区、协议模式状态处理 GATT 写请求回调如 Protocol Mode 切换Adapter Layer针对不同芯片厂商的 BLE SDK 封装例如STM32WB调用aci_gatt_update_char_value()更新 Report 特征值nRF52调用sd_ble_gatts_value_set()sd_ble_gatts_hvx()发送 NotifyESP32调用esp_ble_gatts_set_attr_value()esp_ble_gatts_send_indicate()。此分层确保同一套 HID 业务逻辑可在不同硬件平台复用仅需重写 Adapter 层。3. 关键 API 接口详解与使用规范3.1 初始化与服务注册// 初始化 HID Service传入 Report Map 地址与长度 blehid_status_t blehid_init(const uint8_t *report_map, uint16_t map_len); // 注册 HID Service 到 GATT 数据库需在 BLE Stack 初始化后调用 blehid_status_t blehid_service_register(void);report_map指向 HID Report Descriptor 的 const uint8_t 数组必须为 USB HID 1.11 格式。例如标准键盘 Report Descriptor104 键static const uint8_t keyboard_report_map[] { 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) 0x25, 0x65, // LOGICAL_MAXIMUM (101) 0x19, 0x00, // USAGE_MINIMUM (Reserved (no event indicated)) 0x29, 0x65, // USAGE_MAXIMUM (Keyboard Application) 0x81, 0x00, // INPUT (Data,Ary,Abs) 0xC0 // END_COLLECTION };map_lenReport Descriptor 字节数上例为 63 字节。若 descriptor 超过单次 ATT MTU通常 23 字节库需自动分片读取但要求report_map存储于非易失性内存Flash。3.2 报告发送接口// 发送键盘输入报告最多 6 个普通按键 修饰键 blehid_status_t blehid_send_keyboard_report(uint8_t modifier, uint8_t reserved, const uint8_t keys[6]); // 发送鼠标输入报告X/Y 位移、按钮状态、滚轮 blehid_status_t blehid_send_mouse_report(int8_t x, int8_t y, uint8_t buttons, int8_t wheel); // 发送通用 Report需指定 Report ID 与数据缓冲区 blehid_status_t blehid_send_report(uint8_t report_id, const uint8_t *data, uint16_t len);键盘报告格式Report ID 1字节含义范围0修饰键ModifierBit0Ctrl, Bit1Shift, Bit2Alt, Bit3GUI, Bit4–7Reserved1保留字节Must be 00x002–7按键码Key Codes0x00无按键0x04–0x65标准键码鼠标报告格式Report ID 2字节含义范围0按钮状态ButtonsBit0Left, Bit1Right, Bit2Middle1X 位移Signed 8-bit-127 ~ 1272Y 位移Signed 8-bit-127 ~ 1273滚轮Wheel-127 ~ 127⚠️关键约束所有send_*_report()调用必须在GATT 连接已建立且客户端已使能 Report 特征值的 Notify 属性后执行。若连接断开或 Notify 未使能函数返回BLEHID_STATUS_NOT_CONNECTED或BLEHID_STATUS_NOTIFY_DISABLED不会自动缓存数据。应用层需自行实现重试队列如 FreeRTOS Queue。3.3 回调事件处理库通过注册回调函数接收主机端控制请求typedef struct { void (*on_protocol_mode_changed)(uint8_t mode); // mode: 0x00(Boot), 0x01(Report) void (*on_control_point_received)(uint8_t command); // command: 0x00(Suspend), 0x01(Exit Suspend) void (*on_connection_established)(void); void (*on_connection_lost)(void); } blehid_callback_t; void blehid_register_callbacks(const blehid_callback_t *cb);on_protocol_mode_changed()当主机写入 Protocol Mode 特征值时触发。Boot Protocol 下键盘/鼠标使用固定格式无 Report ID兼容旧系统Report Protocol 下使用 Report ID 寻址支持多报告类型on_control_point_received()主机写入 Control Point 特征值值为 0x00 或 0x01时调用设备应进入低功耗状态或恢复通信on_connection_established/lost()连接状态变更通知常用于切换 LED 指示灯或关闭/开启传感器采样。4. 典型硬件平台集成实践4.1 STM32WB55 STM32CubeWBHAL BLE Stack在main.c中初始化流程如下#include ble.h #include blehid.h // Report Map 定义存于 Flash const uint8_t keyboard_map[] __attribute__((section(.flash_data))) { /* ... */ }; void SystemClock_Config(void); static void MX_GPIO_Init(void); static void ble_stack_init(void); int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); // 1. 初始化 BLE Stack ble_stack_init(); // 调用 HCI_TL_MM_Init() 等 // 2. 初始化 BLE_HID if (blehid_init(keyboard_map, sizeof(keyboard_map)) ! BLEHID_STATUS_SUCCESS) { Error_Handler(); // 初始化失败 } // 3. 注册服务 if (blehid_service_register() ! BLEHID_STATUS_SUCCESS) { Error_Handler(); } // 4. 注册回调 blehid_callback_t cb { .on_protocol_mode_changed handle_protocol_mode, .on_connection_established led_on, .on_connection_lost led_off, }; blehid_register_callbacks(cb); // 5. 启动 BLE 广播 aci_gap_set_discoverable(ADV_IND, 0, 0, PUBLIC_ADDR, NO_WHITE_LIST_USE, 0, 0, 0, 0, 0, 0, 0); while (1) { // 主循环扫描 GPIO 按键检测到按下则发送报告 if (HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) GPIO_PIN_RESET) { static uint8_t key_buffer[6] {0}; key_buffer[0] 0x04; // a 键码 blehid_send_keyboard_report(0x00, 0x00, key_buffer); HAL_Delay(100); // 去抖 } HAL_PWREx_EnterCPUIdleMode(PWR_MAINREGULATOR_ON); } }注意STM32WB 的 BLE Stack 运行于 Cortex-M0 内核应用代码运行于 M4需通过 IPC 机制如SHCI_C2_Ble_Init()同步初始化。blehid_service_register()内部调用aci_gatt_add_serv()添加服务。4.2 nRF52840 Nordic SDK 17.1SoftDevice S140Adapter 层需实现nrf52_blehid_adapter.c// 将 BLE_HID 的 Notify 请求转换为 SoftDevice API blehid_status_t nrf52_hid_notify(uint16_t conn_handle, uint16_t attr_handle, const uint8_t *data, uint16_t len) { ble_gatts_hvx_params_t hvx_params {0}; hvx_params.handle attr_handle; hvx_params.type BLE_GATTS_HVX_NOTIFICATION; hvx_params.offset 0; hvx_params.p_len len; hvx_params.p_data (uint8_t*)data; uint32_t err_code sd_ble_gatts_hvx(conn_handle, hvx_params); return (err_code NRF_SUCCESS) ? BLEHID_STATUS_SUCCESS : BLEHID_STATUS_ERROR; }在sdk_config.h中需启用#define CONFIG_NFCT_PINS_AS_GPIOS 1 #define BLE_GATTS_VAR_ATTR_LEN 1 #define BLE_GATTS_CHAR_MTU_DEFAULT 235. 调试与问题排查指南5.1 常见连接失败原因现象可能原因解决方案手机/PC 无法发现设备广播包未包含 Flags0x01与 Complete Local Name0x09在aci_gap_set_discoverable()前调用aci_gap_set_device_name()并确保广播数据中包含0x01, 0x06, 0x09, name_len, ...连接后立即断开HID Service 未正确注册或 Report Map 长度 512 字节使用 nRF Connect 或 LightBlue 检查 GATT 浏览器确认0x1812服务存在且0x2A4B特征值可读Report Map 长度上限由芯片 BLE Stack 决定nRF52 为 512BSTM32WB 为 256B键盘按键无响应Report ID 与 Report Reference 描述符不匹配检查 Report Reference 描述符值输入报告应为[0x01, 0x01]Report ID1, TypeInput若 Report ID0则描述符为[0x00, 0x01]5.2 协议模式切换调试Windows 主机默认使用 Boot ProtocolProtocol Mode 0x00而 macOS/Android 默认使用 Report Protocol0x01。若设备仅实现单一模式需在on_protocol_mode_changed()回调中动态切换内部报告格式static uint8_t g_protocol_mode 0x01; void handle_protocol_mode(uint8_t mode) { g_protocol_mode mode; if (mode 0x00) { // Boot Protocol键盘报告为 8 字节modifier 6 keys无 Report ID // 鼠标报告为 4 字节buttons x y wheel无 Report ID } else { // Report Protocol所有报告前缀 Report ID 字节 } }✅验证方法在 Windows 上运行hdwwiz.exe→ “添加硬件” → 手动选择“HID Keyboard Device”若驱动安装成功且设备管理器显示“HID 键盘”表明 Boot Protocol 工作正常在 macOS 的“系统设置→蓝牙”中查看设备名称旁是否显示“已连接”并测试按键响应。6. 性能优化与低功耗设计要点6.1 报告发送吞吐量控制BLE HID 的理论最大吞吐量受限于连接间隔Connection Interval。根据蓝牙规范最小连接间隔为 7.5ms对应 125Hz 报告率但实际中需权衡功耗与延迟连接间隔典型报告率适用场景平均电流7.5–15ms66–125Hz游戏手柄、实时鼠标3.2–4.8mA30–50ms20–33Hz办公键盘、演示遥控器1.8–2.5mA100–500ms2–10Hz低功耗传感器节点0.3–0.8mA在blehid_send_*_report()内部库不进行速率限制应用层必须实现节流逻辑。推荐使用 FreeRTOS Timerstatic TimerHandle_t report_timer; void send_keyboard_debounced(uint8_t mod, uint8_t res, uint8_t keys[6]) { // 仅当定时器未运行时发送 if (xTimerIsTimerActive(report_timer) pdFALSE) { blehid_send_keyboard_report(mod, res, keys); xTimerStart(report_timer, 0); } } void report_timer_callback(TimerHandle_t xTimer) { // 定时器到期允许下次发送 }6.2 深度睡眠唤醒策略在无按键活动时设备应进入深度睡眠Stop Mode with RTC Wakeupvoid enter_deep_sleep(void) { // 1. 关闭所有外设时钟 __HAL_RCC_GPIOA_CLK_DISABLE(); __HAL_RCC_GPIOB_CLK_DISABLE(); // 2. 配置 RTC Alarm 唤醒如 5 秒后 HAL_RTC_SetAlarm_IT(hrtc, sAlarm, RTC_FORMAT_BIN); // 3. 进入 Stop Mode HAL_PWR_EnterSTOPMode(PWR_LOWPOWERREGULATOR_ON, PWR_STOPENTRY_WFE); }唤醒后需重新初始化 BLE Radioaci_hal_set_radio_activity()但无需重建 GATT Service —— 连接上下文由 SoftDevice 维护。7. 安全边界与合规性提醒BLE_HID 库本身不提供加密功能所有 Report 数据以明文传输。在涉及敏感输入如密码键盘的场景中必须叠加应用层加密方案一在blehid_send_keyboard_report()调用前对keys[]数组进行 AES-128-ECB 加密密钥预置在 Flash方案二使用 BLE Secure ConnectionsLE SC在配对阶段协商 LTK由 SoftDevice 自动加密 ATT 信道需启用SECURE_CONNECTIONS编译选项。此外需注意 FCC/CE 认证要求广播功率不得超过 10dBm多数芯片默认为 0dBm若设备含锂电池需通过 UN38.3 运输安全测试HID Report Descriptor 中的 Usage Page 必须与实际功能一致如游戏手柄不可声明为0x01 Generic Desktop而非0x05 Game Controls否则可能被 iOS 拒绝连接。最终交付前务必使用蓝牙协议分析仪如 Ellisys BEX400抓包验证广播包中Flags字段为0x06LE General Discoverable BR/EDR Not Supported连接后首次读取0x2A4B返回完整 Report MapNotify 数据包 payload 与blehid_send_*_report()参数严格一致。