简介：这是一份基于NRF52832芯片的蓝牙低功耗（BLE）人机接口设备（HID）键盘应用例程，面向物联网及蓝牙开发初学者与中级工程师，可帮助解决在无物理USB接口场景下实现无线键盘输入的问题。资源共包含200个文件，压缩包约10.19MB，包含74个编译生成的o目标文件与d依赖文件、可直接烧录的hex固件、ld链接脚本，以及h头文件、makefile和uvproj工程配置，便于查阅代码与重新编译。已有722人学习参考。例程源码结构清晰，涵盖ble_hidsKeyboard服务实现、main主流程、GPIO按键中断及日志模块，并详解了从BLE HID规范、芯片特性到编译烧录、配对测试的完整链路，完整展示了BLE HID服务的注册、按键上报与事件回调机制。开发者可据此快速搭建虚拟键盘原型，并扩展为游戏手柄、遥控器等自定义BLE HID设备，是学习NRF52832 HID应用的良好起点。

1. 把 BLE HID 键盘固件跑起来：NRF52832 上最完整的一块拼图

看到ble_app_hids_keyboard.rar这个名字，熟悉 Nordic SDK 的人会立刻认出这是那套经典 BLE HID 键盘例程的打包工程，但真正把它用进项目的人都知道，从编译通过到按键稳定上屏，中间隔着 HID 报告、配对绑定、连接参数和功耗管理这四道坎。这份资源解决的就是 nRF52832 作为标准无线键盘的整套链路问题：Android、iOS、Windows 的蓝牙协议栈都会把它识别成键盘设备，按下键立刻出字符，不需要任何 app 做中间层翻译。它适合两类人：一是手上有 nRF52832 开发板、想快速变成无线键盘的嵌入式工程师，二是做自定义键帽、宏键盘、无线遥控器的硬件玩家，需要一份能直接改骨架的 BLE HID 固件。不管你是想改键位、加多媒体键还是调功耗，这份工程都是很好的起点。

2. HID over GATT 的骨架：服务初始化与报告映射的四个关键点

2.1 为什么键盘必须走 HID over GATT，而不是自定义服务

BLE 外设上报数据其实有三条主流路线：自定义服务、传感器服务、HID 服务。键盘这个品类很特殊，它服务的是操作系统输入子系统，不是某个 app。iOS、Android 和 Windows 的蓝牙协议栈识别键盘的第一反应，就是去找 HID over GATT（HOGP）规范里定义的键盘报告，而自定义 Service 里发的字节流，系统输入法根本不会解析。哪怕你通过私有服务把按键码发到手机端，在字符落进输入框之前，数据就已经断在系统边界上。

Nordic SDK 把 HOGP 的封装集中在 ble_hids 模块，自动处理 Report Map 的存储、报告特征的通知使能，以及 Protocol Mode 切换。你需要做的只是填充报告内容、处理事件回调。这个工程的价值是把 ble_hids 和广播、配对、按键扫描、功耗管理捏合成一个可以直接运行的 demo。如果去 SDK 示例堆里自己拼这条链路，光是服务初始化就能折腾两三天，更不用说后面还要调连接参数。

2.2 services_init 流程：从协议栈到 HID 服务注册

初始化顺序不能乱。协议栈从上到下的注册顺序是 softdevice → GAP → GATT → HID 服务，只要顺序反了，ble_hids_init大概率返回NRF_ERROR_INVALID_STATE。我习惯把服务注册统一收在services_init函数里，逻辑清楚也方便单独排查：

