简介面向使用安信可PB-03蓝牙模块进行二次开发的嵌入式工程师与物联网学习者这份资料合集围绕PHY6252低功耗蓝牙SoC展开重点解决BLE5.2开发环境搭建、外设驱动参考与固件升级等常见需求。压缩包共1163个文件、约66.23MB以C源码与头文件为主体辅以Keil工程文件、链接脚本、启动汇编、INI配置、批处理脚本及PDF文档覆盖从工程配置到编译烧录的多个环节并包含串口AT指令、FOTA升级与低功耗休眠等相关参考材料。已有2248人学习说明其在PB-03二次开发人群中具有一定参考价值。读者可从中获取较完整的SDK目录与示例工程结构借助源码与配置理解UART、GPIO、ADC、PWM、I2C、SPI等接口的调用方式对照文档和工程文件排查编译、链接与下载问题也可为Windows开发环境下的二次开发与固件远程升级提供直接可用的素材。1. PB03 蓝牙 5.2 二次开发资料一份资料包能省掉哪些摸索手上有一块 PB03 模组想让它从「能广播」走到「能跟自己的 App 收发自定义数据」中间这段路很多人卡过两三天不知道 SDK 该从哪个文件下手广播包改完手机扫不到烧录工具一连上就报握手失败。PB03 蓝牙 5.2 二次开发资料这套文档资料的价值就在这儿——它把 SDK 工程、硬件设计文件、AT 指令手册、烧录工具和几套可编译的例程收在一起拿到手就能编译、能下载、能跟自己的板子对比差异不是芯片手册的中文翻译版。适合三类人第一次碰 BLE 5.2 模组、需要两周内出样机的固件工程师要画底板、核对引脚复用和天线净空的硬件工程师以及做方案选型、想判断这颗模组扛不扛得住自己场景的技术负责人。2. 资料包拆解SDK 目录、协议栈分层与二次开发的可改边界二次开发资料包最容易出现的浪费是不是「东西不够」而是「不知道哪份东西该信」。同一个功能AT 指令手册里有一套说法例程里又有一套写法SDK 里的宏开关还是第三套。第 2 章先把包里的结构捋清哪些目录只读、哪些是主要修改区域、协议栈哪一层能改哪一层碰了就麻烦以及硬件那份资料该在什么时候看。等把边界划清楚后面编译、烧录、调 GATT 才有参照系不然每改一行代码都像在赌。2.1 目录分工哪几个文件夹看完就该锁上PB03 这类模组的二次开发包目录结构基本是固定的几个部分区别只在命名习惯。我一般拿到包先做一件事ls一遍把每个目录归到「只读」和「会改」两类里心里有个地图再动手。下面这张表是按常见组织方式整理的实际包里的名字可能差一两个字但功能对应得上。目录常见命名典型内容二次开发时的用途是否修改doc/数据手册、AT 指令手册、天线设计指南、功耗实测表查引脚定义、指令集、射频指标只读sdk/协议栈库文件、应用层源码、Keil 工程、链接脚本改业务逻辑、加自定义服务主要修改区域sdk/lib/预编译的协议栈与射频驱动.lib/.a只调用不反编译只读hw/原理图、PCB 封装库、BOM、匹配网络参数画底板、核对引脚复用只读tool/烧录上位机、串口助手、固件合并脚本、量产工具下载固件、看日志、批量写参数只读example/透传、主从一体、HID、OTA 四类例程抄配置、对比差异、当回归基线可改但先备份表里最关键的一行是sdk/lib/。协议栈以预编译库的形式给出意味着链路层、射频校准、跳频这些逻辑你既看不到也改不了出问题只能从应用层参数倒推。这不是资料包偷懒是认证和射频一致性要求的常规做法。知道自己改不到那一层排查思路就会变——连不上先怀疑参数和时序而不是去翻协议栈源码。动手的第一步我个人的习惯是把sdk/整份复制一份出来改个名字比如sdk_myproj/原始包保持原样。原因很实际二次开发过程中一定会改宏、改链接地址、删例程改乱了想回退重新解压一遍是最快的后悔药。同理example/里的透传例程建议单独复制一份当「金标准」你自己的工程跑不通时把它烧进去对比能立刻区分是硬件问题还是代码问题——这个动作在两块板子都调不通的时候能救命。还要提醒一个细节很多包的doc/里放着两三个版本的 AT 指令手册文件名只差一个后缀。别默认最新的那份就对应当前固件。判断方法是看手册里描述的指令集和你手上模组实际返回的响应是否一致随手发一条查询指令回什么就知道版本对不对得上。这个核对只花两分钟能省掉后面半小时的自我怀疑。2.2 协议栈分层GAP 广播、GATT 属性、应用回调各管什么BLE 的分层概念网上一搜一大把但落到「我到底能改哪一行」还是得按这个资料包的实际结构重新讲一遍。从下往上看控制器层含射频、链路层、跳频以库形式封装你只通过 API 配置参数主机层的 GAP 负责广播、扫描、连接建立GATT 负责属性的组织和读写再往上是你自己的应用逻辑和串口协议。二次开发里 90% 的工作量集中在 GATT 和 GAP 参数这两块。广播包内容的填充、连接间隔的取值、自定义服务属性表的顺序、CCCD 的读写回调——这些全在应用层改起来不用碰库。反过来凡是涉及「连接建立之前的射频行为」和「链路稳定性」的比如发射功率、射频信道、白名单过滤的底层实现基本都在库里你只能通过上层参数间接影响。新手最容易误改的是启动文件和链接脚本。它们长得像普通源码里面也确实有可以改的数字但改错的表现往往不是编译报错而是烧进去之后跑飞、或者广播正常但一连接就复位。我见过有人为了省几 KB 空间去动链接脚本里的段地址结果应用区和 OTA 备份区重叠升级一次直接变砖。这类文件在包里通常放在sdk/project/下面看到.sct、.ld、startup_*.s这种后缀动之前先备份改完必须做一次完整的烧录和连接验证。另一处边界是中断优先级。协议栈对射频中断和定时器中断的响应时间有隐含要求应用层如果把串口中断优先级配得比射频还高重负载时会出现连接间隔抖动甚至断链。资料包里的例程一般给了一套可用的优先级配置直接沿用比自己重新分配更稳非要改就一次只改一个改完拿连接稳定性压测一遍。2.3 工具链版本对齐编译器和烧录工具比你想的挑嵌入式资料包最容易被忽略的一句话是「本 SDK 在某某版本下验证通过」。这句话不是免责声明是硬约束。编译器版本差异会带来两个后果一是 C 库行为不同导致的隐性问题比如某些优化等级下的对齐访问二是生成的代码体积变化本来刚好塞进应用区的固件突然超了。具体要核对三项编译器主版本、器件支持包、烧录上位机版本。前两项决定能不能编译出行为一致的固件第三项决定能不能把固件写进去。烧录工具的版本和模组内部固件版本之间通常有协议对应关系版本差太多会表现成「能识别串口但握手失败」这种报错信息往往很含糊看着像硬件坏了其实换个工具版本就好。串口驱动的坑也值得一提。同一台电脑上装过多个串口工具时虚拟串口偶尔会被别的软件占用表现是烧录工具提示打不开端口但设备管理器里看着一切正常。遇到这种情况先关掉所有串口助手再试别急着怀疑板子。2.4 硬件资料怎么用天线净空和电源纹波比原理图重要hw/目录里的原理图很多人扫一眼就跳过直接照着引脚表画底板。真正会被忽略又最容易出事的是两块天线的净空区和电源的纹波要求。天线部分资料里一般会给一个推荐布局模组天线端到板边要保持一段无铜无走线的净空底下不走线不铺铜附近不要放电池和金属结构件。这段距离具体多少看包里的天线设计说明但「净空」这件事必须当真。我踩过一次底板为了塞结构把电池挪到天线正下方传导测试一切正常实际通信距离掉了一大半查了两天才定位到。电源部分BLE 模组在广播瞬间有脉冲电流LDO 选型偏小或者去耦电容离得太远会出现「空闲正常、一广播就复位」。资料里的参考设计给了电容位置和容值照着抄就行别自己优化。表里这几个点硬件阶段确认一次能省掉固件阶段一半的玄学问题。检查项资料里看哪硬件阶段怎么验天线净空天线设计指南目视 卡尺净空区内无铜无器件匹配网络原理图匹配电路按参考值贴不自行改容感值电源去耦参考设计布局电容靠近模组电源脚地平面完整复位与启动脚引脚定义表上电时序符合要求不悬空调试串口引脚复用表留出测试点方便抓日志3. 跑通第一个工程宏配置、命令行编译与烧录验证把资料包里的例程编译通过、烧进去、手机能扫到这三步做完心里才算有底。这章按顺序走一遍先在 IDE 里改对几个关键宏再用命令行把编译过程脚本化后面接自动化构建也方便然后校验固件尺寸别越界最后烧录并验证广播。每一步都给出判断标准做完能明确知道「这一步过了」。3.1 打开工程先改三个宏别急着编译第一次打开 Keil 工程不要直接点编译。先找工程配置里的预定义宏通常在Options for Target的 C/C 页确认三个方向上的开关日志输出、休眠使能、设备名与地址来源。日志开关决定你能不能看到串口打印。出厂状态的例程有时为了省电把日志全关了烧进去串口一片安静你会以为程序没跑起来实际上是没打印。调试阶段先打开功能验证完再关掉关掉之前记得测一次功耗因为日志本身很耗电。休眠使能决定空闲时会不会进低功耗。带休眠调试连接问题很痛苦因为唤醒需要时间某些时序会被拉长。我一般调试期先关休眠等连接稳定了再打开专门测一轮。设备名和地址来源这一项很多 SDK 用宏来控制是「用芯片内部地址」还是「用代码里写死的地址」。如果两片模组广播出来名字和地址完全一样手机端会出现只能连上一片的情况看着像连接问题其实是配置重复。/* 这几个开关通常定义在工程宏或 board_cfg.h 里名字随 SDK 有差异 */ #define CFG_LOG_EN 1 /* 调试期开量产关关掉能省下几 mA */ #define CFG_SLEEP_EN 0 /* 调试期关稳定后再开 */ #define CFG_USE_CHIP_MAC 1 /* 1用芯片唯一地址0用下面写死的地址 */ #define CFG_DEV_NAME PB03-DEV /* 广播里的设备名长度计入广播包 */ #define CFG_UART_BAUD 115200 /* 调试串口波特率和上位机保持一致 */这段配置不需要解释太多重点是养成「先确认再编译」的顺序。血泪经验是改代码之前先确认宏改完之后记录改了什么否则三五天后自己都不记得当初为什么把这行设成 0。3.2 命令行编译把错误从日志里捞出来IDE 里点编译适合调试但只要开始多人协作或者想把构建挂到自动流程里命令行编译就必须能跑通。资料包里的工程是标准 Keil 工程可以用它的命令行模式批量编译。#!/usr/bin/env bash # 一键编译并提取关键信息适合本地快速验证或挂到构建机 set -euo pipefail KEIL_BIN/c/Keil_v5/UV4/UV4.exe # 按本机安装路径改注意 Windows 路径在 bash 下的写法 PROJsdk_myproj/project/pb03_app.uvprojx # 工程文件相对路径要先 cd 到仓库根目录 LOGbuild/compile_$(date %Y%m%d_%H%M%S).log mkdir -p build build_log # -b 批量编译(不弹窗) -j0 抑制对话框 -o 输出完整日志 $KEIL_BIN -b $PROJ -j0 -o $LOG || true # Keil 的进程返回码不区分警告和错误扫日志比看返回码可靠 echo ---- 错误与告警 ---- grep -nE error:|Error:|Warning: $LOG | tail -n 30 || echo 无错误 echo ---- 代码体积 ---- grep -nE Program Size|Total RO|Total RW $LOG | tail -n 8 || true几处说明。-b是批处理编译模式不弹界面适合脚本调用-j0用来抑制可能出现的模态对话框不然在无人值守的构建机上会卡住等点击-o把完整日志落盘这是排查的关键——IDE 窗口里滚过去的告警往往被忽略落盘之后grep一遍才发现有「隐式声明」这类会埋雷的告警。|| true是有意加的。Keil 命令行在某些版本下即使编译成功也返回非零码直接set -e会把脚本中断在成功的那一步。真正判断成败看日志里的error:计数这也是为什么脚本里要单独 grep 一遍。如果编译报的是「找不到某个头文件」九成是工程里的相对路径和你移动目录之后的实际位置对不上。解决办法不是改代码里的#include而是回到工程配置的 Include Paths 里修路径这样所有引用同一处配置的源文件都能一起好。3.3 固件尺寸校验别让应用区越界这一步很多人省略直到 OTA 升级失败才发现固件的末尾压到了备份区。做二次开发尤其是加了自定义服务和日志之后代码体积是会长的靠肉眼判断不靠谱写个脚本卡住更稳妥。#!/usr/bin/env python3 按分区表校验编译产物是否越过应用区上限防止烧进去跑飞或 OTA 变砖。 import sys APP_LIMIT 0x3A000 # 应用区上限改成自己分区表里的值别照抄 def hex_top_addr(path: str) - int: 遍历 Intel HEX返回所有数据记录覆盖到的最高地址。 top 0 with open(path, r, encodingutf-8, errorsignore) as f: for line in f: line line.strip() if not line.startswith(:): continue raw bytes.fromhex(line[1:]) length raw[0] addr (raw[1] 8) | raw[2] rectype raw[3] if rectype 0x00: # 0x00 是数据记录其余类型不影响地址占用 top max(top, addr length) elif rectype 0x04: # 0x04 扩展线性地址高 16 位要左移拼接 # 这里只做上限判断遇到扩展地址记录时把高位记下来即可 pass return top if __name__ __main__: top hex_top_addr(sys.argv[1]) left APP_LIMIT - top print(ftop0x{top:08X} limit0x{APP_LIMIT:08X} free{left} bytes) sys.exit(0 if left 0 else 1)关键参数只有一个APP_LIMIT它的值必须来自你自己的分区表不是随便写的常数。脚本里的rectype 0x00判断的是数据记录只有这一类才真正占用 Flash 地址0x04那条分支是留给你扩展高位的如果固件地址超过 64KB 就必须补全否则算出来的上限会偏小反而误报。把这个脚本挂到编译之后跑一次返回非零就中断构建。养成习惯之后加功能时会不自觉地关注体积增长比事后救火强。3.4 烧录与上电验证两个判断标准烧录一般有两条路串口 ISP 和调试器。串口 ISP 需要把启动脚拉到指定电平再上电让芯片进下载模式调试器则是直接连 SWD 口能顺带在线调试。第一次建议用调试器出问题能看到芯片有没有起来量产和维护用串口不依赖调试器。烧完之后的验证分两步。第一步看串口日志上电后有没有打印启动信息初始化到哪一步有没有报错。日志停在哪一行问题就在那附近。第二步用手机端的通用 BLE 调试 App 扫描看能不能扫到设备名信号强度是否正常服务列表里有没有你预期的 UUID。判断标准要具体能扫到但连不上问题在连接参数或配对配置能连上但服务列表是空的问题在属性表注册顺序扫都扫不到先查广播使能有没有调用再查天线。这三条分清楚排查就不会乱撞。4. 自定义 GATT 服务广播数据、属性表与连接参数例程能跑通只是起点真正落地时一定要加自己的服务和特征值。这章讲三件事广播包 31 字节怎么分配、属性表怎么注册出一个最小可用的自定义服务、连接参数和 MTU 怎么先测再定。最后补一段低功耗配置因为很多项目死在「功能都对功耗超标」这一步。4.1 广播包与扫描响应31 字节怎么分配传统广播包上限 31 字节每一段都由「1 字节长度 1 字节类型 内容」组成长度字节不包含它自己。BLE 5.2 支持扩展广播可以超过 31 字节但手机端的兼容性和模组侧的支持度都不统一实际项目里我一般还是按 31 字节来规划把厂商自定义数据放到扫描响应里。/* 广播数据长度字节 1(类型) 内容长度 */ static uint8_t adv_payload[] { 0x02, 0x01, 0x06, /* Flags通用可发现不支持 BR/EDR */ 0x05, 0x09, P, B, 0, 3, /* 0x09 完整设备名长度 14 */ 0x03, 0x03, 0x0F, 0x18, /* 0x03 完整 16bit UUID 列表 */ }; /* 扫描响应单独一包也限 31 字节厂商自定义字段放这里更宽松 */ static uint8_t scan_rsp[] { 0x06, 0xFF, 0x34, 0x12, 0x01, 0x02, /* 0xFF 厂商自定义前两字节是厂商 ID(小端) */ }; /* 使能广播函数名以实际 SDK 为准 */ ble_gap_adv_start(adv_payload, sizeof(adv_payload), scan_rsp, sizeof(scan_rsp), 100 /* 广播间隔 ms100~500 之间按需取 */);最容易错的地方是长度字节。比如设备名是 4 个字符那么长度应该是 5类型 1 字节 名字 4 字节写成 4 会把名字最后一个字符吃掉手机端显示成三个字母看着像编码问题。加一段内容就重新数一遍别凭感觉。广播间隔这个参数要权衡调小被发现更快但平均功耗直线上升调到 500 ms 以上某些手机的扫描窗口覆盖不到会表现为「偶尔能扫到」。100~300 ms 是常见的起步区间。4.2 属性表注册一个自定义服务的最小闭环GATT 服务在代码里就是一张属性表表项顺序决定 handle 顺序handle 又是客户端读写的寻址依据。所以顺序不能乱中间也不能插空项。一个能读、能开通知的最小服务需要四项服务声明、特征值声明、特征值本身、CCCD。/* 自定义 128bit 服务的属性表顺序即 handle 递增顺序 */ static const att_db_item_t user_db[] { /* 1. 服务声明主服务 128bit UUID */ { .type ATT_TYPE_PRIMARY_SERVICE, .uuid_len 16, .uuid USER_SVC_UUID, .perm ATT_PERM_READ }, /* 2. 特征值声明属性位决定客户端能不能开通知这里给读通知 */ { .type ATT_TYPE_CHARACTERISTIC, .uuid_len 16, .uuid USER_CHAR_UUID, .perm ATT_PERM_READ, .value { .props ATT_PROP_READ | ATT_PROP_NOTIFY } }, /* 3. 特征值本身max_len 要和 MTU 协商结果对齐别写成 512 占内存 */ { .type ATT_TYPE_CHAR_VALUE, .uuid_len 16, .uuid USER_CHAR_UUID, .perm ATT_PERM_READ, .value { .buf user_val, .len sizeof(user_val), .max_len 20 } }, /* 4. CCCD客户端写 0x0001 开通知0x0000 关 */ { .type ATT_TYPE_CCCD, .perm ATT_PERM_READ | ATT_PERM_WRITE, .value { .buf user_cccd, .len 2 } }, }; /* 写回调里按 handle 分派handle 用注册后的返回值别写死数字 */ static void on_attr_write(uint16_t handle, const uint8_t *data, uint16_t len) { if (handle user_cccd_handle) { user_notify_en (len 2) (data[0] 0x01); /* 开/关通知 */ } else if (handle user_val_handle) { /* 业务数据处理注意 len 可能小于 max_len */ handle_user_cmd(data, len); } }三处说明。max_len 20对应默认 MTU 23 减去 3 字节协议开销如果后面协商到更大 MTU这个值要同步放开但在没协商之前设太大只是白占 RAM。CCCD 必须占一个独立表项漏了它客户端开不了通知表现是「订阅了但收不到数据」。回调里判断 handle 一定要用注册后返回的变量写死数字在后期插入新服务时必然错位而且错位之后的行为很诡异——写 A 特征值却触发了 B 的逻辑。注册完之后手机端能看到服务但点开可能是空的。这种情况先确认属性表里的 UUID 字节序128 位 UUID 在内存里通常按小端倒序存放写反了客户端解析出的 UUID 和你以为的不一样服务会被当成未知服务折叠起来。4.3 连接参数与 MTU先测再定别抄别人的数连接参数直接决定吞吐、延迟和功耗三者互相牵制。参数没有通用最优值只能按场景定。先把几个参数的物理含义和边界搞清楚再用实测收敛。参数常见取值影响注意广播间隔100~500 ms被发现速度、平均功耗低于 100 ms 收益不明显功耗接近翻倍最小连接间隔15~30 ms吞吐、响应延迟部分手机端会向上收敛到它认可的粒度从机延迟0~4空闲时省电设太大配合小间隔写操作容易超时监督超时2~6 s断链判定速度必须大于 (1延迟) × 间隔 × 2否则频繁误判断链MTU23 或 247单包有效负载默认 23即 20 字节协商后按实际值算调试连接问题光看手机界面不够得把空中抓到的广播和连接行为拆开看。下面这段脚本用来解析抓包工具或串口导出的广播十六进制串检查 AD 结构是否合法、有没有超长。#!/usr/bin/env python3 把广播原始 hex 逐条拆成 AD 结构定位长度写错或类型写错的那一段。 def parse_adv(hexstr: str) - None: data bytes.fromhex(hexstr.replace( , ).replace(\n, )) if len(data) 31: print(f[警告] 长度 {len(data)} 超过传统广播包 31 字节上限) i 0 while i len(data): ln data[i] if ln 0: # 0 表示后续是填充直接结束 break if i 1 len(data): print(f[错误] 偏移 {i} 处长度 {ln} 越界包被截断) return ad_type data[i 1] value data[i 2: i 1 ln] print(foff{i:3} len{ln:3} type0x{ad_type:02X} value{value.hex( )}) i ln 1 if __name__ __main__: # 把抓到的广播 hex 粘进来空格可有可无 parse_adv(02 01 06 05 09 50 42 30 33 03 03 0F 18)i ln 1是核心跳过一个长度字节加 ln 个字节的内容。ln 0提前退出是因为广播包尾部常用零填充。这段脚本不依赖任何第三方库抓包工具导出的数据直接粘贴就能用定位「名字少了最后一个字母」「UUID 类型写成 0x02」这类问题比肉眼数快得多。MTU 协商的结果要在连接建立后主动打印一次。有些平台默认不协商你以为能发 200 字节实际每包只发出去 20 字节剩余全被截断表现是「指令发一半设备不响应」。日志里加上协商前后的 MTU 值这个问题一眼就能看出来。4.4 低功耗休眠、GPIO 与广播间隔的取舍功耗超标是二次开发里最典型的翻车点。规格书上的数字通常是「仅射频MCU 广播」的理想值你板子上多一个上拉电阻、多一路常开的串口数字就完全不一样。第一件事是确认休眠真的进去了。很多 SDK 有休眠前后的钩子函数在里面翻转一个 GPIO用示波器看这个脚的占空比就知道实际醒着多久。比看电流平均值直观得多。第二件事是 GPIO 状态。休眠时悬空的输入脚会因电平不确定产生漏电上拉电阻在外部有下拉时会持续耗流。原则是不用的脚配置成模拟或下拉输出外部上拉能省则省能加大阻值就加大。第三件事是外设时钟。串口、定时器、ADC 在休眠前该关的关掉尤其是串口——调试完忘记关一晚掉几百微安很常见。广播间隔的调整放在最后先把漏电堵住再谈间隔否则你怎么调间隔都对不上规格书。5. 常见问题排查烧录、连接、功耗的五条踩坑记录有些坑几乎每个项目都会踩一遍写在这里省得重复试错。下面五条都按「现象 → 原因 → 解决」组织遇到相似症状可以直接对照。需要强调一点BLE 调试最忌讳同时改多个变量一次只改一处改完立刻验证否则问题解决了你也不知道是哪一步生效的。5.1 烧录报握手失败换线换板都没用现象烧录工具能识别到串口点开始后几秒提示握手失败或超时换 USB 线、换板子症状一样。原因多半是没进下载模式。串口 ISP 需要在复位释放的瞬间采样启动脚电平手动按键的时序经常对不上另一种可能是烧录工具版本与模组内部固件版本不匹配协议对不上同样表现为握手失败。解决先改成调试器烧录排除时序问题确认固件本身没问题如果只能用串口用工具里的「自动进入下载模式」选项让工具通过 DTR/RTS 控制复位和启动脚别手动按。工具版本按资料包tool/目录里配套的那份用不要用电脑上残留的旧版。5.2 广播数据改了手机扫到的还是旧名字现象代码里改了设备名并重新编译烧录手机端扫出来还是原来那个名字换一台手机也一样。原因缓存。手机端对已配对或曾扫描到的设备会缓存 GATT 和广播信息Android 侧尤其明显另一种情况是编译产物没真正烧进去烧录的是旧 hex。解决先在手机蓝牙设置里删除该设备记录或在调试 App 里清缓存再扫同时核对烧录日志里的固件时间和大小确认烧的是新产物。判断是不是缓存最直接的办法是换一台从没扫过这个设备的手机。5.3 能连上几秒钟后自动断开现象连接建立成功服务也能看到三五秒后连接断开反复重连。原因监督超时配置不合理最常见。监督超时必须大于 (1 从机延迟) × 连接间隔 × 2如果从机延迟设成 4、间隔 30 ms超时至少要 300 ms 以上配成 200 ms 就会周期性误判断链。其次是应用层在连接回调里做了耗时操作阻塞了协议栈的事件处理。解决先把从机延迟改成 0、监督超时放大到 4 s 验证连接是否稳定稳定后逐步往回调找到临界点再留一倍余量。回调里不要做 Flash 擦写、不要长延时重活丢到主循环里做。5.4 功耗比规格书高一个数量级现象休眠电流实测几百微安规格书写的是个位数微安。原因串口没关、GPIO 悬空漏电、调试日志没关、外部上拉电阻常供这四样占了绝大多数。日志这一项最隐蔽因为功能上完全正常。解决按顺序排查——先关日志测一次再关串口测一次再把所有未用 GPIO 配成模拟态测一次。每关一项测一次电流变化最大的那项就是主因。用 GPIO 翻转配合示波器看唤醒占空比比盯着万用表数字猜有效。5.5 AT 固件和 SDK 固件混着烧功能莫名其妙现象按 SDK 例程烧完串口发 AT 指令没反应或者刷回 AT 固件后自定义服务消失但广播名还是自己改的那个。原因AT 固件和 SDK 固件是两套完全不同的应用共用同一块 Flash 但入口和分区不同。混烧之后配置区残留旧参数表现就是「一半新一半旧」。解决切换固件类型前先做一次全片擦除别只擦应用区。切换完成后用默认配置跑一遍基础功能确认干净了再烧自己的业务固件。产线上尤其要注意返修板子回炉时先擦再写。6. OTA 与产线固化把「能跑」变成「能出厂」样机能跑通和能出厂之间隔着 OTA 和参数固化两件事。这两块资料包里不一定有现成脚本但基于里面的例程补起来不难。OTA 的核心是分区。常见做法是应用区 备份区双 bank新固件先整包写进备份区校验通过后把启动标志指过去重启由 bootloader 搬运或直接跳转。判断 OTA 是否可靠别只看「升级成功」这一条要专门测三个场景升级过程中断电、升级包被截断、降级回滚。断电测试最容易被跳过但它恰恰是现场最容易发生的——用户在升级时锁屏走了。/* OTA 状态机的最小实现关键是每一步都落标志位掉电后可恢复 */ typedef enum { OTA_IDLE, OTA_RECEIVING, OTA_VERIFYING, OTA_READY, OTA_FAIL } ota_state_t; static void ota_on_packet(const uint8_t *data, uint16_t len, uint32_t offset) { /* 1. 先写备份区绝不直接覆盖运行区 */ if (flash_write(OTA_BAK_ADDR offset, data, len) ! 0) { ota_set_state(OTA_FAIL); /* 写失败立刻标记下次上电重来 */ return; } /* 2. 每包写完更新进度标志掉电后从标志处续传 */ ota_set_progress(offset len); ota_set_state(OTA_RECEIVING); } static void ota_on_finish(uint32_t total_len) { ota_set_state(OTA_VERIFYING); /* 3. 整包 CRC 校验通过才允许切启动标志 */ if (crc32_check(OTA_BAK_ADDR, total_len) 0) { ota_set_state(OTA_READY); ota_commit_boot_flag(); /* 这一步之后才真正生效 */ } else { ota_set_state(OTA_FAIL); /* 校验失败保留旧固件不切标志 */ } }这段代码的重点不在语法在顺序先写备份区、再校验、最后切标志。把切标志放到校验之前一次传输错误就能让设备变砖现场只能返修。进度标志要落在独立的配置区别和固件放一起否则搬运固件时会一起被擦掉。产线固化是另一件事。每台设备需要写入唯一的 MAC、设备名、校准参数和密钥这些不该靠改代码重新编译。常规做法是在 Flash 里划一小块参数区产线工具通过串口指令写入应用启动时读取。参数区要带版本号和 CRC升级固件后参数仍然有效参数格式变了则按版本号做兼容迁移。验证方法我一般分三层单机功能回归广播、连接、读写、通知四项走一遍、异常注入断电、断链、超长包、错 CRC、小批量老化十几台连续跑 24 小时统计断链次数和电流波动。三层都过才敢说这批固件能出厂。从那以后我每次改完固件都强制走一遍「擦全片 → 烧固件 → 断电重启 → 手机端删缓存重扫」这四步不管改动多小。省下的那两分钟往往要用两天去找回来。希望帮到你。本文还有配套的精品资源点击获取 PB03蓝牙5.2二次开发资料：从SDK到GATT与OTA实战
简介面向使用安信可PB-03蓝牙模块进行二次开发的嵌入式工程师与物联网学习者这份资料合集围绕PHY6252低功耗蓝牙SoC展开重点解决BLE5.2开发环境搭建、外设驱动参考与固件升级等常见需求。压缩包共1163个文件、约66.23MB以C源码与头文件为主体辅以Keil工程文件、链接脚本、启动汇编、INI配置、批处理脚本及PDF文档覆盖从工程配置到编译烧录的多个环节并包含串口AT指令、FOTA升级与低功耗休眠等相关参考材料。已有2248人学习说明其在PB-03二次开发人群中具有一定参考价值。读者可从中获取较完整的SDK目录与示例工程结构借助源码与配置理解UART、GPIO、ADC、PWM、I2C、SPI等接口的调用方式对照文档和工程文件排查编译、链接与下载问题也可为Windows开发环境下的二次开发与固件远程升级提供直接可用的素材。1. PB03 蓝牙 5.2 二次开发资料一份资料包能省掉哪些摸索手上有一块 PB03 模组想让它从「能广播」走到「能跟自己的 App 收发自定义数据」中间这段路很多人卡过两三天不知道 SDK 该从哪个文件下手广播包改完手机扫不到烧录工具一连上就报握手失败。PB03 蓝牙 5.2 二次开发资料这套文档资料的价值就在这儿——它把 SDK 工程、硬件设计文件、AT 指令手册、烧录工具和几套可编译的例程收在一起拿到手就能编译、能下载、能跟自己的板子对比差异不是芯片手册的中文翻译版。适合三类人第一次碰 BLE 5.2 模组、需要两周内出样机的固件工程师要画底板、核对引脚复用和天线净空的硬件工程师以及做方案选型、想判断这颗模组扛不扛得住自己场景的技术负责人。2. 资料包拆解SDK 目录、协议栈分层与二次开发的可改边界二次开发资料包最容易出现的浪费是不是「东西不够」而是「不知道哪份东西该信」。同一个功能AT 指令手册里有一套说法例程里又有一套写法SDK 里的宏开关还是第三套。第 2 章先把包里的结构捋清哪些目录只读、哪些是主要修改区域、协议栈哪一层能改哪一层碰了就麻烦以及硬件那份资料该在什么时候看。等把边界划清楚后面编译、烧录、调 GATT 才有参照系不然每改一行代码都像在赌。2.1 目录分工哪几个文件夹看完就该锁上PB03 这类模组的二次开发包目录结构基本是固定的几个部分区别只在命名习惯。我一般拿到包先做一件事ls一遍把每个目录归到「只读」和「会改」两类里心里有个地图再动手。下面这张表是按常见组织方式整理的实际包里的名字可能差一两个字但功能对应得上。目录常见命名典型内容二次开发时的用途是否修改doc/数据手册、AT 指令手册、天线设计指南、功耗实测表查引脚定义、指令集、射频指标只读sdk/协议栈库文件、应用层源码、Keil 工程、链接脚本改业务逻辑、加自定义服务主要修改区域sdk/lib/预编译的协议栈与射频驱动.lib/.a只调用不反编译只读hw/原理图、PCB 封装库、BOM、匹配网络参数画底板、核对引脚复用只读tool/烧录上位机、串口助手、固件合并脚本、量产工具下载固件、看日志、批量写参数只读example/透传、主从一体、HID、OTA 四类例程抄配置、对比差异、当回归基线可改但先备份表里最关键的一行是sdk/lib/。协议栈以预编译库的形式给出意味着链路层、射频校准、跳频这些逻辑你既看不到也改不了出问题只能从应用层参数倒推。这不是资料包偷懒是认证和射频一致性要求的常规做法。知道自己改不到那一层排查思路就会变——连不上先怀疑参数和时序而不是去翻协议栈源码。动手的第一步我个人的习惯是把sdk/整份复制一份出来改个名字比如sdk_myproj/原始包保持原样。原因很实际二次开发过程中一定会改宏、改链接地址、删例程改乱了想回退重新解压一遍是最快的后悔药。同理example/里的透传例程建议单独复制一份当「金标准」你自己的工程跑不通时把它烧进去对比能立刻区分是硬件问题还是代码问题——这个动作在两块板子都调不通的时候能救命。还要提醒一个细节很多包的doc/里放着两三个版本的 AT 指令手册文件名只差一个后缀。别默认最新的那份就对应当前固件。判断方法是看手册里描述的指令集和你手上模组实际返回的响应是否一致随手发一条查询指令回什么就知道版本对不对得上。这个核对只花两分钟能省掉后面半小时的自我怀疑。2.2 协议栈分层GAP 广播、GATT 属性、应用回调各管什么BLE 的分层概念网上一搜一大把但落到「我到底能改哪一行」还是得按这个资料包的实际结构重新讲一遍。从下往上看控制器层含射频、链路层、跳频以库形式封装你只通过 API 配置参数主机层的 GAP 负责广播、扫描、连接建立GATT 负责属性的组织和读写再往上是你自己的应用逻辑和串口协议。二次开发里 90% 的工作量集中在 GATT 和 GAP 参数这两块。广播包内容的填充、连接间隔的取值、自定义服务属性表的顺序、CCCD 的读写回调——这些全在应用层改起来不用碰库。反过来凡是涉及「连接建立之前的射频行为」和「链路稳定性」的比如发射功率、射频信道、白名单过滤的底层实现基本都在库里你只能通过上层参数间接影响。新手最容易误改的是启动文件和链接脚本。它们长得像普通源码里面也确实有可以改的数字但改错的表现往往不是编译报错而是烧进去之后跑飞、或者广播正常但一连接就复位。我见过有人为了省几 KB 空间去动链接脚本里的段地址结果应用区和 OTA 备份区重叠升级一次直接变砖。这类文件在包里通常放在sdk/project/下面看到.sct、.ld、startup_*.s这种后缀动之前先备份改完必须做一次完整的烧录和连接验证。另一处边界是中断优先级。协议栈对射频中断和定时器中断的响应时间有隐含要求应用层如果把串口中断优先级配得比射频还高重负载时会出现连接间隔抖动甚至断链。资料包里的例程一般给了一套可用的优先级配置直接沿用比自己重新分配更稳非要改就一次只改一个改完拿连接稳定性压测一遍。2.3 工具链版本对齐编译器和烧录工具比你想的挑嵌入式资料包最容易被忽略的一句话是「本 SDK 在某某版本下验证通过」。这句话不是免责声明是硬约束。编译器版本差异会带来两个后果一是 C 库行为不同导致的隐性问题比如某些优化等级下的对齐访问二是生成的代码体积变化本来刚好塞进应用区的固件突然超了。具体要核对三项编译器主版本、器件支持包、烧录上位机版本。前两项决定能不能编译出行为一致的固件第三项决定能不能把固件写进去。烧录工具的版本和模组内部固件版本之间通常有协议对应关系版本差太多会表现成「能识别串口但握手失败」这种报错信息往往很含糊看着像硬件坏了其实换个工具版本就好。串口驱动的坑也值得一提。同一台电脑上装过多个串口工具时虚拟串口偶尔会被别的软件占用表现是烧录工具提示打不开端口但设备管理器里看着一切正常。遇到这种情况先关掉所有串口助手再试别急着怀疑板子。2.4 硬件资料怎么用天线净空和电源纹波比原理图重要hw/目录里的原理图很多人扫一眼就跳过直接照着引脚表画底板。真正会被忽略又最容易出事的是两块天线的净空区和电源的纹波要求。天线部分资料里一般会给一个推荐布局模组天线端到板边要保持一段无铜无走线的净空底下不走线不铺铜附近不要放电池和金属结构件。这段距离具体多少看包里的天线设计说明但「净空」这件事必须当真。我踩过一次底板为了塞结构把电池挪到天线正下方传导测试一切正常实际通信距离掉了一大半查了两天才定位到。电源部分BLE 模组在广播瞬间有脉冲电流LDO 选型偏小或者去耦电容离得太远会出现「空闲正常、一广播就复位」。资料里的参考设计给了电容位置和容值照着抄就行别自己优化。表里这几个点硬件阶段确认一次能省掉固件阶段一半的玄学问题。检查项资料里看哪硬件阶段怎么验天线净空天线设计指南目视 卡尺净空区内无铜无器件匹配网络原理图匹配电路按参考值贴不自行改容感值电源去耦参考设计布局电容靠近模组电源脚地平面完整复位与启动脚引脚定义表上电时序符合要求不悬空调试串口引脚复用表留出测试点方便抓日志3. 跑通第一个工程宏配置、命令行编译与烧录验证把资料包里的例程编译通过、烧进去、手机能扫到这三步做完心里才算有底。这章按顺序走一遍先在 IDE 里改对几个关键宏再用命令行把编译过程脚本化后面接自动化构建也方便然后校验固件尺寸别越界最后烧录并验证广播。每一步都给出判断标准做完能明确知道「这一步过了」。3.1 打开工程先改三个宏别急着编译第一次打开 Keil 工程不要直接点编译。先找工程配置里的预定义宏通常在Options for Target的 C/C 页确认三个方向上的开关日志输出、休眠使能、设备名与地址来源。日志开关决定你能不能看到串口打印。出厂状态的例程有时为了省电把日志全关了烧进去串口一片安静你会以为程序没跑起来实际上是没打印。调试阶段先打开功能验证完再关掉关掉之前记得测一次功耗因为日志本身很耗电。休眠使能决定空闲时会不会进低功耗。带休眠调试连接问题很痛苦因为唤醒需要时间某些时序会被拉长。我一般调试期先关休眠等连接稳定了再打开专门测一轮。设备名和地址来源这一项很多 SDK 用宏来控制是「用芯片内部地址」还是「用代码里写死的地址」。如果两片模组广播出来名字和地址完全一样手机端会出现只能连上一片的情况看着像连接问题其实是配置重复。/* 这几个开关通常定义在工程宏或 board_cfg.h 里名字随 SDK 有差异 */ #define CFG_LOG_EN 1 /* 调试期开量产关关掉能省下几 mA */ #define CFG_SLEEP_EN 0 /* 调试期关稳定后再开 */ #define CFG_USE_CHIP_MAC 1 /* 1用芯片唯一地址0用下面写死的地址 */ #define CFG_DEV_NAME PB03-DEV /* 广播里的设备名长度计入广播包 */ #define CFG_UART_BAUD 115200 /* 调试串口波特率和上位机保持一致 */这段配置不需要解释太多重点是养成「先确认再编译」的顺序。血泪经验是改代码之前先确认宏改完之后记录改了什么否则三五天后自己都不记得当初为什么把这行设成 0。3.2 命令行编译把错误从日志里捞出来IDE 里点编译适合调试但只要开始多人协作或者想把构建挂到自动流程里命令行编译就必须能跑通。资料包里的工程是标准 Keil 工程可以用它的命令行模式批量编译。#!/usr/bin/env bash # 一键编译并提取关键信息适合本地快速验证或挂到构建机 set -euo pipefail KEIL_BIN/c/Keil_v5/UV4/UV4.exe # 按本机安装路径改注意 Windows 路径在 bash 下的写法 PROJsdk_myproj/project/pb03_app.uvprojx # 工程文件相对路径要先 cd 到仓库根目录 LOGbuild/compile_$(date %Y%m%d_%H%M%S).log mkdir -p build build_log # -b 批量编译(不弹窗) -j0 抑制对话框 -o 输出完整日志 $KEIL_BIN -b $PROJ -j0 -o $LOG || true # Keil 的进程返回码不区分警告和错误扫日志比看返回码可靠 echo ---- 错误与告警 ---- grep -nE error:|Error:|Warning: $LOG | tail -n 30 || echo 无错误 echo ---- 代码体积 ---- grep -nE Program Size|Total RO|Total RW $LOG | tail -n 8 || true几处说明。-b是批处理编译模式不弹界面适合脚本调用-j0用来抑制可能出现的模态对话框不然在无人值守的构建机上会卡住等点击-o把完整日志落盘这是排查的关键——IDE 窗口里滚过去的告警往往被忽略落盘之后grep一遍才发现有「隐式声明」这类会埋雷的告警。|| true是有意加的。Keil 命令行在某些版本下即使编译成功也返回非零码直接set -e会把脚本中断在成功的那一步。真正判断成败看日志里的error:计数这也是为什么脚本里要单独 grep 一遍。如果编译报的是「找不到某个头文件」九成是工程里的相对路径和你移动目录之后的实际位置对不上。解决办法不是改代码里的#include而是回到工程配置的 Include Paths 里修路径这样所有引用同一处配置的源文件都能一起好。3.3 固件尺寸校验别让应用区越界这一步很多人省略直到 OTA 升级失败才发现固件的末尾压到了备份区。做二次开发尤其是加了自定义服务和日志之后代码体积是会长的靠肉眼判断不靠谱写个脚本卡住更稳妥。#!/usr/bin/env python3 按分区表校验编译产物是否越过应用区上限防止烧进去跑飞或 OTA 变砖。 import sys APP_LIMIT 0x3A000 # 应用区上限改成自己分区表里的值别照抄 def hex_top_addr(path: str) - int: 遍历 Intel HEX返回所有数据记录覆盖到的最高地址。 top 0 with open(path, r, encodingutf-8, errorsignore) as f: for line in f: line line.strip() if not line.startswith(:): continue raw bytes.fromhex(line[1:]) length raw[0] addr (raw[1] 8) | raw[2] rectype raw[3] if rectype 0x00: # 0x00 是数据记录其余类型不影响地址占用 top max(top, addr length) elif rectype 0x04: # 0x04 扩展线性地址高 16 位要左移拼接 # 这里只做上限判断遇到扩展地址记录时把高位记下来即可 pass return top if __name__ __main__: top hex_top_addr(sys.argv[1]) left APP_LIMIT - top print(ftop0x{top:08X} limit0x{APP_LIMIT:08X} free{left} bytes) sys.exit(0 if left 0 else 1)关键参数只有一个APP_LIMIT它的值必须来自你自己的分区表不是随便写的常数。脚本里的rectype 0x00判断的是数据记录只有这一类才真正占用 Flash 地址0x04那条分支是留给你扩展高位的如果固件地址超过 64KB 就必须补全否则算出来的上限会偏小反而误报。把这个脚本挂到编译之后跑一次返回非零就中断构建。养成习惯之后加功能时会不自觉地关注体积增长比事后救火强。3.4 烧录与上电验证两个判断标准烧录一般有两条路串口 ISP 和调试器。串口 ISP 需要把启动脚拉到指定电平再上电让芯片进下载模式调试器则是直接连 SWD 口能顺带在线调试。第一次建议用调试器出问题能看到芯片有没有起来量产和维护用串口不依赖调试器。烧完之后的验证分两步。第一步看串口日志上电后有没有打印启动信息初始化到哪一步有没有报错。日志停在哪一行问题就在那附近。第二步用手机端的通用 BLE 调试 App 扫描看能不能扫到设备名信号强度是否正常服务列表里有没有你预期的 UUID。判断标准要具体能扫到但连不上问题在连接参数或配对配置能连上但服务列表是空的问题在属性表注册顺序扫都扫不到先查广播使能有没有调用再查天线。这三条分清楚排查就不会乱撞。4. 自定义 GATT 服务广播数据、属性表与连接参数例程能跑通只是起点真正落地时一定要加自己的服务和特征值。这章讲三件事广播包 31 字节怎么分配、属性表怎么注册出一个最小可用的自定义服务、连接参数和 MTU 怎么先测再定。最后补一段低功耗配置因为很多项目死在「功能都对功耗超标」这一步。4.1 广播包与扫描响应31 字节怎么分配传统广播包上限 31 字节每一段都由「1 字节长度 1 字节类型 内容」组成长度字节不包含它自己。BLE 5.2 支持扩展广播可以超过 31 字节但手机端的兼容性和模组侧的支持度都不统一实际项目里我一般还是按 31 字节来规划把厂商自定义数据放到扫描响应里。/* 广播数据长度字节 1(类型) 内容长度 */ static uint8_t adv_payload[] { 0x02, 0x01, 0x06, /* Flags通用可发现不支持 BR/EDR */ 0x05, 0x09, P, B, 0, 3, /* 0x09 完整设备名长度 14 */ 0x03, 0x03, 0x0F, 0x18, /* 0x03 完整 16bit UUID 列表 */ }; /* 扫描响应单独一包也限 31 字节厂商自定义字段放这里更宽松 */ static uint8_t scan_rsp[] { 0x06, 0xFF, 0x34, 0x12, 0x01, 0x02, /* 0xFF 厂商自定义前两字节是厂商 ID(小端) */ }; /* 使能广播函数名以实际 SDK 为准 */ ble_gap_adv_start(adv_payload, sizeof(adv_payload), scan_rsp, sizeof(scan_rsp), 100 /* 广播间隔 ms100~500 之间按需取 */);最容易错的地方是长度字节。比如设备名是 4 个字符那么长度应该是 5类型 1 字节 名字 4 字节写成 4 会把名字最后一个字符吃掉手机端显示成三个字母看着像编码问题。加一段内容就重新数一遍别凭感觉。广播间隔这个参数要权衡调小被发现更快但平均功耗直线上升调到 500 ms 以上某些手机的扫描窗口覆盖不到会表现为「偶尔能扫到」。100~300 ms 是常见的起步区间。4.2 属性表注册一个自定义服务的最小闭环GATT 服务在代码里就是一张属性表表项顺序决定 handle 顺序handle 又是客户端读写的寻址依据。所以顺序不能乱中间也不能插空项。一个能读、能开通知的最小服务需要四项服务声明、特征值声明、特征值本身、CCCD。/* 自定义 128bit 服务的属性表顺序即 handle 递增顺序 */ static const att_db_item_t user_db[] { /* 1. 服务声明主服务 128bit UUID */ { .type ATT_TYPE_PRIMARY_SERVICE, .uuid_len 16, .uuid USER_SVC_UUID, .perm ATT_PERM_READ }, /* 2. 特征值声明属性位决定客户端能不能开通知这里给读通知 */ { .type ATT_TYPE_CHARACTERISTIC, .uuid_len 16, .uuid USER_CHAR_UUID, .perm ATT_PERM_READ, .value { .props ATT_PROP_READ | ATT_PROP_NOTIFY } }, /* 3. 特征值本身max_len 要和 MTU 协商结果对齐别写成 512 占内存 */ { .type ATT_TYPE_CHAR_VALUE, .uuid_len 16, .uuid USER_CHAR_UUID, .perm ATT_PERM_READ, .value { .buf user_val, .len sizeof(user_val), .max_len 20 } }, /* 4. CCCD客户端写 0x0001 开通知0x0000 关 */ { .type ATT_TYPE_CCCD, .perm ATT_PERM_READ | ATT_PERM_WRITE, .value { .buf user_cccd, .len 2 } }, }; /* 写回调里按 handle 分派handle 用注册后的返回值别写死数字 */ static void on_attr_write(uint16_t handle, const uint8_t *data, uint16_t len) { if (handle user_cccd_handle) { user_notify_en (len 2) (data[0] 0x01); /* 开/关通知 */ } else if (handle user_val_handle) { /* 业务数据处理注意 len 可能小于 max_len */ handle_user_cmd(data, len); } }三处说明。max_len 20对应默认 MTU 23 减去 3 字节协议开销如果后面协商到更大 MTU这个值要同步放开但在没协商之前设太大只是白占 RAM。CCCD 必须占一个独立表项漏了它客户端开不了通知表现是「订阅了但收不到数据」。回调里判断 handle 一定要用注册后返回的变量写死数字在后期插入新服务时必然错位而且错位之后的行为很诡异——写 A 特征值却触发了 B 的逻辑。注册完之后手机端能看到服务但点开可能是空的。这种情况先确认属性表里的 UUID 字节序128 位 UUID 在内存里通常按小端倒序存放写反了客户端解析出的 UUID 和你以为的不一样服务会被当成未知服务折叠起来。4.3 连接参数与 MTU先测再定别抄别人的数连接参数直接决定吞吐、延迟和功耗三者互相牵制。参数没有通用最优值只能按场景定。先把几个参数的物理含义和边界搞清楚再用实测收敛。参数常见取值影响注意广播间隔100~500 ms被发现速度、平均功耗低于 100 ms 收益不明显功耗接近翻倍最小连接间隔15~30 ms吞吐、响应延迟部分手机端会向上收敛到它认可的粒度从机延迟0~4空闲时省电设太大配合小间隔写操作容易超时监督超时2~6 s断链判定速度必须大于 (1延迟) × 间隔 × 2否则频繁误判断链MTU23 或 247单包有效负载默认 23即 20 字节协商后按实际值算调试连接问题光看手机界面不够得把空中抓到的广播和连接行为拆开看。下面这段脚本用来解析抓包工具或串口导出的广播十六进制串检查 AD 结构是否合法、有没有超长。#!/usr/bin/env python3 把广播原始 hex 逐条拆成 AD 结构定位长度写错或类型写错的那一段。 def parse_adv(hexstr: str) - None: data bytes.fromhex(hexstr.replace( , ).replace(\n, )) if len(data) 31: print(f[警告] 长度 {len(data)} 超过传统广播包 31 字节上限) i 0 while i len(data): ln data[i] if ln 0: # 0 表示后续是填充直接结束 break if i 1 len(data): print(f[错误] 偏移 {i} 处长度 {ln} 越界包被截断) return ad_type data[i 1] value data[i 2: i 1 ln] print(foff{i:3} len{ln:3} type0x{ad_type:02X} value{value.hex( )}) i ln 1 if __name__ __main__: # 把抓到的广播 hex 粘进来空格可有可无 parse_adv(02 01 06 05 09 50 42 30 33 03 03 0F 18)i ln 1是核心跳过一个长度字节加 ln 个字节的内容。ln 0提前退出是因为广播包尾部常用零填充。这段脚本不依赖任何第三方库抓包工具导出的数据直接粘贴就能用定位「名字少了最后一个字母」「UUID 类型写成 0x02」这类问题比肉眼数快得多。MTU 协商的结果要在连接建立后主动打印一次。有些平台默认不协商你以为能发 200 字节实际每包只发出去 20 字节剩余全被截断表现是「指令发一半设备不响应」。日志里加上协商前后的 MTU 值这个问题一眼就能看出来。4.4 低功耗休眠、GPIO 与广播间隔的取舍功耗超标是二次开发里最典型的翻车点。规格书上的数字通常是「仅射频MCU 广播」的理想值你板子上多一个上拉电阻、多一路常开的串口数字就完全不一样。第一件事是确认休眠真的进去了。很多 SDK 有休眠前后的钩子函数在里面翻转一个 GPIO用示波器看这个脚的占空比就知道实际醒着多久。比看电流平均值直观得多。第二件事是 GPIO 状态。休眠时悬空的输入脚会因电平不确定产生漏电上拉电阻在外部有下拉时会持续耗流。原则是不用的脚配置成模拟或下拉输出外部上拉能省则省能加大阻值就加大。第三件事是外设时钟。串口、定时器、ADC 在休眠前该关的关掉尤其是串口——调试完忘记关一晚掉几百微安很常见。广播间隔的调整放在最后先把漏电堵住再谈间隔否则你怎么调间隔都对不上规格书。5. 常见问题排查烧录、连接、功耗的五条踩坑记录有些坑几乎每个项目都会踩一遍写在这里省得重复试错。下面五条都按「现象 → 原因 → 解决」组织遇到相似症状可以直接对照。需要强调一点BLE 调试最忌讳同时改多个变量一次只改一处改完立刻验证否则问题解决了你也不知道是哪一步生效的。5.1 烧录报握手失败换线换板都没用现象烧录工具能识别到串口点开始后几秒提示握手失败或超时换 USB 线、换板子症状一样。原因多半是没进下载模式。串口 ISP 需要在复位释放的瞬间采样启动脚电平手动按键的时序经常对不上另一种可能是烧录工具版本与模组内部固件版本不匹配协议对不上同样表现为握手失败。解决先改成调试器烧录排除时序问题确认固件本身没问题如果只能用串口用工具里的「自动进入下载模式」选项让工具通过 DTR/RTS 控制复位和启动脚别手动按。工具版本按资料包tool/目录里配套的那份用不要用电脑上残留的旧版。5.2 广播数据改了手机扫到的还是旧名字现象代码里改了设备名并重新编译烧录手机端扫出来还是原来那个名字换一台手机也一样。原因缓存。手机端对已配对或曾扫描到的设备会缓存 GATT 和广播信息Android 侧尤其明显另一种情况是编译产物没真正烧进去烧录的是旧 hex。解决先在手机蓝牙设置里删除该设备记录或在调试 App 里清缓存再扫同时核对烧录日志里的固件时间和大小确认烧的是新产物。判断是不是缓存最直接的办法是换一台从没扫过这个设备的手机。5.3 能连上几秒钟后自动断开现象连接建立成功服务也能看到三五秒后连接断开反复重连。原因监督超时配置不合理最常见。监督超时必须大于 (1 从机延迟) × 连接间隔 × 2如果从机延迟设成 4、间隔 30 ms超时至少要 300 ms 以上配成 200 ms 就会周期性误判断链。其次是应用层在连接回调里做了耗时操作阻塞了协议栈的事件处理。解决先把从机延迟改成 0、监督超时放大到 4 s 验证连接是否稳定稳定后逐步往回调找到临界点再留一倍余量。回调里不要做 Flash 擦写、不要长延时重活丢到主循环里做。5.4 功耗比规格书高一个数量级现象休眠电流实测几百微安规格书写的是个位数微安。原因串口没关、GPIO 悬空漏电、调试日志没关、外部上拉电阻常供这四样占了绝大多数。日志这一项最隐蔽因为功能上完全正常。解决按顺序排查——先关日志测一次再关串口测一次再把所有未用 GPIO 配成模拟态测一次。每关一项测一次电流变化最大的那项就是主因。用 GPIO 翻转配合示波器看唤醒占空比比盯着万用表数字猜有效。5.5 AT 固件和 SDK 固件混着烧功能莫名其妙现象按 SDK 例程烧完串口发 AT 指令没反应或者刷回 AT 固件后自定义服务消失但广播名还是自己改的那个。原因AT 固件和 SDK 固件是两套完全不同的应用共用同一块 Flash 但入口和分区不同。混烧之后配置区残留旧参数表现就是「一半新一半旧」。解决切换固件类型前先做一次全片擦除别只擦应用区。切换完成后用默认配置跑一遍基础功能确认干净了再烧自己的业务固件。产线上尤其要注意返修板子回炉时先擦再写。6. OTA 与产线固化把「能跑」变成「能出厂」样机能跑通和能出厂之间隔着 OTA 和参数固化两件事。这两块资料包里不一定有现成脚本但基于里面的例程补起来不难。OTA 的核心是分区。常见做法是应用区 备份区双 bank新固件先整包写进备份区校验通过后把启动标志指过去重启由 bootloader 搬运或直接跳转。判断 OTA 是否可靠别只看「升级成功」这一条要专门测三个场景升级过程中断电、升级包被截断、降级回滚。断电测试最容易被跳过但它恰恰是现场最容易发生的——用户在升级时锁屏走了。/* OTA 状态机的最小实现关键是每一步都落标志位掉电后可恢复 */ typedef enum { OTA_IDLE, OTA_RECEIVING, OTA_VERIFYING, OTA_READY, OTA_FAIL } ota_state_t; static void ota_on_packet(const uint8_t *data, uint16_t len, uint32_t offset) { /* 1. 先写备份区绝不直接覆盖运行区 */ if (flash_write(OTA_BAK_ADDR offset, data, len) ! 0) { ota_set_state(OTA_FAIL); /* 写失败立刻标记下次上电重来 */ return; } /* 2. 每包写完更新进度标志掉电后从标志处续传 */ ota_set_progress(offset len); ota_set_state(OTA_RECEIVING); } static void ota_on_finish(uint32_t total_len) { ota_set_state(OTA_VERIFYING); /* 3. 整包 CRC 校验通过才允许切启动标志 */ if (crc32_check(OTA_BAK_ADDR, total_len) 0) { ota_set_state(OTA_READY); ota_commit_boot_flag(); /* 这一步之后才真正生效 */ } else { ota_set_state(OTA_FAIL); /* 校验失败保留旧固件不切标志 */ } }这段代码的重点不在语法在顺序先写备份区、再校验、最后切标志。把切标志放到校验之前一次传输错误就能让设备变砖现场只能返修。进度标志要落在独立的配置区别和固件放一起否则搬运固件时会一起被擦掉。产线固化是另一件事。每台设备需要写入唯一的 MAC、设备名、校准参数和密钥这些不该靠改代码重新编译。常规做法是在 Flash 里划一小块参数区产线工具通过串口指令写入应用启动时读取。参数区要带版本号和 CRC升级固件后参数仍然有效参数格式变了则按版本号做兼容迁移。验证方法我一般分三层单机功能回归广播、连接、读写、通知四项走一遍、异常注入断电、断链、超长包、错 CRC、小批量老化十几台连续跑 24 小时统计断链次数和电流波动。三层都过才敢说这批固件能出厂。从那以后我每次改完固件都强制走一遍「擦全片 → 烧固件 → 断电重启 → 手机端删缓存重扫」这四步不管改动多小。省下的那两分钟往往要用两天去找回来。希望帮到你。本文还有配套的精品资源点击获取