HID 按键#
GPIO (General Purpose Input/Output) 按键 → BLE (Bluetooth Low Energy) 键盘 — HID (Human Interface Device) over GATT (Generic Attribute Profile) Boot 模式
前置阅读:Hello BLE 和 Hello Notify
学习目标#
理解 HID over GATT 的服务结构和 Boot Keyboard Report 格式
掌握 WS53 板载 S1 按键的 GPIO 映射、消抖和长按处理
理解按下报告与释放报告必须成对发送的原因
能够将 WS53 配置为免驱 BLE 键盘外设并验证 Page Down 输入
基本概念#
HID over GATT#
BLE HID 通过 GATT 承载。WS53 作为 Peripheral/GATT Server,注册标准 HID Service 0x1812;PC 或手机作为 Central/GATT Client,发现服务并通过 Notification 接收键盘报告。
sequenceDiagram
participant B as 板载 S1
participant W as WS53 HID Server
participant H as PC / Phone HID Host
W->>W: 注册 HID Service 0x1812
W-->>H: 广播 HID UUID 和 Keyboard Appearance
H->>W: 连接并订阅 Boot Keyboard Input
B->>W: 按下
W-->>H: 8 字节按键报告
B->>W: 松开
W-->>H: 8 字节全零报告
WS53 不支持 BLE Central/GATT Client 功能;本案例中的 Client/Host 是外部 PC 或手机。
HID Service 结构#
Characteristic |
UUID |
Property |
说明 |
|---|---|---|---|
HID Information |
|
Read |
HID 1.11、Remote Wake、Normally Connectable |
HID Control Point |
|
Write Without Response |
注册标准属性;当前未实现 Suspend / Exit Suspend 业务 |
Protocol Mode |
|
Read、Write Without Response |
注册标准属性;当前按键发送路径固定使用 Boot 模式 |
Report Map |
|
Read |
68 字节键盘报告描述符 |
Boot Keyboard Input |
|
Read、Notify |
8 字节按键报告,带 CCCD |
Boot Keyboard Output |
|
Read、Write、Write Without Response |
注册标准属性;当前未解析键盘 LED 输出 |
Boot Keyboard Input Report#
输入报告固定为 8 字节:
字节 |
字段 |
说明 |
|---|---|---|
0 |
Modifier |
Ctrl、Shift、Alt 等修饰键位图,本案例固定为 0 |
1 |
Reserved |
固定为 0 |
2~7 |
Keycodes |
最多 6 个普通键码,本案例只使用第一个 |
默认 Page Down 按下和松开报告:
状态 |
报告 |
|---|---|
按下 |
|
松开 |
|
如果只发送按下报告而不发送释放报告,Host 会认为按键仍处于按下状态,可能产生连续输入。
BLE 广播#
广播数据包含:
AD 字段 |
内容 |
|---|---|
Flags |
|
Complete 16-bit Service UUIDs |
HID |
Appearance |
Keyboard |
扫描响应包含 CONFIG_BLE_HID_DEVICE_NAME,默认设备名为 ble_hid_btn。广播间隔为 20~30 ms,使用 37、38、39 三个广播信道。
按键消抖与长按#
案例每 20 ms 读取一次按键,连续两次读到相同状态后确认变化。默认板载 S1 使用 MGPIO6,高电平有效且不启用内部上下拉。
flowchart TD
A[读取 GPIO] --> B{与上次采样一致}
B -->|否| C[更新候选状态并重新计数]
B -->|是| D{连续两次一致}
D -->|否| A
D -->|是| E{状态发生变化}
E -->|按下| F[发送键码报告]
E -->|松开| G[发送全零报告]
F --> H{按住超过 500 ms}
H -->|启用长按| I[额外发送释放/按下序列]
配置其他 GPIO 时,源码走低电平有效、内部上拉的通用分支,需要结合实际硬件复核电平和上下拉。
涉及 API#
API |
用途 |
|---|---|
|
启用 BLE 协议栈 |
|
注册广播和连接状态回调 |
|
设置可发现设备名 |
|
同时设置 HID 广播数据和扫描响应数据 |
|
配置并启动可连接广播 |
|
注册 GATT Server |
|
创建 HID Service |
|
创建 HID 标准 Characteristic |
|
为 Boot Keyboard Input 创建 CCCD |
|
发送 8 字节按键报告 |
|
配置 S1 GPIO 输入 |
|
周期读取按键电平 |
案例说明#
功能规格#
规格项 |
当前实现 |
|---|---|
BLE 角色 |
Peripheral / GATT Server |
Service UUID |
HID |
输入报告 |
Boot Keyboard Input |
默认按键 |
板载 S1 / MGPIO6,高电平有效 |
采样和消抖 |
20 ms 采样,连续 2 次确认 |
默认键码 |
|
长按 |
默认开启,超过 500 ms 额外重复一次 |
设备名 |
|
断连行为 |
自动重新广播 |
案例流程#
WS53 注册 HID GATT Server 并启动广播。
按键任务配置板载 S1,开始周期采样和消抖。
PC 或手机连接
ble_hid_btn并订阅 Boot Keyboard Input。S1 按下时发送配置键码,松开时发送全零报告。
Host 断开后 WS53 重新广播。
源码对应关系#
内容 |
源码位置 |
|---|---|
案例入口、GPIO 和按键状态机 |
|
HID GATT Service 和报告发送 |
|
广播和扫描响应 |
|
用户配置 |
|
案例操作指导#
第一步:配置案例#
CONFIG_SAMPLE_ENABLE=y
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_HID_BTN_SAMPLE=y
CONFIG_BLE_HID_BTN_PIN=6
CONFIG_BLE_HID_BTN_KEYCODE=78
CONFIG_BLE_HID_BTN_LONGPRESS=y
CONFIG_BLE_HID_DEVICE_NAME="ble_hid_btn"
BLE 案例使用 Kconfig choice 互斥选择,同一固件中只能启用一个 BLE 示例。
第二步:准备硬件#
默认配置直接使用 WS53 板载 S1,无需外接按键。S1 映射为逻辑 MGPIO6,对应 S_MGPIO6 / pin_t 32,高电平表示按下。
第三步:编译和烧录#
fbb build ws53_liteos_app
fbb flash ws53_liteos_app
第四步:验证#
在 PC 或手机上搜索并连接
ble_hid_btn。打开能够接收键盘输入或响应 Page Down 的应用。
短按板载 S1,确认应用收到一次 Page Down。
按住 S1 超过 500 ms,检查长按重复行为。
使用通用 GATT 工具时,手动订阅 HID Service
0x1812下的 Boot Keyboard Input0x2A22。
WS53 正常输出:
[ble_hid_btn_sample] task started, gpio=6 pin_t=32 keycode=0x4E active=high
[ble_hid_btn_sample] press key=0x4E
[ble_hid_btn_sample] release
关键配置#
配置项 |
默认值 |
说明 |
|---|---|---|
|
|
逻辑 MGPIO 编号;6 对应板载 S1 |
|
|
USB HID Usage ID,即 |
|
|
启用一次长按重复 |
|
|
PC 或手机扫描时显示的名称 |
常见 Keyboard Page 键码包括 0x4B Page Up、0x4E Page Down、0x2C Space 和 0x28 Enter。0xE9、0xEA 属于 Consumer Page 音量键,不能直接作为普通 Keyboard Page 键码使用。
代码详解#
1. HID Report#
hid_kb_report_t 固定为 8 字节。按下时将配置键码写入 keys[0],松开时发送全零结构体。ble_hid_btn_send_report() 仅在 Host 已连接时调用 gatts_notify_indicate()。
2. HID Service 注册#
build_hid_service() 创建 Service 0x1812,随后依次添加 Protocol Mode、Report Map、Boot Keyboard Input/Output、HID Information 和 HID Control Point。只有 Boot Keyboard Input 带 CCCD,用于发送 Notification。
当前写回调没有区分 Protocol Mode、Boot Keyboard Output 和 HID Control Point 的 Handle,因此这些标准属性仅完成注册,尚未形成完整业务闭环。后续实现需增加 Handle 分流、取值校验、挂起状态、LED 位图处理,以及与 Protocol Mode 对应的发送路径。
3. 按键任务#
hid_btn_task() 配置 GPIO 并以 20 ms 周期采样。hid_button_update_level() 完成连续两次确认消抖,hid_button_handle_state() 处理按下、松开和长按重复。
4. 断连恢复#
连接状态回调在 Host 断开后调用 ble_hid_adv_restart(),重新等待 PC 或手机连接。
常见问题#
扫描不到设备:确认案例已启用,并检查广播启动日志和设备名配置。
已连接但按键无效:确认 Host 已识别 HID Service,或使用 GATT 工具订阅
0x2A22。按一次却连续翻页:确认松开时发送了全零报告,并检查按键电平与消抖日志。
修改 GPIO 后状态相反:非 MGPIO6 配置默认使用低电平有效和内部上拉,需要按实际电路调整。
修改为音量键后无效:当前报告描述符使用 Keyboard Page,不支持直接发送 Consumer Page 键码。