做BLE开发的朋友几乎都会被同一个问题卡住标准GATT服务确实方便但业务逻辑稍微特殊一点就发现通用Profile怎么都不顺手。数据要分包、要加密、要带上自己的命令字或者设备端要对接私有网关这时候用STM32WB的Custom Template来定制一条自己的BLE私有协议就成了最务实的路子。我最近把LAT1197这篇应用笔记完整跑了一遍基于CubeWB自带的Custom Template工程自己动手改了一套私有协议栈从协议设计、代码实现到联调踩坑整个过程值得好好整理一下分享给准备在STM32WB上做定制化BLE方案的工程师。这篇博文适合下面这类读者已经在用或准备用STM32WB做无线产品对BLE规范有一点点基础但不想用官方那些通用例程硬套自己的业务想自己定义服务、特征值和数据帧格式的开发者。我会把LAT1197里提到的Custom Template到底在哪、怎么用、怎么改成自己的协议以及我在改写过程中遇到的细节问题都讲清楚。看完之后你至少能独立搭出一个“从广播到连接、从收发数据到协议解析”的私有BLE通信链路。1. LAT1197在讲什么Custom Template的定位与价值1.1 为什么需要Custom Template先解释一下背景。STM32WB是意法半导体推出的双核无线MCU一颗Cortex-M4负责跑应用另一颗Cortex-M0专门跑蓝牙协议栈。这种双核架构的好处是协议栈处理和业务逻辑互不干扰应用核不会因为处理Link Layer任务而卡顿。但代价是工程结构比普通单核MCU复杂M4和M0之间要通过IPC消息去交互很多人第一次接触都会被这套机制绕晕。ST官方在STM32CubeWB固件包里提供了不少示例比如BLE_HeartRate、BLE_Throughput这些都是基于标准GATT服务的Demo。这类例程的好处是拿来就能跑缺陷也很明显所有服务、特征值都是ST定义好的UUID、数据格式、行为逻辑都是写死的。你想改一个特征值的UUID或者想在连接后立刻下发一包自定义控制指令就得去翻代码、改回调、动协议栈配置改到后面往往发现还不如从头搭一个干净工程。Custom Template就是为了解决这个痛点存在的。它位于固件包的Projects\NUCLEO-WB55RG\Applications\BLE\Custom_Template目录下本质是一个最小可用的BLE从机工程模板内部已经配置好了基本的GAP广播、GATT服务和数据收发通道。最关键的是它把ST那些复杂的初始化过程封装的比较干净开发者可以在一个相对清晰的代码结构上直接替换成自己的服务定义和处理逻辑。1.2 LAT1197和Custom Template的关系LAT1197是ST官方发布的应用笔记全称大概是“AN1197 Custom Template for STM32WB”之类的编号文档不过大家记住LAT1197这个编号就行。它的作用就是手把手告诉你Custom Template这个模板怎么集成到自己的项目中。我找到的版本内容覆盖了从工程导入、代码结构说明、到如何添加自定义服务和修改广播数据这几个层面。需要说明的是LAT1197本身更偏向于“说明文档”真正的核心资产还是Custom Template工程本身你最终的工作都是在那个工程里完成的。我自己的感受是LAT1197适合用来建立全局概念但光看文档不动手很多细节根本意识不到。比如自定义UUID的字节序问题、广播数据31字节上限怎么分配、通知使能之后数据下发的时序、还有调试时很容易忽略的HCI接口日志输出。所以接下来我按实战路线来讲把工程改写的每一步和踩过的坑都摊开比直接贴文档更有用。2. BLE私有协议怎么设计从业务需求到GATT映射2.1 私有协议到底“私有”在哪里很多人对“BLE私有协议”有误解以为要自己写物理层和数据链路层那是不可能的也是没有必要的。BLE通信的底层无线传输、连接管理、重传机制都是蓝牙协议栈已经做好的事情。所谓的私有协议通常指在GATT层之上的业务数据格式和交互流程是我们自己定义的。换句话说物理链路和L2CAP这些底层还是标准的BLE但应用层的数据交换方式、UUID、数据包结构、交互时序都由你说了算。这样做的好处很多可以定义紧凑的二进制帧格式减少空口数据量可以用私有128位UUID避免和市面上的标准服务冲突还可以在应用层加入自己的加密、校验、命令应答机制。对做智能家居、工业传感器、私有网关对接的团队来说这套思路非常实用。2.2 怎么把业务协议映射到GATT的Service和Characteristic设计私有协议的第一步是要把业务交互模型归类到GATT的层次上。GATT的模型其实不复杂一个设备可以有多个Service每个Service包含多个CharacteristicCharacteristic有属性读、写、通知、指示通过属性进行数据交互。业务上最常见的两种交互模式用GATT来表达非常直观主设备下发控制指令对应一个属性为“写”的Characteristic手机端往这个特征值写入数据设备端在写回调里解析指令。从设备主动上报数据对应一个属性为“通知/指示”的Characteristic设备端主动发送数据手机端开启通知后就会持续收到。像LAT1197的Custom Template里ST就预设了一个名为P2P Server的服务里面设计了两个Characteristic一个用来收手机下发的数据一个用来向手机发送通知。这个结构基本覆盖了大多数简单的命令-响应、主动上报场景。如果你的业务更复杂比如需要多个独立的数据通道那就照着这个模板继续添加Characteristic即可。以我自己的项目为例当时做的是一个低功耗温度采集器业务逻辑是手机发一条查询命令设备在一秒内上报温度数据。协议帧我设计为| Byte0 帧头 | Byte1 命令字 | Byte2-5 数据区 | Byte6 校验和 |这样一个短小的帧用4个字节就能搞定一次完整的查询应答交互。在GATT映射上我只需要一个写特征值接收命令和一个通知特征值上报结果再加上一个标准的Device Information Service做设备信息识别完全够用。2.3 关键参数需要提前定下来协议设计阶段就要把蓝牙参数和技术指标定好不要等代码写完了再改改起来会非常痛苦。几个关键参数和我的实践经验列一下128位UUID的选取不要用ST模板里默认的P2P UUID建议自己生成一个唯一的128位UUID网上有很多UUID生成器生成之后区分好Service UUID和Characteristic UUID。广播间隔与连接间隔如果设备主要用于上报数据广播间隔可以短一点方便快速发现比如100ms如果是低功耗场景连接间隔可以设大比如50ms到100ms之间兼顾实时性和功耗。MTU大小默认MTU是23字节实际应用数据只有20字节。如果业务帧比较长可以在连接后发起MTU协商请求协商到247字节做更长数据的传输。单包数据长度即便协商了更大的MTU单次通知的最大长度也受MTU限制建议业务帧设计成定长或携带长度的可变长结构。3. 实操把Custom Template工程跑起来3.1 环境准备工具链与版本匹配在动代码之前先把环境搭对避免后面折腾一上午发现是版本问题。我自己用的这套组合供参考STM32CubeMX6.10及以上版本用来生成初始化代码和配置时钟、外设。STM32CubeWB固件包1.16.0或更新的版本LAT1197对应的Custom Template就在这个包里。IAR EWARM或者STM32CubeIDE官方例程对IAR的支持最完整不过CubeIDE也一样能编译我这次用的STM32CubeIDE更新及时调试体验不错。NUCLEO-WB55RG开发板官方最常用的评估板Custom Template默认就是为这块板子准备的。需要注意的是STM32CubeMX在生成工程时会自动检测固件包版本如果版本之间差异较大生成出来的代码结构和Custom Template可能会有出入。所以我建议装好固件包之后直接用Custom Template自带的工程文件不要用CubeMX重新生成一版再合并那样工作量反而大。3.2 导入工程和编译烧录Custom Template的工程文件在Projects\NUCLEO-WB55RG\Applications\BLE\Custom_Template下里面有EWARM和STM32CubeIDE的子目录。我用CubeIDE的话直接选择Existing Projects导入即可。导入后先别急着改先编译一次。这个工程第一次编译可能要拉取一些中间文件耗时略长耐心等一会。烧录时有个重点STM32WB是双核芯片M0核烧的是蓝牙协议栈固件M4核烧的是应用代码。但Custom Template这个例子很省事因为它是通过“无线烧录”方式把协议栈加载到M0核的也就是说只需要烧录M4核的Image协议栈会在应用初始化时被加载到M0。实测下来ST这套方式确实方便不用专门准备J-Link去烧M0。编译烧录完成后开发板的LCD屏幕会显示广播和连接状态NUCLEO-WB55RG板载LCD如果没有显示屏可以通过串口查看日志。我的建议是第一步先不要连手机用串口工具打开日志口确认设备起来后在正确广播。3.3 工程整体结构先看一遍再动手Custom Template的代码结构不复杂但涉及的文件和调用链值得先搞清楚。我梳理了一张逻辑图给团队新人看main.c └─ 硬件初始化、时钟配置 app_ble.c ├─ BLE协议栈初始化 ├─ GAP配置广播、连接参数 ├─ GATT服务注册 └─ BLE事件回调分发 p2p_server.c ├─ P2P服务定义 ├─ 写特征值回调 └─ 通知发送接口LAT1197文档里对这块的说明和我的梳理基本一致。核心逻辑都在app_ble.c和p2p_server.c这两个文件里前者管连接生命周期后者管业务数据收发。你在改协议的时候九成的时间都在动这两个文件其余像是hci_tl.c、stm32wbxx_hal_msp.c这些底层文件正常开发很少去碰除非要调整时钟或引脚映射。app_ble.c中的初始化顺序我建议认真读一遍先调用MX_APPE_Init()做协议栈和GATT初始化再调用MX_APPE_Process()进入事件循环。事件循环不要放在阻塞式while里要放到主循环的SuperLoop中否则会影响协议栈处理。4. 核心代码实现从广播到数据收发的完整解析4.1 广播数据的DIY广播数据是BLE设备给人留下的第一印象手机扫描列表里看到的名字、厂商数据、服务UUID全在这里。Custom Template默认的广播数据包含一个完整的广播包和一个扫描响应包分别在app_ble.c里的a_AdvData和a_ScanResponseData这两个数组里定义。广播包的数据格式是TLV结构第一个字节表示后面数据块的长度第二个字节是AD Type随后是数据内容。以我定制的广播包为例我要把服务UUID广播出去同时加入两个字节的自定义设备类型标识代码里这样定义static uint8_t a_AdvData[] { 0x02, AD_TYPE_FLAGS, 0x06, 0x03, AD_TYPE_16_BIT_SERVICE_UUID, 0x00, 0x00, 0x04, AD_TYPE_MANUFACTURER_SPECIFIC_DATA, 0x54, 0x4C, 0x01, };这里的0x03代表这个数据块长度为31字节类型2字节内容AD_TYPE_16_BIT_SERVICE_UUID表明后面是两个字节的16位UUID。如果你用128位UUID则要使用AD_TYPE_128_BIT_SERVICE_UUID数据块长度也要相应调整成17字节。扫描响应包我放了设备名最长不超过31字节这点要特别注意蓝牙4.0经典广告包总共只有31字节可用这31字节要同时容纳必须的Flags和自定义数据剩余空间非常紧张。如果广播和扫描响应装不下就要考虑把一些不重要的信息省掉。LAT1197里其实也建议把广播数据精简因为广播包是周期性发送的每多一个字节就多一点空中占用时间和功耗。我自己的心得是广播包只放“快速识别设备”的最小信息完整信息等连接建立后再通过GATT读特征值获取没必要一股脑塞进广播里。4.2 自定义Service和Characteristic的添加接下来是重头戏在Custom Template上添加自己的服务。我把ST默认的P2P服务改成自己的Sensor ServiceUUID我随机生成了一个128位UUID并给服务里的两个特征值分别分配了不同的UUID。在p2p_server.c的P2P_Server_Init函数中服务注册的调用链是这样的先调用aci_gatt_add_serv注册服务然后在回调里根据event参数判断当前状态再依次调用aci_gatt_add_char添加特征值。下面这个代码片段是我改过的服务注册逻辑static void Sensor_Server_Init(void) { tBleStatus ret BLE_STATUS_INVALID_PARAMS; ret aci_gatt_add_serv( SERVICE_UUID_TYPE_128, // UUID类型128位 (Service_UUID_t *)Sensor_Service_UUID, // 服务UUID指针 SENSOR_SERVICE_MAX_NBR_ATTRIBUTES, // 属性数量上限 Sensor_Service_Handle); // 返回的服务句柄 if (ret BLE_STATUS_SUCCESS) { // 添加写特征值用于接收手机下发的命令 aci_gatt_add_char( Sensor_Service_Handle, CHAR_UUID_TYPE_128, (Char_UUID_t *)Sensor_Rx_Char_UUID, SENSOR_RX_CHAR_SIZE, CHAR_PROP_WRITE, ATTR_PERMISSION_NONE, Sensor_Rx_Char_Handle); // 添加通知特征值用于设备向手机上报数据 aci_gatt_add_char( Sensor_Service_Handle, CHAR_UUID_TYPE_128, (Char_UUID_t *)Sensor_Tx_Char_UUID, SENSOR_TX_CHAR_SIZE, CHAR_PROP_NOTIFY, ATTR_PERMISSION_NONE, Sensor_Tx_Char_Handle); } }这里有几个细节容易翻车。SENSOR_SERVICE_MAX_NBR_ATTRIBUTES这个值要设置正确每个Characteristic本身需要消耗2个属性声明和值如果还有配置描述符比如CCCD用于通知使能还要再加1个。我一开始只填了5个结果运行到注册第二个特征值时报错BLE_STATUS_INSUFFICIENT_RESOURCES后来加到8个才正常。每个服务、每个特征值的句柄都是全局变量要在头文件里声明extern后面所有操作都要用到。特征值的属性要仔细选择。比如接收命令的特征值有的产品希望手机随时能写有的希望配对后才能写这对应不同的权限设置。Custom Template默认设置是ATTR_PERMISSION_NONE连接后手机就能读写安全性要求高的产品建议开启配对绑定并在配对完成后才开放写权限。4.3 数据收发的核心回调设备端接收数据的入口在Sensor_Server_App_Notification这个回调里它是整个协议栈事件分发机制的一部分。当手机端写数据到特征值时协议栈会上抛ACI_GATT_ATTRIBUTE_MODIFIED_EVT事件需要在这个事件里做业务数据的解析处理。我写的接收处理逻辑是这样的static void Sensor_Server_App_Notification(void *pEvent) { tBleStatus ret BLE_STATUS_INVALID_PARAMS; ACI_GATT_ATTRIBUTE_MODIFIED_EVT_t *pData NULL; switch (((hci_event_pckt_t *)pEvent)-evt) { case ACI_GATT_ATTRIBUTE_MODIFIED_EVT: pData (ACI_GATT_ATTRIBUTE_MODIFIED_EVT_t *)((hci_event_pckt_t *)pEvent)-data; if (pData-Att_Handle Sensor_Rx_Char_Handle 1) // 注意句柄偏移 { // 在这里解析手机发来的私有协议帧 Parse_Command_Frame(pData-Att_Data, pData-Att_Data_Length); } break; default: break; } }这里有个特别容易踩的坑事件返回的Att_Handle和你在aci_gatt_add_char时拿到的句柄并不完全一致。Characteristic Handle指的是特征值声明的句柄而ACI_GATT_ATTRIBUTE_MODIFIED_EVT返回的是特征值“值”属性的句柄两者相差1。我第一次写的时候直接拿服务注册返回的handle去比对结果怎么都触发不了后来在调试日志里打印了handle才发现这个问题。所以建议在注册完成后把Sensor_Rx_Char_Handle和Sensor_Rx_Char_Handle 1都打印出来确认哪一个是实际触发写事件的句柄。发送数据给手机端用aci_gatt_update_char_value这个APIret aci_gatt_update_char_value( Sensor_Service_Handle, Sensor_Tx_Char_Handle, 0, // 值偏移0表示从头发送 length, // 数据长度 data_buffer); // 数据缓冲区这个函数准备好之后要注意通知是否已经使能。手机端没有开启Notify之前调用这个接口不会报错但数据也不会送出去。严谨的做法是在代码里维护一个布尔变量在CCCD回调里更新通知状态只有使能了才真正发送。我在家里调试的时候经常因为忘了先点手机上的“开启通知”按钮导致设备端显示发送成功但手机收不到数据排查了半天才发现是通知没开。4.4 SuperLoop机制与RTOS的配合Custom Template默认的工程结构是超级循环SuperLoop式的不带RTOS。main.c的主循环里除了跑MX_APPE_Process()处理BLE协议栈事件还要跑你自己的业务逻辑。这里要特别注意优先级和阻塞问题。如果你的业务代码里有耗时的操作比如Flash写入、传感器采集建议不要在BLE事件回调里直接做而是置一个标志位在主循环里处理否则可能影响BLE协议栈的响应实时性。如果你的产品打算上RTOS比如FreeRTOS那么MX_APPE_Process要放到一个独立任务中并且任务栈空间要足够。官方推荐的栈大小是1024字节以上但我在跑一些稍复杂的数据处理时会把它调整到2048字节避免栈溢出导致的诡异问题。5. 联调、调试与踩坑记录5.1 常用的几种调试手段对比STM32WB的调试方式和普通MCU不太一样因为协议栈在M0核上运行用调试器只能看到M4核的应用状态协议栈内部发生了什么得靠ST提供的工具来观察。我梳理了几种常用调试手段调试手段适用场景优势劣势串口日志查看程序运行流程、错误码简单直接不依赖额外硬件只能看代码主动打印的信息STM32CubeMonitor-RF抓取空口无线数据包能观看到广播包、连接包、数据包的完整时序需要USB Dongle数据量大会刷屏nRF Connect手机端快速验证广播信息、服务发现、数据收发方便手机上直接看适合产品早期验证无法看到底层重传细节ST-Link调试器单步跟踪应用代码能查变量值和函数调用栈看不到协议栈内部动作我习惯的组合是开发前期用nRF Connect验证服务定义和数据交互跑通后如果怀疑协议栈行为异常再用STM32CubeMonitor-RF抓空口包确认时序。串口日志则全程开着随时打印关键状态和错误码。5.2 我遇到过的三个典型问题第一个问题是广播数据太长手机扫描不到。修改广播数据后我往广播包里塞了完整的128位服务UUID又加了一段设备信息加起来超过31字节结果编译没问题但手机端完全扫描不到。后来检查才发现广播包的长度超过31字节时协议栈会直接停止广播。解决方法是把128位UUID移到扫描响应包里广播包只保留必要的Flags和短名称。第二个问题是连接后排不上包设备端收不到手机端的数据。排查到最后发现是SENSOR_RX_CHAR_SIZE定义得太小只有4个字节而手机端一次写入8字节协议栈直接拒绝了写入返回错误码。把特征值大小调整到20字节并处理好MTU协商后问题解决。这里需要注意特征值大小对应单个Attribute Value的最大字节数不是缓冲区大小设置过小会直接限制单次写入的数据量。第三个问题比较隐蔽是关于连接参数更新的。设备连接后如果手机端请求修改连接间隔等参数协议栈会上抛一个连接参数更新请求事件。Custom Template默认没有做自动接受处理结果就是有些手机请求把连接间隔改成7.5ms有些改成50ms设备这边被动接受导致不同手机之间的数据延迟表现差异很大。我在代码里补充了参数检查逻辑只接受合理范围内的连接参数超出就拒绝并保持原有参数这样产品表现就稳定多了。case ACI_GAP_LL_CONNECTION_UPDATE_COMPLETE_EVT: // 连接参数更新完成后的处理 break; case ACI_GAP_LINK_CONNECTION_UPDATE_REQ_EVT: // 收到连接参数更新请求可以在这里决定接受或拒绝 // 检查connInterval、slaveLatency等参数是否合理 break;5.3 参数调整和低功耗建议BLE产品通常对功耗有要求结合LAT1197的说明和我自己实测的数据给几个参数调整建议广播阶段的功耗与广播间隔直接相关。广播间隔100ms时平均电流大约在15到20uA之间如果拉长到1s平均电流能降到5uA以下。但如果你的产品需要被快速发现建议分阶段广播前30秒用100ms快速广播之后切到1s慢速广播这样兼顾了发现速度和功耗。连接阶段的功耗主要由连接间隔、从机延迟Slave Latency和是否开启ACK自动应答决定。我的做法是把从机延迟设为4这样设备每5个连接事件才醒来一次接收数据功耗能降低不少但代价是双向通信的触达延迟会变大下发指令后最坏情况要等几个连接间隔才有响应。电商类、交互类应用建议从机延迟设为0或1确保指令实时性。还有一点容易被忽略就是M0核的运行状态。STM32WB的M0负责协议栈即使应用核进入低功耗模式M0也要保持运行才能维护连接。在进入低功耗之前要确保BLE没有正在进行的空中活动比如正在发送长数据包时不要立刻Sleep。我一般是在发送回调收到发送完成事件后再进入低功耗这样既省电又不会丢包。6. 从Custom Template到量产固件的路径规划6.1 从Demo到产品的代码整理Custom Template能让你快速跑通流程但它毕竟是工程模板直接拿去做量产产品还缺不少东西。你需要补上几块工作一是把调试用的串口日志按日志等级裁剪线上版本只保留ERROR级别的打印否则日志本身会成为功耗元凶二是把硬编码的UUID、句柄、缓冲区整理成独立配置头文件方便维护和裁剪三是把协议解析层从驱动层拆分出来方便做单元测试。我自己的习惯是把协议帧的解析和组包做成独立的模块用纯C实现不依赖任何ST的库函数。这样我可以在PC上用单元测试框架直接测试协议的正确性而不必每次都烧录到板子上验证。蓝牙链路调试固然重要但协议逻辑的正确性完全可以脱离硬件提前验证这个习惯帮我省了很多时间。6.2 安全相关的设计考量如果私有协议承载的数据比较敏感比如医疗数据、门锁指令那GATT层的ATTR_PERMISSION_NONE显然是不够的。你需要考虑以下安全措施开启LE Secure Connections配对使用Just Works或者Passkey方式完成配对绑定。写特征值设置写权限为ATTR_PERMISSION_WRITE_ENC只有加密连接才能写入。在业务层做数据加密即便蓝牙链路被嗅探也无法直接解析业务帧。在协议帧中加入递增序列号和消息认证码防止重放攻击。LAT1197和Custom Template里没有直接教你做这些但它的代码结构给了你足够的扩展空间。加密、认证这些逻辑放到事件回调里和协议解析层即可不影响协议栈本身。6.3 多设备场景下的连接与连接参数规划如果你的产品要和多个设备同时连接比如一个网关带多个传感器那就不只是单从机的问题了。STM32WB最多支持的连接数受到RAM和配置限制NUCLEO-WB55RG的默认配置里是从机模式以最多支持8个连接为上限。但连接的设备越多每个连接可用的带宽和缓存就越小需要合理规划。我做过一个网关项目同时管理4个传感器节点。这种情况下传感器端的从机延迟要调大网关端的连接间隔要拉开避免多个连接事件在时间上重叠导致冲突。协议层也要区分不同设备推荐在服务特征值层面带上节点ID字段或者在每个连接的回调里判断连接句柄来区分数据来源。这些在Custom Template默认代码里都没有现成的需要自己加一套连接实例的管理结构体。7. 一些个人的体会用Custom Template做BLE私有协议最大的感受是“下限很低、上限不低”。它帮你把协议栈初始化和底层通信处理好了入门难度确实比从零开始写低很多但要真正把一套私有协议打磨稳定还是要花不少功夫去理解GATT语义、连接参数、MTU协商这些细节。尤其是当你开始做多连接、低功耗、安全加密这些进阶特性时光靠模板已经不够需要把BLE协议知识补起来。不过反过来看正因为模板给了你一个干净可控的起点你的每一分投入都会沉淀在自己的代码里而不是消耗在和官方例程的“斗争”中。最后再分享一个调试上的小技巧在开发阶段给串口日志加上时间戳所有事件和错误码都带上毫秒级时间排查BLE时序问题时会非常有用。比如连接后第一条数据是在什么时候到的、命令和响应之间隔了多久这些信息在优化交互体验时是实打实的依据。我自己吃过不少没有时间戳的亏后来补上这个功能排查问题的效率提升非常明显。
