1. SimpleBLE 库概述SimpleBLE 是为法国国立高等矿业学院École Nationale Supérieure de Mécanique et des Microtechniques, ENSMMOBCPObjets Connectés et Protocoles — 物联网设备与协议教学项目开发的轻量级蓝牙低功耗Bluetooth Low Energy, BLE软件库。该库并非通用型 BLE 协议栈如 Nordic nRF5 SDK 中的 SoftDevice、Zephyr 的 Bluetooth Host/Controller 或 BlueZ而是一个面向嵌入式教学场景、聚焦于 BLE 外设Peripheral角色的简化实现专为 STM32 系列微控制器特别是基于 Cortex-M0/M4 内核的型号设计运行于裸机Bare-metal或 FreeRTOS 环境下。其核心工程目标明确在有限的教学课时与学生嵌入式基础前提下剥离 BLE 协议栈的复杂性暴露关键控制点使学生能快速理解 BLE 连接建立、服务发现、特征值读写等核心交互逻辑并亲手完成一个可被手机 App如 nRF Connect识别和控制的 BLE 设备。因此SimpleBLE 不实现完整的 GAP/GATT 层状态机、不支持多连接、不包含 L2CAP 分片重组、不提供 ATT 协议的完整错误码处理而是以“够用、可控、可调试”为第一原则。从技术定位看SimpleBLE 属于典型的HAL-LL 混合驱动层抽象它直接操作 STM32 的硬件外设主要是 UART 用于与 BLE 模块通信或直接配置 RF 子系统同时向上提供一组语义清晰、参数精简的 C 函数接口。它不依赖任何商业 BLE 协议栈而是假设底层已存在一个具备基本 AT 指令集或寄存器映射能力的 BLE 硬件模块如 HM-10、JDY-08、或集成 BLE 射频的 STM32WB 系列芯片的专用外设。在 ENSMM 的 OBCP 课程中SimpleBLE 被用作“协议实践”的载体。学生通过修改simpleble_service.c中的特征值句柄、重载simpleble_on_write_callback回调函数、调整simpleble_init()中的广播数据包Advertising Data即可在数小时内完成一个温度传感器模拟器、LED 控制器或按钮状态上报器。这种“改一行代码现象立现”的反馈闭环是其教学价值的核心。2. 系统架构与硬件依赖2.1 整体分层模型SimpleBLE 的软件架构遵循经典的嵌入式分层思想自底向上分为四层层级组件职责依赖硬件层 (Hardware Layer)STM32 MCU、BLE 模块UART 接口或 STM32WB 射频外设提供物理射频收发能力UART/SPI/I2C 通信通道无外设驱动层 (Peripheral Driver Layer)stm32fxxx_hal_uart.c,stm32wbxx_ll_rfic.c等初始化串口、配置中断、发送/接收原始字节流或直接操作 RFIC 寄存器HAL/LL 库SimpleBLE 核心层 (Core Layer)simpleble_core.c/h,simpleble_gatt.c/h实现 BLE 广播包构造、连接事件解析、GATT PDUProtocol Data Unit的序列化/反序列化、属性表Attribute Table管理外设驱动层、CMSIS-Core应用接口层 (API Layer)simpleble.h,simpleble_service.h向用户暴露simpleble_init(),simpleble_start_advertising(),simpleble_register_write_callback()等高层 APICore Layer该架构刻意规避了传统 BLE 协议栈中常见的“Host-Controller Interface (HCI)”抽象层。在 UART 方案中SimpleBLE 直接将 AT 指令如ATADVSTART或二进制命令帧写入 UART 发送缓冲区在 STM32WB 方案中则直接向RFIC-TXDATA寄存器写入预格式化的 ADV_IND 包。这种紧耦合设计牺牲了移植性却极大降低了理解门槛——学生可直接在simpleble_core.c中看到uint8_t adv_data[] {0x02, 0x01, 0x06, 0x05, 0x09, S, I, M, P};这样的广播数据定义无需先学习 HCI ACL 数据包的结构。2.2 关键硬件接口与配置SimpleBLE 的运行高度依赖以下硬件资源的正确配置其初始化代码通常位于simpleble_platform_init()函数中UART 接口用于 AT 指令模式波特率固定为 9600 bpsHM-10 默认或 115200 bpsJDY-08 常见由SIMPLEBLE_UART_BAUDRATE宏定义。数据位/停止位/校验位8-N-1无硬件流控。中断启用UART_IT_RXNE接收非空中断和UART_IT_TC传输完成中断用于非阻塞通信。引脚TXMCU 输出至 BLE 模块 RX、RXMCU 输入来自 BLE 模块 TX需根据具体开发板原理图配置 GPIO 复用功能。RFIC 外设用于 STM32WB 直连模式时钟使能RCC_APB1ENR1_RFICEN。GPIO配置RFIC_ANT_SEL天线选择、RFIC_PA_EN功率放大器使能等控制引脚为推挽输出。中断使能RFIC_IRQn用于接收射频事件如RFIC_EVENT_RX_DONE。系统时钟与定时器SysTick用于实现simpleble_delay_ms()精度要求 ±10% 即可满足 BLE 广播间隔100ms~10s需求。TIM2可选若需精确控制连接事件窗口Connection Event可配置为 125μs 分辨率的计数器但 SimpleBLE 默认采用 MCU 主频分频的粗略延时。工程提示在 STM32CubeMX 中配置时UART 必须勾选 “Global Interrupt”并在生成代码后在main.c的MX_USARTx_UART_Init()后手动调用HAL_UART_Receive_IT(huartx, rx_byte, 1)启动首个字节接收否则无法触发后续的 AT 响应解析。3. 核心 API 接口详解SimpleBLE 的 API 设计贯彻“最小完备集”原则所有函数均以simpleble_为前缀返回simpleble_status_t枚举类型SIMPLEBLE_OK,SIMPLEBLE_ERROR,SIMPLEBLE_BUSY。以下是其最核心的五个接口及其底层实现逻辑。3.1 初始化与配置simpleble_init()该函数是整个库的入口点负责硬件初始化、内部状态机复位及默认 GATT 数据库构建。typedef struct { uint8_t device_name[32]; // 设备名ASCII 字符串 uint16_t appearance; // 外观值如 0x0340 (Generic Thermometer) uint8_t adv_interval_ms; // 广播间隔单位毫秒有效值20ms~10240ms uint8_t tx_power_level; // 发射功率等级0最低3最高依模块而定 } simpleble_config_t; simpleble_status_t simpleble_init(const simpleble_config_t* config);内部执行流程调用simpleble_platform_init()初始化 UART/RFIC。清零全局状态结构体g_simpleble_ctx包括连接状态标志is_connected、当前 MTU 大小mtu_size默认 23 字节。构造默认广播数据包Advertising Datauint8_t adv_data[31] { 0x02, 0x01, 0x06, // Flags: LE General Discoverable Mode BR/EDR Not Supported 0x05, 0x09, config-device_name[0], // Complete Local Name (长度类型名字) // ... 后续填充名字剩余字节 0x03, 0x19, (config-appearance 8) 0xFF, config-appearance 0xFF // Appearance };若为 UART 模式向模块发送ATNAMEname和ATADVIinterval指令若为 RFIC 模式则将adv_data加载至RFIC-ADV_DATA寄存器组。关键参数说明adv_interval_ms直接影响功耗与可发现性。教学实验中常设为 1000ms1Hz平衡电池消耗与手机扫描成功率。tx_power_level在 HM-10 上对应ATPOWE指令级别 3 可达 0dBm级别 0 为 -23dBm。室内实验推荐级别 1-6dBm避免信号过强导致多径干扰。3.2 广播控制simpleble_start_advertising()/simpleble_stop_advertising()这两个函数控制 BLE 设备的“可见性”是外设角色最基础的行为。simpleble_status_t simpleble_start_advertising(void); simpleble_status_t simpleble_stop_advertising(void);UART 模式实现start: 发送ATADVSTART等待模块返回OK\r\n。stop: 发送ATADVSTOP等待OK\r\n。底层通过HAL_UART_Transmit()发送指令并使用HAL_UART_Receive_IT()在中断中解析响应状态机保存于g_simpleble_ctx.adv_state。RFIC 模式实现start: 设置RFIC-CR | RFIC_CR_ADV_EN启动广播定时器。stop: 清除RFIC-CR中的ADV_EN位。广播包内容adv_data已在simpleble_init()中预加载此处仅开关使能位。工程注意事项在 FreeRTOS 环境下此函数必须在任务上下文中调用不可在中断服务程序ISR中直接调用因其内部可能涉及对 UART 外设寄存器的临界区访问。若需在 ISR 中触发广播启停应使用xQueueSendFromISR()向控制任务发送命令消息。3.3 GATT 服务注册simpleble_register_service()SimpleBLE 将 GATT 服务抽象为一个结构体允许用户动态注册自定义服务。这是实现“可编程 BLE 设备”的关键。typedef struct { uint16_t uuid16; // 16-bit UUID如 0x1809 (Temperature) uint8_t num_characteristics; // 该服务下特征值数量 const simpleble_characteristic_t* characteristics; // 特征值数组指针 } simpleble_service_t; simpleble_status_t simpleble_register_service(const simpleble_service_t* service);simpleble_characteristic_t结构体定义了单个特征值的全部属性typedef struct { uint16_t uuid16; // 特征值 UUID16-bit uint8_t properties; // 属性位掩码SIMPLEBLE_PROP_READ / WRITE / NOTIFY uint8_t* value_ptr; // 指向特征值当前值的指针RAM 地址 uint16_t value_len; // 当前值长度字节 uint16_t max_len; // 最大允许长度用于写入校验 } simpleble_characteristic_t;注册过程将service结构体及其characteristics数组拷贝至内部 RAM 的g_att_table属性表。为每个特征值分配唯一的 16-bit 句柄Handle按注册顺序递增起始句柄通常为 0x0001。自动为每个特征值添加对应的 Client Characteristic Configuration Descriptor (CCCD)句柄为特征值句柄1用于控制 Notify/Indicate 开关。示例注册一个 LED 控制服务uint8_t led_state 0; // 全局变量存储 LED 状态 const simpleble_characteristic_t led_char { .uuid16 0x2A56, // On/Off characteristic .properties SIMPLEBLE_PROP_READ | SIMPLEBLE_PROP_WRITE, .value_ptr led_state, .value_len 1, .max_len 1 }; const simpleble_service_t led_service { .uuid16 0x1810, // Generic Access Service .num_characteristics 1, .characteristics led_char }; // 在 main() 中调用 simpleble_register_service(led_service);3.4 写入回调注册simpleble_register_write_callback()当中心设备Central如手机向某个可写的特征值发起写请求时SimpleBLE 会调用用户注册的回调函数。这是实现“远程控制”的核心机制。typedef void (*simpleble_write_callback_t)(uint16_t handle, const uint8_t* data, uint16_t length); simpleble_status_t simpleble_register_write_callback(simpleble_write_callback_t callback);触发时机与数据流UART 模式BLE 模块收到写请求后通过 UART 发送类似NOTIFY:0002,01的通知0002为句柄01为数据SimpleBLE 的 UART 接收中断解析此字符串提取句柄与数据然后调用callback(handle, data_byte, 1)。RFIC 模式RFIC 外设产生RFIC_EVENT_ATT_WRITE_REQ中断在 ISR 中解析 ATT Write Request PDU提取Attribute Handle和Value字段再调用回调。回调函数中的典型处理void on_led_write(uint16_t handle, const uint8_t* data, uint16_t length) { if (handle 0x0002 length 1) { // 确认是 LED 特征值且数据长度正确 if (data[0] 0x01) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); // 点亮 } else if (data[0] 0x00) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); // 熄灭 } // 更新特征值内存中的值确保下次读取正确 *(g_att_table[0].characteristics[0].value_ptr) data[0]; } } // 注册回调 simpleble_register_write_callback(on_led_write);3.5 连接状态查询simpleble_is_connected()这是一个轻量级的状态查询函数用于应用层判断当前是否处于连接状态常用于条件性执行耗电操作如关闭传感器采样。bool simpleble_is_connected(void);实现原理UART 模式监听模块发送的CONNECTION/DISCONNECT事件字符串更新g_simpleble_ctx.is_connected标志。RFIC 模式检查RFIC-SR RFIC_SR_CONN_ESTABLISHED状态位。该函数为纯读取操作无副作用可在任意上下文包括中断安全调用。4. 典型应用场景与代码示例4.1 场景一BLE 温度传感器模拟器FreeRTOS 集成在 OBCP 实验中学生常需将 STM32 的 ADC 读数模拟温度通过 BLE 发送给手机。SimpleBLE 与 FreeRTOS 的结合可实现低功耗轮询。#include FreeRTOS.h #include task.h #include simpleble.h // 全局变量存储温度值整数单位 0.1°C int16_t temperature_centi 250; // 温度特征值定义 const simpleble_characteristic_t temp_char { .uuid16 0x2A1C, // Temperature Measurement .properties SIMPLEBLE_PROP_READ | SIMPLEBLE_PROP_NOTIFY, .value_ptr (uint8_t*)temperature_centi, .value_len sizeof(temperature_centi), .max_len sizeof(temperature_centi) }; // 任务周期性读取 ADC 并更新温度值 void vTempReadTask(void *pvParameters) { for(;;) { // 读取 ADC此处简化为模拟值 temperature_centi 250 (int16_t)(rand() % 100) - 50; // 20.0°C ~ 30.0°C // 如果有客户端订阅了 Notify则发送通知 if (simpleble_is_connected()) { simpleble_notify_value(0x0002, (uint8_t*)temperature_centi, sizeof(temperature_centi)); } vTaskDelay(pdMS_TO_TICKS(2000)); // 每 2 秒更新一次 } } int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_ADC1_Init(); MX_USART1_UART_Init(); // 初始化 SimpleBLE simpleble_config_t ble_cfg { .device_name ENSMM-THERMO, .appearance 0x0340, .adv_interval_ms 1000, .tx_power_level 1 }; simpleble_init(ble_cfg); simpleble_start_advertising(); // 创建温度读取任务 xTaskCreate(vTempReadTask, TempRead, configMINIMAL_STACK_SIZE, NULL, 1, NULL); // 启动调度器 vTaskStartScheduler(); while(1); }关键点解析simpleble_notify_value()是 SimpleBLE 提供的辅助函数封装了 Notify PDU 的构造与发送逻辑。vTaskDelay()使用 FreeRTOS 的滴答定时器比裸机HAL_Delay()更精准且不阻塞其他任务。simpleble_is_connected()的调用避免了在未连接时无效的 Notify 发送节省功耗。4.2 场景二基于中断的按钮状态上报裸机模式对于资源极度受限的 Cortex-M0 MCUFreeRTOS 可能过于沉重。SimpleBLE 支持纯裸机中断驱动模式。// 在 stm32f0xx_it.c 中 extern simpleble_context_t g_simpleble_ctx; void EXTI4_15_IRQHandler(void) { if (__HAL_GPIO_EXTI_GET_FLAG(GPIO_PIN_13)) { __HAL_GPIO_EXTI_CLEAR_FLAG(GPIO_PIN_13); // 按钮按下更新状态并触发 Notify static uint8_t button_state 0; button_state ^ 0x01; // 直接更新特征值内存 *(g_simpleble_ctx.att_table[0].characteristics[0].value_ptr) button_state; // 如果已连接则立即发送 Notify if (g_simpleble_ctx.is_connected) { simpleble_notify_value_immediate(0x0002, button_state, 1); } } }simpleble_notify_value_immediate()是一个无 RTOS 依赖的版本它直接调用HAL_UART_Transmit()UART 模式或RFIC-TXDATARFIC 模式发送数据不进行队列排队适用于对实时性要求极高的场景。5. 调试与常见问题排查5.1 UART 通信故障诊断当 BLE 模块无响应时首要检查 UART 通信链路物理层用万用表测量TX/RX引脚电压确认空闲态为高电平3.3V发送时有电平翻转。协议层使用逻辑分析仪捕获 UART 波形验证波特率、数据位是否匹配。SimpleBLE 的simpleble_debug_print()函数可将关键日志如ATCMD SENT,RESP RECEIVED通过第二路 UART如 USART2输出便于隔离调试。AT 指令响应在simpleble_core.c的uart_rx_callback()中设置断点观察接收到的原始字节流。常见错误是模块返回ERROR而非OK原因多为指令格式错误如缺少\r\n或模块未进入 AT 模式需拉低特定引脚或上电时序触发。5.2 广播不可见问题手机无法扫描到设备按以下顺序排查广播数据合法性检查adv_data数组长度是否 ≤ 31 字节。超过则被截断导致Flags或Name缺失手机忽略该广播包。广播使能状态确认simpleble_start_advertising()返回SIMPLEBLE_OK且g_simpleble_ctx.adv_state SIMPLEBLE_ADV_STARTED。天线与距离STM32WB 的板载 PCB 天线对地平面敏感确保开发板放置在开阔区域远离金属物体。使用simpleble_set_tx_power(3)提升发射功率测试。5.3 写入回调不触发中心设备写入后无回调常见原因特征值属性错误确认simpleble_characteristic_t.properties中设置了SIMPLEBLE_PROP_WRITE位。句柄不匹配手机 App 显示的句柄是 16 进制而代码中比较的是十进制。例如App 显示0x0002代码中应写if (handle 0x0002)而非if (handle 2)C 语言中0x0002与2等价但为清晰起见建议统一用十六进制。连接未建立simpleble_is_connected()返回false说明设备虽在广播但未成功建立连接。检查中心设备是否点击了“Connect”按钮而非仅“Discover”。6. 总结SimpleBLE 的工程价值与演进路径SimpleBLE 的本质是一个为教育场景深度定制的“BLE 协议解剖工具”。它不追求工业级的鲁棒性与兼容性而是以极致的简洁性将 BLE 协议栈中那些被层层封装的“黑箱”——广播信道、连接事件、GATT 属性表、ATT PDU——转化为学生可触摸、可修改、可调试的 C 语言变量与函数。在 ENSMM 的实验室里一个学生能在两小时内从阅读simpleble_core.c中的adv_data数组开始亲手修改设备名、更换服务 UUID、添加新的可写特征值并最终用手机点亮一块 LED。这种即时、可视、可验证的学习体验是任何文档或视频教程都无法替代的。对于嵌入式工程师而言SimpleBLE 的价值远超教学。其源码是理解 BLE 协议物理层与链路层交互逻辑的绝佳范本。通过研读其simpleble_gatt.c中对ATT_WRITE_REQ的解析逻辑可以深刻体会为何 BLE 写操作必须包含 16-bit 的 Attribute Handle通过跟踪simpleble_notify_value()的执行路径能清晰看到一个 Notify PDU 如何被组装为[Opcode0x1B][Handle_LSB][Handle_MSB][Value...]的字节流。这些底层细节正是在使用商业 SDK 时被彻底隐藏的“魔法”。未来SimpleBLE 的合理演进方向并非堆砌功能而是深化其“教学-工程”桥梁作用增加对 BLE Mesh 的基础支持如 GATT Proxy 功能引入更严格的 ATT 错误码处理如0x01 Attribute Not Found或提供与 Zephyr Bluetooth Host 的对接层让学生能平滑过渡到工业级开发。但其核心哲学不会改变——始终以“让协议变得可见”为使命成为嵌入式开发者探索无线世界的第一把钥匙。