BLE Profile 实战：HID over GATT（HOGP）键鼠即插即用
BLE 的 HID over GATT Profile（简称 HOGP）就是把 USB HID 那套"键盘/鼠标/手柄即插即用"的能力搬到了低功耗链路上。手机、电脑、电视之所以能"连上蓝牙键盘就能打字、不用装驱动"，靠的就是它。本文把 HOGP 的服务构成、关键特性和落地时最容易踩的坑讲清楚，适合要做 BLE 键鼠/手柄/遥控器的嵌入式工程师。
一、角色与架构
HOGP 里只有两种角色：
- HID Device（设备端）：GATT Server，通常是外设（键盘、鼠标、手柄），做 Peripheral。
- Report Host（主机端）：GATT Client，通常是手机/电脑，做 Central。
一个 HID 设备至少要注册三个服务：
- HID Service（0x1812）：核心，承载按键/移动数据。
- Battery Service（0x180F）：电量，主机普遍期望看到。
- Device Information Service（0x180A）：厂商/型号/版本，主机用来识别设备。
可选还有 Scan Parameters Service（0x1813），让主机把自己的扫描窗口告诉设备，省电用；不做也能跑。
二、HID Service（0x1812）完整特性
| 特性 | UUID | 属性 | 说明 |
|---|---|---|---|
| Protocol Mode | 0x2A4E | Read / Write Without Response | 0 = Boot 协议，1 = Report 协议 |
| Report | 0x2A4D | Read / Write / Notify | 数据主通道，可有多个实例 |
| Report Map | 0x2A4B | Read | HID 描述符（二进制），告诉主机数据怎么解析 |
| Boot Keyboard Input | 0x2A22 | Read / Notify | Boot 模式下键盘输入（8 字节固定） |
| Boot Keyboard Output | 0x2A32 | Read / Write / Write Without Response | Boot 模式下 LED 状态（Caps/Num/Scroll Lock） |
| Boot Mouse Input | 0x2A33 | Read / Notify | Boot 模式下鼠标输入（3 字节固定） |
| HID Information | 0x2A4A | Read | 4 字节：bcdHID + 国家码 + 标志位 |
| HID Control Point | 0x2A4C | Write Without Response | 0 = Suspend，1 = Exit Suspend |
三、Protocol Mode：Boot 与 Report
Protocol Mode（0x2A4E） 决定设备用哪种数据格式：
- 0 = Boot 协议：用固定长度格式（如键盘 8 字节、鼠标 3 字节），不需要 Report Map。最初设计是给 PC BIOS 阶段（操作系统没起来、没有完整 HID 栈）用的。
- 1 = Report 协议：默认模式，数据格式由 Report Map 描述，灵活、支持任意自定义报告。
实际产品里几乎都用 Report 模式：因为 PC/手机的 BIOS 阶段根本不会加载 BLE 协议栈（鼠标键盘的 BLE 连接要进系统后才有），Boot 模式在现代系统上基本用不上。设备启动后默认进 Report 模式即可。
四、Report 与 Report Reference 描述符
HID 服务里通常有多个 Report 特性（UUID 都是 0x2A4D）——比如键盘有"输入报告"（按键）、"输出报告"（LED），手柄有多个输入报告。怎么区分它们？靠 Report Reference 描述符（0x2908）：
- Report Reference 是一个 2 字节值：Report ID（1 字节）+ Report Type（1 字节）。
- Report Type：0x01 = Input（设备→主机），0x02 = Output（主机→设备），0x03 = Feature（双向）。
属性也要配套：Input 报告至少要能 Notify；Output 报告至少要能 Write；Feature 报告至少要能 Read + Write。主机扫到多个 0x2A4D 时，就是靠 Report Reference 的 Type 和 ID 来分辨谁是谁。
五、Report Map：HID 描述符
Report Map（0x2A4B） 是一段二进制 HID Report Descriptor，它描述每个 Report 里每一位的含义：哪个字节是 Modifier、哪个是按键码、鼠标 X/Y 各占几位、有没有滚轮……主机只有解析了它，才知道收到的字节流怎么翻译成按键。
它是只读的，一般在设备初始化时一次性写死。写错 Report Map 是最常见的"连上了但主机完全不懂数据"的原因——它必须和你在 Report 里实际发的字节布局严格对应。
六、HID Information 与 Control Point
HID Information（0x2A4A）：4 字节。前 2 字节是 bcdHID（版本，如 0x0101 表示 1.1），第 3 字节国家码（0x00 = 不限），第 4 字节标志位（如 0x02 = Normally Connectable）。HID Control Point（0x2A4C）：主机用来通知设备挂起/唤醒。0x00 = Suspend（主机休眠，设备进低功耗），0x01 = Exit Suspend。用 Write Without Response。
七、必须搭配 Battery 与 DIS
很多工程师只实现 0x1812，结果在部分系统上"能连但识别异常或电量不显示"。原因是 HOGP 规范把 Battery Service（0x180F，电量 0x2A19） 和 Device Information Service（0x180A） 列为期望服务，操作系统会主动去读。建议至少提供：
- Battery Level（0x2A19，Read + Notify）
- Manufacturer Name（0x2A29）、Model Number（0x2A24）、Firmware Revision（0x2A26）、PnP ID（0x2A50）
八、广播里要带什么
让主机在扫描阶段就把你识别成 HID 设备，广播包建议包含：
- Flags（0x01）：0x06 = LE General Discoverable + BR/EDR Not Supported（纯 BLE）。
- Complete 16-bit Service UUIDs（0x03）：放 0x1812（HID Service）。
- Appearance（0x19）：键盘 0x03C1、鼠标 0x03C2，帮助系统显示正确图标/行为。
九、Boot Keyboard Report 格式示例
即便用 Report 模式，了解 Boot 键盘格式也有助于调试（8 字节定长）：
- Byte 0：Modifier 修饰键掩码（Ctrl/Shift/Alt/GUI）。
- Byte 1：保留，固定 0x00。
- Byte 2~7：按键码（USB HID Usage ID），最多同时按 6 键。
- 松开时发全零 报告表示所有键释放。
例如按下 Page Down（Usage ID 0x4E）：[0x00, 0x00, 0x4E, 0x00, 0x00, 0x00, 0x00, 0x00]。
十、实战坑提醒
- Report Map 必须与真实数据布局一致，否则主机解析错乱——这是头号坑。
- 默认进 Report 模式（Protocol Mode = 1），Boot 模式现代系统基本用不上。
- 多个 Report 特性必须配 Report Reference（0x2908） 区分 Input/Output/Feature，否则主机分不清。
- Notify 类 Report 别忘了开 CCCD（0x2902），否则收不到按键。
- Battery / DIS 缺失 会导致某些 OS（尤其 Windows）识别为"未知设备"或电量永远 0。
- Appearance 要设对，键盘 0x03C1、鼠标 0x03C2，影响系统交互。
- HID Control Point 用 Write Without Response，别用需要响应的写。
- iOS / Android 的 HOGP 一般要求配对绑定，首次连接会弹配对框，做好 SMP/安全。
- MTU 影响单包 Report 长度，长报告（如带很多 usages 的手柄）注意分片或提升 MTU。
- Report ID 不是 GATT 层概念，它是 Report Map 内部编号，配合 Report Reference 使用，不要和 GATT 实例混淆。
一句话总结：HOGP = HID Service（0x1812）为核心 + Battery + DIS 作标配，Report Map 描述数据、Report Reference 区分多报告、Protocol Mode 切 Boot/Report；把 Report Map 和 CCCD 做对，键鼠就即插即用了。
