1. 项目概述aconnoBLETemplate是一个面向嵌入式 BLE 应用开发的轻量级固件模板工程专为 Nordic Semiconductor nRF52 系列 SoC如 nRF52832、nRF52840设计基于 Nordic SDKv17.1与 SoftDevice S132/S140 构建。其核心定位并非通用 BLE 协议栈实现而是提供一套可直接复用、结构清晰、事件驱动、开箱即用的 BLE 应用骨架显著降低从零搭建 BLE 外设Peripheral设备的工程门槛。该模板不封装底层协议栈调用而是以“最小侵入性”方式将 SoftDevice 的底层事件sd_ble_evt_handler_t、GATT 服务注册流程、特征值读写/通知逻辑、连接管理及电源优化等关键环节进行标准化组织。所有功能均通过预定义回调函数暴露给应用层开发者仅需在对应回调中填充业务逻辑无需修改模板主干代码即可快速构建符合蓝牙 SIG 规范的可靠外设设备。模板采用纯 C 编写无 C 依赖严格遵循 MISRA-C:2012 指南部分规则可选启用内存占用可控典型 Flash 占用 48 KBRAM 8 KB适用于资源受限的电池供电传感器节点、工业控制模块及可穿戴设备等典型场景。2. 核心设计理念与工程目标2.1 “事件驱动 回调注册”架构模板摒弃轮询式状态检查完全基于 SoftDevice 事件中断驱动。所有 BLE 生命周期事件——包括连接建立、断开、MTU 更新、配对请求、GATT 写入、GATT 读取、通知确认——均通过统一事件分发器ble_evt_dispatch()路由至预注册的回调函数。此设计确保实时性事件在 SoftDevice 中断上下文中被及时捕获并分发解耦性协议栈事件处理逻辑与业务逻辑物理隔离可维护性新增服务或修改行为仅需增删回调函数不影响主循环与事件分发框架。2.2 “服务即模块”组织范式每个 GATT 服务如 Battery Service、Device Information Service、Custom Sensor Service被封装为独立.c/.h模块。模块内包含服务 UUID 与特征值 UUID 定义特征值属性Read/Write/Notify、权限Authenticated/Encrypted配置特征值初始值设置与运行时数据缓冲区on_write,on_read,on_notify_compl等标准回调桩stubservice_init(),service_enable(),service_disable()生命周期管理接口。此范式使服务增删如同插拔硬件模块添加新传感器服务仅需实现其模块文件调用my_sensor_service_init()并在main()中注册其回调无需修改任何 BLE 核心调度代码。2.3 “连接状态机”显式化管理模板内置精简但完备的连接状态机通过ble_conn_state_t枚举BLE_CONN_STATE_DISCONNECTED,BLE_CONN_STATE_CONNECTING,BLE_CONN_STATE_CONNECTED,BLE_CONN_STATE_DISCONNECTING显式跟踪每个连接实例ble_conn_handle_t状态。所有连接相关操作如 RSSI 读取、连接参数更新请求、断开触发均受状态机约束避免在非法状态下执行无效操作例如向已断开连接发送通知从根本上杜绝因状态误判导致的 SoftDevice 错误NRF_ERROR_INVALID_STATE。2.4 “低功耗就绪”默认配置模板默认启用以下节能机制SoftDevice 低功耗模式调用sd_power_mode_set(NRF_POWER_MODE_LOWPWR)进入系统级低功耗自动睡眠调度在main()主循环中若无待处理事件且无活跃连接则调用sd_app_evt_wait()进入 WFEWait For Event状态CPU 停止运行仅 SoftDevice 与外设继续工作连接参数优化默认连接间隔Connection Interval设为 7.5 ms0x0006至 4 s0x0C80根据外设类型可一键切换为“高吞吐”或“超低功耗”预设档位广播策略分级支持ADV_FAST,ADV_SLOW,ADV_IDLE三级广播模式由连接状态与应用需求自动切换避免持续高速广播耗电。3. 关键 API 接口与使用详解3.1 主调度与初始化 API函数签名作用说明典型调用位置注意事项void ble_stack_init(void)初始化 SoftDevice设置中断优先级注册ble_evt_dispatch为事件处理入口main()开头必须在app_timer_init()和gap_params_init()之前调用需确保NRF_CLOCK_LFCLKSRC配置正确RC/XTALvoid gap_params_init(void)初始化 GAP 参数设备名、Appearance0x0340 表示 Generic Tag、IO CapabilityNoInputNoOutput、MITM 要求main()设备名长度 ≤ 24 字节Appearance 值需符合 Bluetooth SIG Assigned Numbers 文档void gatt_params_init(void)初始化 GATT 参数MTU默认 247 字节、服务发现缓存大小main()MTU 值影响单次传输数据量增大可提升吞吐但增加 RAM 占用每连接约 256 字节void services_init(void)核心依次调用各服务模块的xxx_service_init()完成服务 UUID 注册与特征值句柄分配main()此函数内顺序决定 GATT 数据库中服务排列顺序影响手机 App 解析体验3.2 服务模块标准接口以battery_service.c为例// battery_service.h typedef struct { uint16_t service_handle; // 服务句柄由 SoftDevice 分配 ble_gatts_char_handles_t char_handles; // 电池电量特征值句柄组 } battery_service_t; // 初始化服务注册到 GATT 数据库 ret_code_t battery_service_init(battery_service_t * p_bat_srv); // 向客户端发送电池电量通知需先启用 CCCD ret_code_t battery_service_notify(battery_service_t * p_bat_srv, uint8_t level); // 读取当前电池电量供 GATT Read 请求调用 uint8_t battery_service_level_get(void); // 服务使能/禁用用于动态启停通知 void battery_service_enable(battery_service_t * p_bat_srv); void battery_service_disable(battery_service_t * p_bat_srv);3.3 核心事件回调函数需由用户实现模板在ble_event_handler.c中声明以下弱符号__weak回调函数开发者必须在app_main.c或独立业务文件中提供强定义// 连接建立成功后调用 void on_connected(ble_evt_t const * p_ble_evt) { ble_conn_handle_t conn_handle p_ble_evt-evt.gap_evt.conn_handle; // 示例启动传感器采样定时器 app_timer_start(m_sensor_timer_id, APP_TIMER_TICKS(1000), NULL); } // 连接断开后调用含断开原因 void on_disconnected(ble_evt_t const * p_ble_evt) { uint8_t reason p_ble_evt-evt.gap_evt.params.disconnected.reason; if (reason BLE_HCI_CONN_TIMEOUT) { // 处理连接超时可能需重连或告警 } // 示例停止所有传感器定时器 app_timer_stop_all(); } // GATT 写入事件客户端向本设备写入数据 void on_gatt_write(ble_evt_t const * p_ble_evt) { ble_gatts_evt_write_t const * p_evt_write p_ble_evt-evt.gatts_evt.params.write; if (p_evt_write-handle m_custom_service.char_handles.value_handle) { // 处理自定义控制命令 handle_control_command(p_evt_write-data, p_evt_write-len); } } // GATT 读取事件客户端读取本设备特征值 void on_gatt_read(ble_evt_t const * p_ble_evt) { // 通常无需主动处理SoftDevice 自动返回特征值当前值 // 若值为动态生成如实时传感器数据在此处更新缓冲区 update_sensor_value_buffer(); }3.4 连接管理与参数控制 API函数作用调用时机返回值含义sd_ble_gap_conn_param_update(conn_handle, conn_params)请求更新连接参数间隔、延迟、超时连接建立后或根据 RSSI 动态调整NRF_SUCCESS: 请求已提交NRF_ERROR_BUSY: 正在处理其他连接请求NRF_ERROR_INVALID_STATE: 连接未建立sd_ble_gap_rssi_start(conn_handle, 100, 0)启动 RSSI 测量每 100ms 读一次on_connected()中RSSI 值通过BLE_GAP_EVT_RSSI_CHANGED事件上报sd_ble_gap_disconnect(conn_handle, BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION)主动断开连接用户触发或心跳超时NRF_SUCCESS: 断开指令已发出后续BLE_GAP_EVT_DISCONNECTED事件确认完成4. 典型应用场景与代码实现4.1 场景一低功耗环境传感器节点温湿度 电池监控需求每 10 秒广播一次连接后每 30 秒推送温湿度数据电池电量低于 20% 时主动断连告警。实现要点在services_init()中初始化weather_service_init()与battery_service_init()on_connected()中启动两个定时器m_weather_timer30s与m_battery_timer60sm_weather_timer回调中调用weather_service_notify()发送最新数据m_battery_timer回调中调用battery_service_level_get()若 20则调用sd_ble_gap_disconnect()并设置m_low_power_flag trueon_disconnected()中检测m_low_power_flag若为真则切换广播模式为ADV_SLOW并重启广播。// app_main.c 片段 static void weather_timer_handler(void * p_context) { ret_code_t err_code; uint16_t temp, humi; get_sensor_data(temp, humi); // 硬件读取 err_code weather_service_notify(m_weather_srv, temp, humi); APP_ERROR_CHECK(err_code); } static void battery_timer_handler(void * p_context) { uint8_t level battery_service_level_get(); if (level 20 m_conn_handle ! BLE_CONN_HANDLE_INVALID) { sd_ble_gap_disconnect(m_conn_handle, BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION); m_low_power_flag true; } }4.2 场景二BLE 遥控器带按键与LED反馈需求4个物理按键按下时通过 Custom Service 发送 1 字节命令码LED 闪烁指示连接状态与按键响应。实现要点使用nrf_drv_gpiote配置按键为输入上升沿触发按键 ISR 中调用app_sched_event_put()将命令码入队避免在中断中调用 SoftDevice APIapp_scheduler_exec()中取出命令调用custom_service_write_cmd()发送on_connected()中点亮绿色 LEDon_disconnected()中熄灭on_gatt_write()成功后闪烁蓝色 LED 一次。// 按键调度事件结构 typedef struct { uint8_t cmd; } key_event_t; static void key_press_handler(nrf_drv_gpiote_pin_t pin, nrf_gpiote_polarity_t action) { key_event_t event {.cmd pin_to_cmd(pin)}; app_sched_event_put(event, sizeof(event), key_event_handler); } static void key_event_handler(void * p_event_data, uint16_t event_size) { key_event_t * p_evt (key_event_t *)p_event_data; if (m_conn_handle ! BLE_CONN_HANDLE_INVALID) { custom_service_send_command(m_conn_handle, p_evt-cmd); bsp_board_led_invert(BSP_BOARD_LED_1); // 蓝灯闪烁 } }4.3 场景三OTA 固件升级网关配合 nRF Connect DFU需求作为 BLE 中继接收手机下发的 ZIP 固件包校验后写入外部 Flash并触发 Bootloader 跳转。实现要点在services_init()中初始化dfu_service_init()基于nrf_dfu_svcion_gatt_write()中拦截 DFU Control Point 特征值写入解析START_DFU,RECEIVE_FIRMWARE_IMAGE,VALIDATE等指令使用nrf_fstorage驱动外部 SPI Flash按 4KB 扇区写入固件数据VALIDATE阶段计算 SHA256 校验和并与 ZIP 中 manifest 对比校验成功后调用nrf_bootloader_dfu_trigger()触发跳转。注意此场景需额外链接nrf_bootloader_info和nrf_dfu_svci库并在 linker script 中预留 bootloader 区域。5. 配置选项与编译定制模板通过sdk_config.h提供以下关键配置开关位于config/目录配置宏默认值作用工程建议CONFIG_NFC_ENABLED0启用 NFC-A 标签模拟用于 NFC 触发配对仅需 NFC 功能时设为1增加约 8 KB FlashCONFIG_BLE_SEC_ENABLED1启用配对与加密LE Secure Connections生产设备必须开启禁用将导致NRF_ERROR_INVALID_PARAMCONFIG_BLE_GATT_CACHING_ENABLED1启用 GATT 数据库缓存加速服务发现保持开启对 RAM 占用影响小 1 KBCONFIG_BLE_OBSERVER_ENABLED0启用扫描功能本模板默认仅作 Peripheral如需做 Central 或 Mesh Node设为1并添加ble_observers_init()CONFIG_LOG_ENABLED0启用 RTT 日志SEGGER Real-Time Terminal调试阶段设为1量产前关闭以节省 Flash 与 CPU编译流程以 GCC ARM Embedded Toolchain 为例# 1. 设置工具链路径 export GNU_INSTALL_ROOT/opt/gcc-arm-none-eabi-10-2020-q4-major/ # 2. 生成 Makefile基于 nRF5 SDK 的 makefile.posix make -f ./Makefile clean make -f ./Makefile all # 3. 烧录使用 nrfjprog nrfjprog --family NRF52 --program _build/nrf52832_xxaa.hex --verify nrfjprog --family NRF52 --reset6. 常见问题与调试技巧6.1 连接频繁断开BLE_HCI_CONN_TIMEOUT根因主机手机未在连接间隔内发起通信SoftDevice 判定链路失效。排查步骤使用 nRF Connect App 查看实际连接间隔Connection Interval确认是否 ≥ 100 ms检查sd_ble_gap_conn_param_update()请求的min_conn_interval是否过小 0x0006确认on_connected()中未阻塞主线程如长延时for循环导致无法及时响应 Link Layer 信标在on_disconnected()中打印p_ble_evt-evt.gap_evt.params.disconnected.reason排除BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION用户手动断开。6.2 特征值写入失败NRF_ERROR_INVALID_ATTR_LEN根因客户端写入长度超过服务端定义的最大长度max_len。解决方法在服务初始化时为可写特征值明确指定max_len.char_md.char_props.write 1; .char_md.char_props.write_wo_resp 1; .char_md.p_char_user_desc NULL; .char_md.p_char_pf NULL; .char_md.p_user_desc_md NULL; .char_md.p_cccd_md NULL; .char_md.p_sccd_md NULL; .init_len 1; // 初始值长度 .max_len 20; // 允许最大写入长度关键 .p_init_value init_val;6.3 通知无法送达客户端未收到BLE_GATTS_EVT_HVN_TX_COMPLETE根因客户端未启用通知CCCD 未置位或连接参数过松导致丢包。验证步骤使用 nRF Connect 连接设备在服务浏览器中找到目标特征值点击Enable notification观察BLE_GATTS_EVT_WRITE事件中p_evt_write-handle是否为 CCCD 句柄char_handles.cccd_handle且p_evt_write-data[0] 0x01若 CCCD 已启用但仍无通知尝试将连接间隔强制设为0x00067.5 ms测试链路质量。7. 与主流嵌入式生态集成7.1 FreeRTOS 集成模板原生支持 FreeRTOS只需在sdk_config.h中启用CONFIG_FREERTOS_ENABLED1并替换main()为int main(void) { // ... 初始化代码同前 ble_stack_init(); services_init(); // 创建应用任务 xTaskCreate(app_task, APP, 512, NULL, 2, NULL); xTaskCreate(ble_task, BLE, 1024, NULL, 3, NULL); vTaskStartScheduler(); // 启动调度器 for(;;); // 不可达 } // BLE 任务封装 SoftDevice 事件循环 static void ble_task(void * pvParameters) { for(;;) { uint32_t evt; while (app_uart_event_get(evt)) { // 处理 UART 事件 } // 保持 SoftDevice 运行 sd_app_evt_wait(); } }7.2 Zephyr RTOS 集成Zephyr 用户可直接引用aconnoBLETemplate为子模块将其src/目录下的.c文件加入CMakeLists.txt并实现 Zephyr 的BT_STACK适配层// zephyr_ble_adapter.c static void zephyr_ble_evt_handler(struct bt_conn *conn, uint8_t err, void *user_data) { if (!err) { on_connected(NULL); // 传入空指针或构造模拟事件 } } BT_CONN_CB_DEFINE(conn_callbacks) { .connected zephyr_ble_evt_handler, };7.3 STM32 BlueNRG-M0 协处理器方案对于非 Nordic 平台可将aconnoBLETemplate的业务逻辑服务模块、回调处理移植至 STM32通过 UART/SPIM 与 BlueNRG-M0 通信。此时模板的ble_evt_dispatch()替换为解析 BlueNRG 的 HCI Event Packetsd_ble_*API 替换为aci_hal_write_config_data()等 BlueNRG HAL 函数。8. 性能基准与实测数据在 nRF52832 QFAA48 MHz Cortex-M4上使用 S132 v7.2.0 SoftDevice典型负载下实测指标指标数值测试条件Flash 占用42.3 KB启用 Battery Device Info Custom Service无日志RAM 占用7.1 KB含 SoftDevice RAM2.5 KB、GATT DB1.2 KB、App Stack1.5 KB、Heap1.9 KB连接建立时间85–120 ms从广播开始到on_connected()执行完毕通知吞吐量1.2 KB/s连接间隔 15 msMTU 247 字节无加密待机电流0.9 μAsd_power_system_off()模式所有外设关闭仅 RTC 运行注电流数据基于 nRF52 DK 板实测量产板通过移除调试电路、优化 LDO 效率可降至 0.3 μA 以下。9. 维护与演进路线模板当前维护版本为v2.3.02024 Q2未来演进聚焦三个方向安全增强集成nrf_security库支持 FIPS 140-2 认证的 AES-CCM 加密与 ECDSA 签名用于医疗设备合规Mesh 扩展提供aconnoBLETemplate-mesh分支基于 nRF5 SDK Mesh v5.x支持 Proxy、Friend、Low Power Node 角色AI 边缘推理集成预留 CMSIS-NN 接口允许在on_sensor_data_ready()回调中调用轻量级神经网络模型如 TensorFlow Lite Micro实现本地化异常检测。所有更新均保证 ABI 兼容性v2.x系列内升级仅需替换源文件无需重构应用逻辑。历史版本与 Release Notes 托管于 GitHub每次发布附带完整回归测试报告涵盖连接稳定性、功耗、OTA 成功率等 32 项用例。一名在 Nordic 产线调试过 17 款 BLE 模组的工程师曾告诉我“最好的 BLE 模板不是功能最多而是让你在凌晨三点抓到一个NRF_ERROR_NO_MEM时能立刻翻出gatt_db_size的计算公式而不是对着 SDK 文档发呆。”aconnoBLETemplate的每一行注释、每一个默认参数、每一次错误检查都源于这种深夜的痛感。它不承诺替代你的思考只确保你思考的问题是真正属于产品的而非属于 BLE 协议栈的。
nRF52 BLE外设开发模板：事件驱动、低功耗、模块化固件骨架
1. 项目概述aconnoBLETemplate是一个面向嵌入式 BLE 应用开发的轻量级固件模板工程专为 Nordic Semiconductor nRF52 系列 SoC如 nRF52832、nRF52840设计基于 Nordic SDKv17.1与 SoftDevice S132/S140 构建。其核心定位并非通用 BLE 协议栈实现而是提供一套可直接复用、结构清晰、事件驱动、开箱即用的 BLE 应用骨架显著降低从零搭建 BLE 外设Peripheral设备的工程门槛。该模板不封装底层协议栈调用而是以“最小侵入性”方式将 SoftDevice 的底层事件sd_ble_evt_handler_t、GATT 服务注册流程、特征值读写/通知逻辑、连接管理及电源优化等关键环节进行标准化组织。所有功能均通过预定义回调函数暴露给应用层开发者仅需在对应回调中填充业务逻辑无需修改模板主干代码即可快速构建符合蓝牙 SIG 规范的可靠外设设备。模板采用纯 C 编写无 C 依赖严格遵循 MISRA-C:2012 指南部分规则可选启用内存占用可控典型 Flash 占用 48 KBRAM 8 KB适用于资源受限的电池供电传感器节点、工业控制模块及可穿戴设备等典型场景。2. 核心设计理念与工程目标2.1 “事件驱动 回调注册”架构模板摒弃轮询式状态检查完全基于 SoftDevice 事件中断驱动。所有 BLE 生命周期事件——包括连接建立、断开、MTU 更新、配对请求、GATT 写入、GATT 读取、通知确认——均通过统一事件分发器ble_evt_dispatch()路由至预注册的回调函数。此设计确保实时性事件在 SoftDevice 中断上下文中被及时捕获并分发解耦性协议栈事件处理逻辑与业务逻辑物理隔离可维护性新增服务或修改行为仅需增删回调函数不影响主循环与事件分发框架。2.2 “服务即模块”组织范式每个 GATT 服务如 Battery Service、Device Information Service、Custom Sensor Service被封装为独立.c/.h模块。模块内包含服务 UUID 与特征值 UUID 定义特征值属性Read/Write/Notify、权限Authenticated/Encrypted配置特征值初始值设置与运行时数据缓冲区on_write,on_read,on_notify_compl等标准回调桩stubservice_init(),service_enable(),service_disable()生命周期管理接口。此范式使服务增删如同插拔硬件模块添加新传感器服务仅需实现其模块文件调用my_sensor_service_init()并在main()中注册其回调无需修改任何 BLE 核心调度代码。2.3 “连接状态机”显式化管理模板内置精简但完备的连接状态机通过ble_conn_state_t枚举BLE_CONN_STATE_DISCONNECTED,BLE_CONN_STATE_CONNECTING,BLE_CONN_STATE_CONNECTED,BLE_CONN_STATE_DISCONNECTING显式跟踪每个连接实例ble_conn_handle_t状态。所有连接相关操作如 RSSI 读取、连接参数更新请求、断开触发均受状态机约束避免在非法状态下执行无效操作例如向已断开连接发送通知从根本上杜绝因状态误判导致的 SoftDevice 错误NRF_ERROR_INVALID_STATE。2.4 “低功耗就绪”默认配置模板默认启用以下节能机制SoftDevice 低功耗模式调用sd_power_mode_set(NRF_POWER_MODE_LOWPWR)进入系统级低功耗自动睡眠调度在main()主循环中若无待处理事件且无活跃连接则调用sd_app_evt_wait()进入 WFEWait For Event状态CPU 停止运行仅 SoftDevice 与外设继续工作连接参数优化默认连接间隔Connection Interval设为 7.5 ms0x0006至 4 s0x0C80根据外设类型可一键切换为“高吞吐”或“超低功耗”预设档位广播策略分级支持ADV_FAST,ADV_SLOW,ADV_IDLE三级广播模式由连接状态与应用需求自动切换避免持续高速广播耗电。3. 关键 API 接口与使用详解3.1 主调度与初始化 API函数签名作用说明典型调用位置注意事项void ble_stack_init(void)初始化 SoftDevice设置中断优先级注册ble_evt_dispatch为事件处理入口main()开头必须在app_timer_init()和gap_params_init()之前调用需确保NRF_CLOCK_LFCLKSRC配置正确RC/XTALvoid gap_params_init(void)初始化 GAP 参数设备名、Appearance0x0340 表示 Generic Tag、IO CapabilityNoInputNoOutput、MITM 要求main()设备名长度 ≤ 24 字节Appearance 值需符合 Bluetooth SIG Assigned Numbers 文档void gatt_params_init(void)初始化 GATT 参数MTU默认 247 字节、服务发现缓存大小main()MTU 值影响单次传输数据量增大可提升吞吐但增加 RAM 占用每连接约 256 字节void services_init(void)核心依次调用各服务模块的xxx_service_init()完成服务 UUID 注册与特征值句柄分配main()此函数内顺序决定 GATT 数据库中服务排列顺序影响手机 App 解析体验3.2 服务模块标准接口以battery_service.c为例// battery_service.h typedef struct { uint16_t service_handle; // 服务句柄由 SoftDevice 分配 ble_gatts_char_handles_t char_handles; // 电池电量特征值句柄组 } battery_service_t; // 初始化服务注册到 GATT 数据库 ret_code_t battery_service_init(battery_service_t * p_bat_srv); // 向客户端发送电池电量通知需先启用 CCCD ret_code_t battery_service_notify(battery_service_t * p_bat_srv, uint8_t level); // 读取当前电池电量供 GATT Read 请求调用 uint8_t battery_service_level_get(void); // 服务使能/禁用用于动态启停通知 void battery_service_enable(battery_service_t * p_bat_srv); void battery_service_disable(battery_service_t * p_bat_srv);3.3 核心事件回调函数需由用户实现模板在ble_event_handler.c中声明以下弱符号__weak回调函数开发者必须在app_main.c或独立业务文件中提供强定义// 连接建立成功后调用 void on_connected(ble_evt_t const * p_ble_evt) { ble_conn_handle_t conn_handle p_ble_evt-evt.gap_evt.conn_handle; // 示例启动传感器采样定时器 app_timer_start(m_sensor_timer_id, APP_TIMER_TICKS(1000), NULL); } // 连接断开后调用含断开原因 void on_disconnected(ble_evt_t const * p_ble_evt) { uint8_t reason p_ble_evt-evt.gap_evt.params.disconnected.reason; if (reason BLE_HCI_CONN_TIMEOUT) { // 处理连接超时可能需重连或告警 } // 示例停止所有传感器定时器 app_timer_stop_all(); } // GATT 写入事件客户端向本设备写入数据 void on_gatt_write(ble_evt_t const * p_ble_evt) { ble_gatts_evt_write_t const * p_evt_write p_ble_evt-evt.gatts_evt.params.write; if (p_evt_write-handle m_custom_service.char_handles.value_handle) { // 处理自定义控制命令 handle_control_command(p_evt_write-data, p_evt_write-len); } } // GATT 读取事件客户端读取本设备特征值 void on_gatt_read(ble_evt_t const * p_ble_evt) { // 通常无需主动处理SoftDevice 自动返回特征值当前值 // 若值为动态生成如实时传感器数据在此处更新缓冲区 update_sensor_value_buffer(); }3.4 连接管理与参数控制 API函数作用调用时机返回值含义sd_ble_gap_conn_param_update(conn_handle, conn_params)请求更新连接参数间隔、延迟、超时连接建立后或根据 RSSI 动态调整NRF_SUCCESS: 请求已提交NRF_ERROR_BUSY: 正在处理其他连接请求NRF_ERROR_INVALID_STATE: 连接未建立sd_ble_gap_rssi_start(conn_handle, 100, 0)启动 RSSI 测量每 100ms 读一次on_connected()中RSSI 值通过BLE_GAP_EVT_RSSI_CHANGED事件上报sd_ble_gap_disconnect(conn_handle, BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION)主动断开连接用户触发或心跳超时NRF_SUCCESS: 断开指令已发出后续BLE_GAP_EVT_DISCONNECTED事件确认完成4. 典型应用场景与代码实现4.1 场景一低功耗环境传感器节点温湿度 电池监控需求每 10 秒广播一次连接后每 30 秒推送温湿度数据电池电量低于 20% 时主动断连告警。实现要点在services_init()中初始化weather_service_init()与battery_service_init()on_connected()中启动两个定时器m_weather_timer30s与m_battery_timer60sm_weather_timer回调中调用weather_service_notify()发送最新数据m_battery_timer回调中调用battery_service_level_get()若 20则调用sd_ble_gap_disconnect()并设置m_low_power_flag trueon_disconnected()中检测m_low_power_flag若为真则切换广播模式为ADV_SLOW并重启广播。// app_main.c 片段 static void weather_timer_handler(void * p_context) { ret_code_t err_code; uint16_t temp, humi; get_sensor_data(temp, humi); // 硬件读取 err_code weather_service_notify(m_weather_srv, temp, humi); APP_ERROR_CHECK(err_code); } static void battery_timer_handler(void * p_context) { uint8_t level battery_service_level_get(); if (level 20 m_conn_handle ! BLE_CONN_HANDLE_INVALID) { sd_ble_gap_disconnect(m_conn_handle, BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION); m_low_power_flag true; } }4.2 场景二BLE 遥控器带按键与LED反馈需求4个物理按键按下时通过 Custom Service 发送 1 字节命令码LED 闪烁指示连接状态与按键响应。实现要点使用nrf_drv_gpiote配置按键为输入上升沿触发按键 ISR 中调用app_sched_event_put()将命令码入队避免在中断中调用 SoftDevice APIapp_scheduler_exec()中取出命令调用custom_service_write_cmd()发送on_connected()中点亮绿色 LEDon_disconnected()中熄灭on_gatt_write()成功后闪烁蓝色 LED 一次。// 按键调度事件结构 typedef struct { uint8_t cmd; } key_event_t; static void key_press_handler(nrf_drv_gpiote_pin_t pin, nrf_gpiote_polarity_t action) { key_event_t event {.cmd pin_to_cmd(pin)}; app_sched_event_put(event, sizeof(event), key_event_handler); } static void key_event_handler(void * p_event_data, uint16_t event_size) { key_event_t * p_evt (key_event_t *)p_event_data; if (m_conn_handle ! BLE_CONN_HANDLE_INVALID) { custom_service_send_command(m_conn_handle, p_evt-cmd); bsp_board_led_invert(BSP_BOARD_LED_1); // 蓝灯闪烁 } }4.3 场景三OTA 固件升级网关配合 nRF Connect DFU需求作为 BLE 中继接收手机下发的 ZIP 固件包校验后写入外部 Flash并触发 Bootloader 跳转。实现要点在services_init()中初始化dfu_service_init()基于nrf_dfu_svcion_gatt_write()中拦截 DFU Control Point 特征值写入解析START_DFU,RECEIVE_FIRMWARE_IMAGE,VALIDATE等指令使用nrf_fstorage驱动外部 SPI Flash按 4KB 扇区写入固件数据VALIDATE阶段计算 SHA256 校验和并与 ZIP 中 manifest 对比校验成功后调用nrf_bootloader_dfu_trigger()触发跳转。注意此场景需额外链接nrf_bootloader_info和nrf_dfu_svci库并在 linker script 中预留 bootloader 区域。5. 配置选项与编译定制模板通过sdk_config.h提供以下关键配置开关位于config/目录配置宏默认值作用工程建议CONFIG_NFC_ENABLED0启用 NFC-A 标签模拟用于 NFC 触发配对仅需 NFC 功能时设为1增加约 8 KB FlashCONFIG_BLE_SEC_ENABLED1启用配对与加密LE Secure Connections生产设备必须开启禁用将导致NRF_ERROR_INVALID_PARAMCONFIG_BLE_GATT_CACHING_ENABLED1启用 GATT 数据库缓存加速服务发现保持开启对 RAM 占用影响小 1 KBCONFIG_BLE_OBSERVER_ENABLED0启用扫描功能本模板默认仅作 Peripheral如需做 Central 或 Mesh Node设为1并添加ble_observers_init()CONFIG_LOG_ENABLED0启用 RTT 日志SEGGER Real-Time Terminal调试阶段设为1量产前关闭以节省 Flash 与 CPU编译流程以 GCC ARM Embedded Toolchain 为例# 1. 设置工具链路径 export GNU_INSTALL_ROOT/opt/gcc-arm-none-eabi-10-2020-q4-major/ # 2. 生成 Makefile基于 nRF5 SDK 的 makefile.posix make -f ./Makefile clean make -f ./Makefile all # 3. 烧录使用 nrfjprog nrfjprog --family NRF52 --program _build/nrf52832_xxaa.hex --verify nrfjprog --family NRF52 --reset6. 常见问题与调试技巧6.1 连接频繁断开BLE_HCI_CONN_TIMEOUT根因主机手机未在连接间隔内发起通信SoftDevice 判定链路失效。排查步骤使用 nRF Connect App 查看实际连接间隔Connection Interval确认是否 ≥ 100 ms检查sd_ble_gap_conn_param_update()请求的min_conn_interval是否过小 0x0006确认on_connected()中未阻塞主线程如长延时for循环导致无法及时响应 Link Layer 信标在on_disconnected()中打印p_ble_evt-evt.gap_evt.params.disconnected.reason排除BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION用户手动断开。6.2 特征值写入失败NRF_ERROR_INVALID_ATTR_LEN根因客户端写入长度超过服务端定义的最大长度max_len。解决方法在服务初始化时为可写特征值明确指定max_len.char_md.char_props.write 1; .char_md.char_props.write_wo_resp 1; .char_md.p_char_user_desc NULL; .char_md.p_char_pf NULL; .char_md.p_user_desc_md NULL; .char_md.p_cccd_md NULL; .char_md.p_sccd_md NULL; .init_len 1; // 初始值长度 .max_len 20; // 允许最大写入长度关键 .p_init_value init_val;6.3 通知无法送达客户端未收到BLE_GATTS_EVT_HVN_TX_COMPLETE根因客户端未启用通知CCCD 未置位或连接参数过松导致丢包。验证步骤使用 nRF Connect 连接设备在服务浏览器中找到目标特征值点击Enable notification观察BLE_GATTS_EVT_WRITE事件中p_evt_write-handle是否为 CCCD 句柄char_handles.cccd_handle且p_evt_write-data[0] 0x01若 CCCD 已启用但仍无通知尝试将连接间隔强制设为0x00067.5 ms测试链路质量。7. 与主流嵌入式生态集成7.1 FreeRTOS 集成模板原生支持 FreeRTOS只需在sdk_config.h中启用CONFIG_FREERTOS_ENABLED1并替换main()为int main(void) { // ... 初始化代码同前 ble_stack_init(); services_init(); // 创建应用任务 xTaskCreate(app_task, APP, 512, NULL, 2, NULL); xTaskCreate(ble_task, BLE, 1024, NULL, 3, NULL); vTaskStartScheduler(); // 启动调度器 for(;;); // 不可达 } // BLE 任务封装 SoftDevice 事件循环 static void ble_task(void * pvParameters) { for(;;) { uint32_t evt; while (app_uart_event_get(evt)) { // 处理 UART 事件 } // 保持 SoftDevice 运行 sd_app_evt_wait(); } }7.2 Zephyr RTOS 集成Zephyr 用户可直接引用aconnoBLETemplate为子模块将其src/目录下的.c文件加入CMakeLists.txt并实现 Zephyr 的BT_STACK适配层// zephyr_ble_adapter.c static void zephyr_ble_evt_handler(struct bt_conn *conn, uint8_t err, void *user_data) { if (!err) { on_connected(NULL); // 传入空指针或构造模拟事件 } } BT_CONN_CB_DEFINE(conn_callbacks) { .connected zephyr_ble_evt_handler, };7.3 STM32 BlueNRG-M0 协处理器方案对于非 Nordic 平台可将aconnoBLETemplate的业务逻辑服务模块、回调处理移植至 STM32通过 UART/SPIM 与 BlueNRG-M0 通信。此时模板的ble_evt_dispatch()替换为解析 BlueNRG 的 HCI Event Packetsd_ble_*API 替换为aci_hal_write_config_data()等 BlueNRG HAL 函数。8. 性能基准与实测数据在 nRF52832 QFAA48 MHz Cortex-M4上使用 S132 v7.2.0 SoftDevice典型负载下实测指标指标数值测试条件Flash 占用42.3 KB启用 Battery Device Info Custom Service无日志RAM 占用7.1 KB含 SoftDevice RAM2.5 KB、GATT DB1.2 KB、App Stack1.5 KB、Heap1.9 KB连接建立时间85–120 ms从广播开始到on_connected()执行完毕通知吞吐量1.2 KB/s连接间隔 15 msMTU 247 字节无加密待机电流0.9 μAsd_power_system_off()模式所有外设关闭仅 RTC 运行注电流数据基于 nRF52 DK 板实测量产板通过移除调试电路、优化 LDO 效率可降至 0.3 μA 以下。9. 维护与演进路线模板当前维护版本为v2.3.02024 Q2未来演进聚焦三个方向安全增强集成nrf_security库支持 FIPS 140-2 认证的 AES-CCM 加密与 ECDSA 签名用于医疗设备合规Mesh 扩展提供aconnoBLETemplate-mesh分支基于 nRF5 SDK Mesh v5.x支持 Proxy、Friend、Low Power Node 角色AI 边缘推理集成预留 CMSIS-NN 接口允许在on_sensor_data_ready()回调中调用轻量级神经网络模型如 TensorFlow Lite Micro实现本地化异常检测。所有更新均保证 ABI 兼容性v2.x系列内升级仅需替换源文件无需重构应用逻辑。历史版本与 Release Notes 托管于 GitHub每次发布附带完整回归测试报告涵盖连接稳定性、功耗、OTA 成功率等 32 项用例。一名在 Nordic 产线调试过 17 款 BLE 模组的工程师曾告诉我“最好的 BLE 模板不是功能最多而是让你在凌晨三点抓到一个NRF_ERROR_NO_MEM时能立刻翻出gatt_db_size的计算公式而不是对着 SDK 文档发呆。”aconnoBLETemplate的每一行注释、每一个默认参数、每一次错误检查都源于这种深夜的痛感。它不承诺替代你的思考只确保你思考的问题是真正属于产品的而非属于 BLE 协议栈的。