static void services_init(void) { uint32_t err_code; ble_hids_init_t hids_init_obj = {0}; hids_init_obj.is_kb = true; // 键盘类设备 hids_init_obj.is_mouse = false; // 不启用鼠标 hids_init_obj.is_consumer = true; // 消费类报告，音量/媒体键走这里 hids_init_obj.included_services_count = 0; // 第一份输入报告：标准 8 字节键盘报告 hids_init_obj.input_report_count = 1; hids_init_obj.input_report[0].max_len = 8; hids_init_obj.input_report[0].rep_ref.report_id = 0; hids_init_obj.input_report[0].rep_ref.report_type = BLE_HIDS_REP_TYPE_INPUT; hids_init_obj.evt_handler = hids_evt_handler; err_code = ble_hids_init(&m_hids, &hids_init_obj); APP_ERROR_CHECK(err_code); }

参数拆解：is_kb让模块绑定键盘 Usage，is_consumer额外开一条消费类报告通道，媒体键、音量键都走这条独立通道，不和普通按键抢带宽。input_report_count决定 RAM 里预分配的输入报告数量，纯键盘场景一份就够；如果要做键盘/鼠标/自定义宏多模式切换，这里要对应增加。max_len定义 8 字节，对应标准「修饰键 + 保留 + 6 按键」结构，和下一节的 Report Map 必须严格一致。

服务注册完别急着广播。先用ble_advdata配置广播数据，键盘设备的 appearance 要设成BLE_APPEARANCE_KEYBOARD，广播名比如 "NRF52 Keyboard"。appearance 影响 iOS 弹出配对框时的图标类型，名称影响用户在系统蓝牙菜单里的辨识度，这两个字段很多人忽略，等真机测试再回来改就要多烧一次固件。另外，ble_hids_init失败时先查 SoftDevice 是否已经启用、GATT 是否注册，这两个前置条件不满足，返回值往往是让你摸不着头脑的NRF_ERROR_INVALID_STATE。

2.3 报告描述符：收发端对峙的边界

Report Map 是系统解析键值的唯一依据。它定义了报告里的每一位怎么解释，由 Usage Page、Usage Minimum、Logical Minimum 等标签构成一个字节数组。Nordic SDK 允许把它作为一个数组定义在代码中，下面是标准 8 字节键盘报告的精简版描述符：

static uint8_t report_map_data[] = { 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) 0x05, 0x07, // Usage Page (Keyboard) 0x19, 0xE0, // Usage Minimum (224) 0x29, 0xE7, // Usage Maximum (231) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x75, 0x01, // Report Size (1) 0x95, 0x08, // Report Count (8) 0x81, 0x02, // Input (Data, Variable, Absolute) 0x95, 0x01, // Report Count (1) 0x75, 0x08, // Report Size (8) 0x81, 0x01, // Input (Constant) 保留字节 0x95, 0x05, // Report Count (5) 0x75, 0x01, // Report Size (1) 0x05, 0x08, // Usage Page (LEDs) 0x19, 0x01, // Usage Minimum (1) 0x29, 0x05, // Usage Maximum (5) 0x91, 0x02, // Output (Data, Variable, Absolute) 0xC0 // End Collection };

前 8 位是修饰键，第二字节保留，后面 48 位是 6 个 HID 按键码。这里的逻辑顺序必须和发送代码的字节对齐，不然就会出现系统把偏移 1 的字节当成保留位、按键码整体错位这类问题。上传到 ble_hids 后，模块会把这段描述符作为 Report Map 特征值供主机读取，Host 端据此解析后续所有输入报告。

注意：Report Map 在连接建立后是只读的，不能在运行中动态改长度。想切换键盘布局，标准做法是准备多份 report map 在启动时选择，而不是连接后用 GATT 写操作去改。

2.4 连接参数：键盘的关键是响应，不是带宽

BLE 连接参数由主从协商，但从机可以主动发起更新请求。键盘链路最重要的指标是端到端延迟，不是吞吐量，因此推荐把连接间隔压到 7.5~15ms：

从机延迟很多人理解成省电利器，但对键盘来说它恰恰是延迟元凶。设成 1 意味着从机最多可跳过 1 个连接事件，键盘扫描到按键后最坏要等两个连接间隔才能上报，体感就变成「慢半拍」。功耗的事交给广播间隔和应用空闲处理，别从连接参数上省。

连接参数更新有个前提：主机不一定同意你的请求。iOS 相对守规矩，Android 部分厂商 ROM 会直接忽略从机的参数更新请求，这时你会看到系统里明明连接成功但延迟就是压不下来。这类玄学问题大多出在参数协商阶段，排查时用 nRF Connect 看实际连接参数，只要显示的是 7.5ms 附近就说明协商成功，否则要去查主机端的协议栈策略。

3. 按键矩阵与扫描：把物理按键变成 HID 报告的完整链路

3.1 矩阵接线：行列 GPIO 怎么选

讲完 HID 服务，下一步是把物理按键接入。直接每个键一个 GPIO 不适合任何超过 8 键的设计，标准做法是行列矩阵扫描。以 3×4 矩阵为例，行接输入，列接驱动输出：

#define ROW_COUNT 3 #define COL_COUNT 4 static const uint8_t row_pins[ROW_COUNT] = {11, 12, 13}; static const uint8_t col_pins[COL_COUNT] = {5, 6, 7, 8}; static void matrix_init(void) { for (int i = 0; i < ROW_COUNT; i++) { nrf_gpio_cfg_input(row_pins[i], NRF_GPIO_PIN_PULLUP); } for (int i = 0; i < COL_COUNT; i++) { nrf_gpio_cfg_output(col_pins[i]); nrf_gpio_pin_set(col_pins[i]); // 默认拉高 } }

GPIO 选型上避开 nRF52832 的 19、20 引脚，这两个引脚复用在 NFC 功能上，默认被协议栈占用。行上拉用NRF_GPIO_PIN_PULLUP，列驱动输出时每次只拉低一列，然后读整行状态。row 和 col 的引脚号不要和调试串口、LED 冲突，这类冲突在 PCB 上往往要飞线时才发现，提前列一份引脚占用表能省掉飞线改板的麻烦。

3.2 扫描与去抖：把物理抖动过滤干净

按键的物理抖动脉冲一般在 1~10ms，表现为按下瞬间电平上下跳动。如果扫描到低电平就直接上报，一个按键动作里会发出多个报告，这是常见的「chatter」问题。常规做法是连续扫描确认，用一个与矩阵等尺寸的计数器数组：

static uint8_t debounce_cnt[ROW_COUNT][COL_COUNT]; static bool key_state[ROW_COUNT][COL_COUNT]; #define DEBOUNCE_THRESHOLD 2 // 连续 2 次扫描稳定才算状态改变 void matrix_scan(void) { for (int col = 0; col < COL_COUNT; col++) { nrf_gpio_pin_clear(col_pins[col]); // 当前列拉低 for (int row = 0; row < ROW_COUNT; row++) { bool pressed = (nrf_gpio_pin_read(row_pins[row]) == 0); bool old = key_state[row][col]; if (pressed == old) { debounce_cnt[row][col] = 0; } else { debounce_cnt[row][col]++; if (debounce_cnt[row][col] >= DEBOUNCE_THRESHOLD) { key_state[row][col] = pressed; debounce_cnt[row][col] = 0; } } } nrf_gpio_pin_set(col_pins[col]); // 恢复高，切下一列 } }

DEBOUNCE_THRESHOLD取 2 意味着一次状态变化需要连续两次扫描确认，扫描周期 1ms 时，总去抖时间约 3ms，手指完全感知不到，却能滤掉大部分机械触点抖动。建议把扫描放在定时器中断里，而不是放在while(1)主循环。主循环一旦被 GATT 事件或功耗处理占住，扫描间隔就会漂移，去抖效果直接失真，按键偶发重复也是这么来的。

3.3 发送 HID 报告：从按键事件到 GATT 通知

扫描得到key_state后，下一步是把键位映射成 HID usage 并打包成报告发出去。nRF52832 发送通知的核心是sd_ble_gatts_hvx，对应输入报告特征值：

static void send_keyboard_report(uint8_t modifiers, uint8_t *keycodes, uint8_t key_count) { uint8_t report[8] = {0}; report[0] = modifiers; memcpy(&report[2], keycodes, key_count); uint16_t len = sizeof(report); ble_gatts_hvx_params_t hvx_params; memset(&hvx_params, 0, sizeof(hvx_params)); hvx_params.handle = m_hids.input_report_handles[0].value_handle; hvx_params.type = BLE_GATT_HVX_NOTIFICATION; hvx_params.p_data = report; hvx_params.p_len = &len; uint32_t err_code = sd_ble_gatts_hvx(m_conn_handle, &hvx_params); if (err_code != NRF_SUCCESS) { // 常见原因：对端未使能通知，或连接已断开 NRF_LOG_INFO("hvx send failed: 0x%x", err_code); } }

这里有个必须注意的前置条件：发送前主机要往 CCCD 特征写 0x0001 使能通知。主机是 PC/iOS 时，系统在连接建立后会自动使能；如果拿 nRF Connect 手动测试，要先进 HID Service 使能 Input Report 的 Notify，否则hvx返回NRF_ERROR_INVALID_STATE。报告里的modifiers对应 Ctrl/Shift 等修饰键，keycodes是要发送的有效按键 usage，最多 6 键，超过 6 键时只能按优先级取前 6 个，这是标准键盘协议的限制。

提示：如果对端一直没使能 CCCD，先检查特征属性的 notify 位有没有在注册时打开，属性位缺失时主机根本找不到可用的通知通道。

4. 编译烧录与验证：从 SDK 环境到 nRF Connect 抓包

4.1 工程结构与三种构建方式

展开工程以后是标准的 Nordic SDK 应用结构：nRF52832 主应用、SoftDevice（s132）、板级配置和sdk_config.h。构建方式我平常用命令行 Makefile，方便在 CI 里复现，也可以直接用 Keil 或 SEGGER Embedded Studio 打开工程。

# 需要先设置 nRF5_SDK 环境变量指向 SDK 根目录 make -j4 NRF52832_XXAA=1 SOFTDEVICE=s132 # 将 softdevice 和应用固件合并后一次性烧录 mergehex -m $(NRF5_SDK)/components/softdevice/s132/hex/s132_nrf52_*.hex \ _build/nrf52832_xxaa.hex -o combined.hex nrfjprog --program combined.hex --chiperase nrfjprog --reset

mergehex合并的顺序无所谓，但nrfjprog带--chiperase时整片会被擦净，SoftDevice、应用和 UICR 会一起写入。如果你习惯 IDE，Makefile 和 IDE 工程的差异主要在于预定义宏和优化选项，功能行为基本一致。烧完先用 nRF Connect 看一眼广播名，能看到 "NRF52 Keyboard" 说明 SoftDevice 和应用都活着。

4.2 sdk_config.h 里的关键开关

nRF5 SDK 的模块开关都在sdk_config.h里，它决定协议栈、定时器、日志和功耗模块是否编进固件。一个常规键盘工程至少要有：

// 协议栈与 GATT 配置 #define NRF_SDH_ENABLED 1 #define NRF_SDH_BLE_ENABLED 1 #define NRF_SDH_BLE_GATT_MAX_MTU_SIZE 247 // 允许更大 MTU，扩展报告长度 // HID 模块 #define BLE_HIDS_ENABLED 1 // 定时器，键盘扫描和广播调度都靠它 #define APP_TIMER_ENABLED 1 #define NRFX_RTC_ENABLED 1

MTU 247 是 s132 可支持的最大值。如果报告不需要超过 20 字节，用默认的 23 就行，开大 MTU 本身不增加多少功耗。BLE_HIDS_ENABLED对应 ble_hids 模块，漏掉会在链接阶段出现 undefined reference。APP_TIMER和NRFX_RTC是配套的，很多「按键偶尔失效」的案例其实是定时器没起来，扫描任务压根没被调度。

4.3 用 nRF Connect 验证 HID 键盘活着

固件烧好后的第一件事不是开记事本打字，而是用 nRF Connect 确认协议层。手机装 nRF Connect，扫描到设备后进入服务列表，你会看到标准 HID Service（0x1812）：

1. 在 HID Service 点开 Report Map 特征，读出的数据应该和report_map_data一致；
2. 找 Input Report 特征，使能 Notify；
3. 在另一端按任意键，观察 Input Report 通知里的字节流变化；
4. 查看连接参数，确认连接间隔在 7.5~15ms 区间，而不是 30ms 以上。

如果 Report Map 读出来是空的，多半是描述符没正确写进 GATT 特征；如果连接参数显示 30ms 以上，说明连接参数更新没生效，回到连接协商那条路径排查。这一步排查的都是协议栈行为，和按键映射无关，先过了再进系统层测试。

4.4 用 HID 助手类工具做系统侧按键验证

协议层通了还不代表系统层面能用。Windows 上连接后直接用记事本验证最直观，但想看具体 usage 值，可以用 HID 助手这类工具。这类工具在 Host 端解析 Report Map，实时显示 Usage Page、键码值和同步状态。开两个窗口对照：一边看 HID 助手解析出的键值，一边按键盘，两边一一对上，说明固件到系统输入栈的链路是通的。真机多系统测试时，iOS 和 Android 的差异主要在配对绑定流程，Windows 更关注报告描述符是否规范，这些在下一章会逐项展开。

5. 避坑与排查：五类高频问题的现象、根因与处理

5.1 配对成功后频繁断开

现象：手机或 PC 配对成功，十几秒后自动断开，重连又要重新配对。

原因：多半是连接参数更新请求被主机拒绝，从机一直用默认连接间隔，主机又用低功耗策略拉长间隔，最终触发连接超时；另一种情况是绑定信息没保存，每次重连都走完整配对流程。

处理：在连接事件里主动发起连接参数更新，并把安全模式配成带绑定的模式：

ble_gap_conn_params_t conn_params = { .min_conn_interval = 6, // 7.5ms .max_conn_interval = 12, // 15ms .slave_latency = 0, .conn_sup_timeout = 400, // 4000ms }; sd_ble_gap_conn_param_update(m_conn_handle, &conn_params);

绑定确认：连接后调用sd_ble_gap_sec_params_reply，传入SEC_PARAM_BOND标志；重启后从 Flash 恢复绑定数据，而不是每次重新生成。真机上如果发现断开时间点固定在一个整秒边界，基本可以锁定是连接超时而不是信号问题。

5.2 按键延迟明显，偶尔吞键

现象：快速连续按键时，第三个或第四个键丢失，或者键序颠倒。

原因：两层。一是按键扫描放在主循环，被其他流程抢占；二是发送报告失败后没有重试机制，丢一帧就少一个字符。

处理：扫描固定到APP_TIMER回调，比如 1ms 周期；发送报告用一个缓冲区存待发事件，连接事件触发后再取最新状态发送。快速连按场景尽量保证每次扫描完成都立刻进队列，而不是「扫描-发送」同步处理。这个坑我踩过一次，当时按键事件和发送耦合在一起，后来把接收和发送解耦，问题一次解决。血泪经验：BLE 外设的按键扫描必须和协议栈事件解耦，否则任何一条链路的阻塞都会表现为丢键。

5.3 按 A 出 B，或组合键错乱

现象：单键测试时键值对不上，固定错位。

原因：九成是 Report Map 和发送数据的字节布局没对齐。比如描述符里第二个字节声明为 Constant，发送代码却往偏移 1 之前填了内容，系统按描述符解析出的 Usage 就会整体位移。另一个常见原因是矩阵 row/col 引脚接错，程序以为按下的键位映射到了别的 usage。

处理：先从源头排查映射表，用测试模式把每个物理键位置打印出来，比较真实按下的 row/col 与 keycodes 的对应关系；再逐字节核对 Report Map。建议两步走：先把矩阵扫到的位置直接映射成 A 键测试，确认硬件通路没问题；再换用修改后的 report_map 烧进去验证系统解析。两步分工，问题立刻定位。

5.4 待机功耗高得离谱

现象：纽扣电池版本一晚上掉电明显，静态电流有几 mA。

原因：未使用的 GPIO 处于浮空输入状态，电平不确定会反复翻转；广播间隔过密、System ON 模式没真正进入、RTC 唤醒太频繁也有贡献。

处理：所有不用的 GPIO 配置为NRF_GPIO_PIN_INPUT_DISCONNECT，断开连接后进入 System ON 睡眠，只留 RTC 和按键唤醒，广播间隔调到 100ms 以上。建议用 Power Profiler Kit 实测，分开看单次广播电流和按键唤醒电流，别靠万用表量平均值，BLE 的瞬态电流会让万用表读数严重失真。这一点最容易翻车，真正进了睡眠状态和只睡了外设，功耗能差两个数量级。

5.5 烧录后进不了 DFU 或升级中途翻车

现象：固件能跑，但按快捷键进不了 bootloader，或者 DFU 传输中途掉线。

原因：常见是 bootloader 入口按键复用了矩阵中的某个 GPIO，矩阵初始化把该引脚拉低，bootloader 检测到的一直是按下状态；另外 secure bootloader 版本与 SoftDevice 不匹配也会中止升级。

处理：检查按键入口在启动阶段必须保持稳定电平，矩阵里冲突的引脚加二极管隔离或改独立 GPIO；版本不匹配时用nrfjprog --recover整片擦除后重新烧 bootloader。多数翻车都是引脚冲突和版本错配，跟协议栈本身没关系，先把这两项排除再去看 bootloader 日志，能少走弯路。

6. 进阶：把报告延迟压进 20ms 的验证方法

6.1 先算延迟账，再动手调

键盘从物理按下到字符上屏，链路是：矩阵扫描（约 1ms）→ 去抖确认（约 3ms）→ GATT 通知排队（等待当前连接事件）→ 蓝牙空口传输（7.5ms 间隔最大 7.5ms）→ 主机处理上报。最坏情况约 15~20ms，这是人体无感的边界。如果去抖阈值再加大、连接间隔又用 30ms，延迟直接到 40ms 以上，就会觉得键盘发粘。我一般把扫描周期锁在 1ms、去抖阈值取 2、连接间隔 7.5ms，这套组合不做特殊优化就能稳定在 20ms 以内。

6.2 Wireshark 只抓指定 BLE 设备的 HID 报告

无线链路最终验证阶段，我依赖 Wireshark 只抓指定 BLE 设备，而不是靠感觉打字测试。前提是 USB 蓝牙适配器能被 Wireshark 接管。抓包建议用这样的过滤条件：

bluetooth.addr == aa:bb:cc:11:22:33 && btatt.opcode == 0x1b

btatt.opcode 0x1b是 Handle Value Notification，对应 HID Input Report 的通知帧。把过滤条件里的地址换成你键盘的蓝牙 MAC，就能把该设备的所有 HID 报告单拎出来看。这样抓出来的 report 字节流和触发按键一一对应，能直接发现发送 A 键码字节、系统却解析成 B 键这类 app 层可能被掩盖的错位。Wireshark 抓包要求硬件兼容，nRF52832 开发板本身也可以做 sniffer，成本更低但配置稍繁琐。

6.3 每次改动固件都要过的验收关

我习惯把验证固化成三步：先用 HID 助手看单键 usage 映射，再用 Wireshark 对比通知字节流，最后在三个系统上各做一轮连接断开压力测试。调试去抖参数时，最有效的工具反而是快速打字和自动化按键测试脚本，二者结合能暴露大多数固件层问题。也不要忘记在功耗分析仪上复测静态电流，这是蓝牙项目做省电的最后一道关。这次的工程刚入手时，我把烧录方案、参数协商和 HID 描述符核对走完整套，才敢把它定义成可复现的基线。从那以后我每次改键位映射，都强制回到这套 Wireshark 抓包流程，不看到 Report 帧里的 usage 码对上就不往下走——等上板再发现问题，那才是真的后悔药都找不着。希望帮到你。

本文还有配套的精品资源，点击获取