簡介面向使用安信可PB-03藍(lán)牙模塊進(jìn)行二次開發(fā)的嵌入式工程師與物聯(lián)網(wǎng)學(xué)習(xí)者這份資料合集圍繞PHY6252低功耗藍(lán)牙SoC展開重點(diǎn)解決BLE5.2開發(fā)環(huán)境搭建、外設(shè)驅(qū)動(dòng)參考與固件升級(jí)等常見需求。壓縮包共1163個(gè)文件、約66.23MB以C源碼與頭文件為主體輔以Keil工程文件、鏈接腳本、啟動(dòng)匯編、INI配置、批處理腳本及PDF文檔覆蓋從工程配置到編譯燒錄的多個(gè)環(huán)節(jié)并包含串口AT指令、FOTA升級(jí)與低功耗休眠等相關(guān)參考材料。已有2248人學(xué)習(xí)說明其在PB-03二次開發(fā)人群中具有一定參考價(jià)值。讀者可從中獲取較完整的SDK目錄與示例工程結(jié)構(gòu)借助源碼與配置理解UART、GPIO、ADC、PWM、I2C、SPI等接口的調(diào)用方式對(duì)照文檔和工程文件排查編譯、鏈接與下載問題也可為Windows開發(fā)環(huán)境下的二次開發(fā)與固件遠(yuǎn)程升級(jí)提供直接可用的素材。1. PB03 藍(lán)牙 5.2 二次開發(fā)資料一份資料包能省掉哪些摸索手上有一塊 PB03 模組想讓它從「能廣播」走到「能跟自己的 App 收發(fā)自定義數(shù)據(jù)」中間這段路很多人卡過兩三天不知道 SDK 該從哪個(gè)文件下手廣播包改完手機(jī)掃不到燒錄工具一連上就報(bào)握手失敗。PB03 藍(lán)牙 5.2 二次開發(fā)資料這套文檔資料的價(jià)值就在這兒——它把 SDK 工程、硬件設(shè)計(jì)文件、AT 指令手冊(cè)、燒錄工具和幾套可編譯的例程收在一起拿到手就能編譯、能下載、能跟自己的板子對(duì)比差異不是芯片手冊(cè)的中文翻譯版。適合三類人第一次碰 BLE 5.2 模組、需要兩周內(nèi)出樣機(jī)的固件工程師要畫底板、核對(duì)引腳復(fù)用和天線凈空的硬件工程師以及做方案選型、想判斷這顆模組扛不扛得住自己場景的技術(shù)負(fù)責(zé)人。2. 資料包拆解SDK 目錄、協(xié)議棧分層與二次開發(fā)的可改邊界二次開發(fā)資料包最容易出現(xiàn)的浪費(fèi)是不是「東西不夠」而是「不知道哪份東西該信」。同一個(gè)功能AT 指令手冊(cè)里有一套說法例程里又有一套寫法SDK 里的宏開關(guān)還是第三套。第 2 章先把包里的結(jié)構(gòu)捋清哪些目錄只讀、哪些是主要修改區(qū)域、協(xié)議棧哪一層能改哪一層碰了就麻煩以及硬件那份資料該在什么時(shí)候看。等把邊界劃清楚后面編譯、燒錄、調(diào) GATT 才有參照系不然每改一行代碼都像在賭。2.1 目錄分工哪幾個(gè)文件夾看完就該鎖上PB03 這類模組的二次開發(fā)包目錄結(jié)構(gòu)基本是固定的幾個(gè)部分區(qū)別只在命名習(xí)慣。我一般拿到包先做一件事ls一遍把每個(gè)目錄歸到「只讀」和「會(huì)改」兩類里心里有個(gè)地圖再動(dòng)手。下面這張表是按常見組織方式整理的實(shí)際包里的名字可能差一兩個(gè)字但功能對(duì)應(yīng)得上。目錄常見命名典型內(nèi)容二次開發(fā)時(shí)的用途是否修改doc/數(shù)據(jù)手冊(cè)、AT 指令手冊(cè)、天線設(shè)計(jì)指南、功耗實(shí)測表查引腳定義、指令集、射頻指標(biāo)只讀sdk/協(xié)議棧庫文件、應(yīng)用層源碼、Keil 工程、鏈接腳本改業(yè)務(wù)邏輯、加自定義服務(wù)主要修改區(qū)域sdk/lib/預(yù)編譯的協(xié)議棧與射頻驅(qū)動(dòng).lib/.a只調(diào)用不反編譯只讀hw/原理圖、PCB 封裝庫、BOM、匹配網(wǎng)絡(luò)參數(shù)畫底板、核對(duì)引腳復(fù)用只讀tool/燒錄上位機(jī)、串口助手、固件合并腳本、量產(chǎn)工具下載固件、看日志、批量寫參數(shù)只讀example/透傳、主從一體、HID、OTA 四類例程抄配置、對(duì)比差異、當(dāng)回歸基線可改但先備份表里最關(guān)鍵的一行是sdk/lib/。協(xié)議棧以預(yù)編譯庫的形式給出意味著鏈路層、射頻校準(zhǔn)、跳頻這些邏輯你既看不到也改不了出問題只能從應(yīng)用層參數(shù)倒推。這不是資料包偷懶是認(rèn)證和射頻一致性要求的常規(guī)做法。知道自己改不到那一層排查思路就會(huì)變——連不上先懷疑參數(shù)和時(shí)序而不是去翻協(xié)議棧源碼。動(dòng)手的第一步我個(gè)人的習(xí)慣是把sdk/整份復(fù)制一份出來改個(gè)名字比如sdk_myproj/原始包保持原樣。原因很實(shí)際二次開發(fā)過程中一定會(huì)改宏、改鏈接地址、刪例程改亂了想回退重新解壓一遍是最快的后悔藥。同理example/里的透傳例程建議單獨(dú)復(fù)制一份當(dāng)「金標(biāo)準(zhǔn)」你自己的工程跑不通時(shí)把它燒進(jìn)去對(duì)比能立刻區(qū)分是硬件問題還是代碼問題——這個(gè)動(dòng)作在兩塊板子都調(diào)不通的時(shí)候能救命。還要提醒一個(gè)細(xì)節(jié)很多包的doc/里放著兩三個(gè)版本的 AT 指令手冊(cè)文件名只差一個(gè)后綴。別默認(rèn)最新的那份就對(duì)應(yīng)當(dāng)前固件。判斷方法是看手冊(cè)里描述的指令集和你手上模組實(shí)際返回的響應(yīng)是否一致隨手發(fā)一條查詢指令回什么就知道版本對(duì)不對(duì)得上。這個(gè)核對(duì)只花兩分鐘能省掉后面半小時(shí)的自我懷疑。2.2 協(xié)議棧分層GAP 廣播、GATT 屬性、應(yīng)用回調(diào)各管什么BLE 的分層概念網(wǎng)上一搜一大把但落到「我到底能改哪一行」還是得按這個(gè)資料包的實(shí)際結(jié)構(gòu)重新講一遍。從下往上看控制器層含射頻、鏈路層、跳頻以庫形式封裝你只通過 API 配置參數(shù)主機(jī)層的 GAP 負(fù)責(zé)廣播、掃描、連接建立GATT 負(fù)責(zé)屬性的組織和讀寫再往上是你自己的應(yīng)用邏輯和串口協(xié)議。二次開發(fā)里 90% 的工作量集中在 GATT 和 GAP 參數(shù)這兩塊。廣播包內(nèi)容的填充、連接間隔的取值、自定義服務(wù)屬性表的順序、CCCD 的讀寫回調(diào)——這些全在應(yīng)用層改起來不用碰庫。反過來凡是涉及「連接建立之前的射頻行為」和「鏈路穩(wěn)定性」的比如發(fā)射功率、射頻信道、白名單過濾的底層實(shí)現(xiàn)基本都在庫里你只能通過上層參數(shù)間接影響。新手最容易誤改的是啟動(dòng)文件和鏈接腳本。它們長得像普通源碼里面也確實(shí)有可以改的數(shù)字但改錯(cuò)的表現(xiàn)往往不是編譯報(bào)錯(cuò)而是燒進(jìn)去之后跑飛、或者廣播正常但一連接就復(fù)位。我見過有人為了省幾 KB 空間去動(dòng)鏈接腳本里的段地址結(jié)果應(yīng)用區(qū)和 OTA 備份區(qū)重疊升級(jí)一次直接變磚。這類文件在包里通常放在sdk/project/下面看到.sct、.ld、startup_*.s這種后綴動(dòng)之前先備份改完必須做一次完整的燒錄和連接驗(yàn)證。另一處邊界是中斷優(yōu)先級(jí)。協(xié)議棧對(duì)射頻中斷和定時(shí)器中斷的響應(yīng)時(shí)間有隱含要求應(yīng)用層如果把串口中斷優(yōu)先級(jí)配得比射頻還高重負(fù)載時(shí)會(huì)出現(xiàn)連接間隔抖動(dòng)甚至斷鏈。資料包里的例程一般給了一套可用的優(yōu)先級(jí)配置直接沿用比自己重新分配更穩(wěn)非要改就一次只改一個(gè)改完拿連接穩(wěn)定性壓測一遍。2.3 工具鏈版本對(duì)齊編譯器和燒錄工具比你想的挑嵌入式資料包最容易被忽略的一句話是「本 SDK 在某某版本下驗(yàn)證通過」。這句話不是免責(zé)聲明是硬約束。編譯器版本差異會(huì)帶來兩個(gè)后果一是 C 庫行為不同導(dǎo)致的隱性問題比如某些優(yōu)化等級(jí)下的對(duì)齊訪問二是生成的代碼體積變化本來剛好塞進(jìn)應(yīng)用區(qū)的固件突然超了。具體要核對(duì)三項(xiàng)編譯器主版本、器件支持包、燒錄上位機(jī)版本。前兩項(xiàng)決定能不能編譯出行為一致的固件第三項(xiàng)決定能不能把固件寫進(jìn)去。燒錄工具的版本和模組內(nèi)部固件版本之間通常有協(xié)議對(duì)應(yīng)關(guān)系版本差太多會(huì)表現(xiàn)成「能識(shí)別串口但握手失敗」這種報(bào)錯(cuò)信息往往很含糊看著像硬件壞了其實(shí)換個(gè)工具版本就好。串口驅(qū)動(dòng)的坑也值得一提。同一臺(tái)電腦上裝過多個(gè)串口工具時(shí)虛擬串口偶爾會(huì)被別的軟件占用表現(xiàn)是燒錄工具提示打不開端口但設(shè)備管理器里看著一切正常。遇到這種情況先關(guān)掉所有串口助手再試別急著懷疑板子。2.4 硬件資料怎么用天線凈空和電源紋波比原理圖重要hw/目錄里的原理圖很多人掃一眼就跳過直接照著引腳表畫底板。真正會(huì)被忽略又最容易出事的是兩塊天線的凈空區(qū)和電源的紋波要求。天線部分資料里一般會(huì)給一個(gè)推薦布局模組天線端到板邊要保持一段無銅無走線的凈空底下不走線不鋪銅附近不要放電池和金屬結(jié)構(gòu)件。這段距離具體多少看包里的天線設(shè)計(jì)說明但「凈空」這件事必須當(dāng)真。我踩過一次底板為了塞結(jié)構(gòu)把電池挪到天線正下方傳導(dǎo)測試一切正常實(shí)際通信距離掉了一大半查了兩天才定位到。電源部分BLE 模組在廣播瞬間有脈沖電流LDO 選型偏小或者去耦電容離得太遠(yuǎn)會(huì)出現(xiàn)「空閑正常、一廣播就復(fù)位」。資料里的參考設(shè)計(jì)給了電容位置和容值照著抄就行別自己優(yōu)化。表里這幾個(gè)點(diǎn)硬件階段確認(rèn)一次能省掉固件階段一半的玄學(xué)問題。檢查項(xiàng)資料里看哪硬件階段怎么驗(yàn)天線凈空天線設(shè)計(jì)指南目視 卡尺凈空區(qū)內(nèi)無銅無器件匹配網(wǎng)絡(luò)原理圖匹配電路按參考值貼不自行改容感值電源去耦參考設(shè)計(jì)布局電容靠近模組電源腳地平面完整復(fù)位與啟動(dòng)腳引腳定義表上電時(shí)序符合要求不懸空調(diào)試串口引腳復(fù)用表留出測試點(diǎn)方便抓日志3. 跑通第一個(gè)工程宏配置、命令行編譯與燒錄驗(yàn)證把資料包里的例程編譯通過、燒進(jìn)去、手機(jī)能掃到這三步做完心里才算有底。這章按順序走一遍先在 IDE 里改對(duì)幾個(gè)關(guān)鍵宏再用命令行把編譯過程腳本化后面接自動(dòng)化構(gòu)建也方便然后校驗(yàn)固件尺寸別越界最后燒錄并驗(yàn)證廣播。每一步都給出判斷標(biāo)準(zhǔn)做完能明確知道「這一步過了」。3.1 打開工程先改三個(gè)宏別急著編譯第一次打開 Keil 工程不要直接點(diǎn)編譯。先找工程配置里的預(yù)定義宏通常在Options for Target的 C/C 頁確認(rèn)三個(gè)方向上的開關(guān)日志輸出、休眠使能、設(shè)備名與地址來源。日志開關(guān)決定你能不能看到串口打印。出廠狀態(tài)的例程有時(shí)為了省電把日志全關(guān)了燒進(jìn)去串口一片安靜你會(huì)以為程序沒跑起來實(shí)際上是沒打印。調(diào)試階段先打開功能驗(yàn)證完再關(guān)掉關(guān)掉之前記得測一次功耗因?yàn)槿罩颈旧砗芎碾?。休眠使能決定空閑時(shí)會(huì)不會(huì)進(jìn)低功耗。帶休眠調(diào)試連接問題很痛苦因?yàn)閱拘研枰獣r(shí)間某些時(shí)序會(huì)被拉長。我一般調(diào)試期先關(guān)休眠等連接穩(wěn)定了再打開專門測一輪。設(shè)備名和地址來源這一項(xiàng)很多 SDK 用宏來控制是「用芯片內(nèi)部地址」還是「用代碼里寫死的地址」。如果兩片模組廣播出來名字和地址完全一樣手機(jī)端會(huì)出現(xiàn)只能連上一片的情況看著像連接問題其實(shí)是配置重復(fù)。/* 這幾個(gè)開關(guān)通常定義在工程宏或 board_cfg.h 里名字隨 SDK 有差異 */ #define CFG_LOG_EN 1 /* 調(diào)試期開量產(chǎn)關(guān)關(guān)掉能省下幾 mA */ #define CFG_SLEEP_EN 0 /* 調(diào)試期關(guān)穩(wěn)定后再開 */ #define CFG_USE_CHIP_MAC 1 /* 1用芯片唯一地址0用下面寫死的地址 */ #define CFG_DEV_NAME PB03-DEV /* 廣播里的設(shè)備名長度計(jì)入廣播包 */ #define CFG_UART_BAUD 115200 /* 調(diào)試串口波特率和上位機(jī)保持一致 */這段配置不需要解釋太多重點(diǎn)是養(yǎng)成「先確認(rèn)再編譯」的順序。血淚經(jīng)驗(yàn)是改代碼之前先確認(rèn)宏改完之后記錄改了什么否則三五天后自己都不記得當(dāng)初為什么把這行設(shè)成 0。3.2 命令行編譯把錯(cuò)誤從日志里撈出來IDE 里點(diǎn)編譯適合調(diào)試但只要開始多人協(xié)作或者想把構(gòu)建掛到自動(dòng)流程里命令行編譯就必須能跑通。資料包里的工程是標(biāo)準(zhǔn) Keil 工程可以用它的命令行模式批量編譯。#!/usr/bin/env bash # 一鍵編譯并提取關(guān)鍵信息適合本地快速驗(yàn)證或掛到構(gòu)建機(jī) set -euo pipefail KEIL_BIN/c/Keil_v5/UV4/UV4.exe # 按本機(jī)安裝路徑改注意 Windows 路徑在 bash 下的寫法 PROJsdk_myproj/project/pb03_app.uvprojx # 工程文件相對(duì)路徑要先 cd 到倉庫根目錄 LOGbuild/compile_$(date %Y%m%d_%H%M%S).log mkdir -p build build_log # -b 批量編譯(不彈窗) -j0 抑制對(duì)話框 -o 輸出完整日志 $KEIL_BIN -b $PROJ -j0 -o $LOG || true # Keil 的進(jìn)程返回碼不區(qū)分警告和錯(cuò)誤掃日志比看返回碼可靠 echo ---- 錯(cuò)誤與告警 ---- grep -nE error:|Error:|Warning: $LOG | tail -n 30 || echo 無錯(cuò)誤 echo ---- 代碼體積 ---- grep -nE Program Size|Total RO|Total RW $LOG | tail -n 8 || true幾處說明。-b是批處理編譯模式不彈界面適合腳本調(diào)用-j0用來抑制可能出現(xiàn)的模態(tài)對(duì)話框不然在無人值守的構(gòu)建機(jī)上會(huì)卡住等點(diǎn)擊-o把完整日志落盤這是排查的關(guān)鍵——IDE 窗口里滾過去的告警往往被忽略落盤之后grep一遍才發(fā)現(xiàn)有「隱式聲明」這類會(huì)埋雷的告警。|| true是有意加的。Keil 命令行在某些版本下即使編譯成功也返回非零碼直接set -e會(huì)把腳本中斷在成功的那一步。真正判斷成敗看日志里的error:計(jì)數(shù)這也是為什么腳本里要單獨(dú) grep 一遍。如果編譯報(bào)的是「找不到某個(gè)頭文件」九成是工程里的相對(duì)路徑和你移動(dòng)目錄之后的實(shí)際位置對(duì)不上。解決辦法不是改代碼里的#include而是回到工程配置的 Include Paths 里修路徑這樣所有引用同一處配置的源文件都能一起好。3.3 固件尺寸校驗(yàn)別讓應(yīng)用區(qū)越界這一步很多人省略直到 OTA 升級(jí)失敗才發(fā)現(xiàn)固件的末尾壓到了備份區(qū)。做二次開發(fā)尤其是加了自定義服務(wù)和日志之后代碼體積是會(huì)長的靠肉眼判斷不靠譜寫個(gè)腳本卡住更穩(wěn)妥。#!/usr/bin/env python3 按分區(qū)表校驗(yàn)編譯產(chǎn)物是否越過應(yīng)用區(qū)上限防止燒進(jìn)去跑飛或 OTA 變磚。 import sys APP_LIMIT 0x3A000 # 應(yīng)用區(qū)上限改成自己分區(qū)表里的值別照抄 def hex_top_addr(path: str) - int: 遍歷 Intel HEX返回所有數(shù)據(jù)記錄覆蓋到的最高地址。 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 是數(shù)據(jù)記錄其余類型不影響地址占用 top max(top, addr length) elif rectype 0x04: # 0x04 擴(kuò)展線性地址高 16 位要左移拼接 # 這里只做上限判斷遇到擴(kuò)展地址記錄時(shí)把高位記下來即可 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)關(guān)鍵參數(shù)只有一個(gè)APP_LIMIT它的值必須來自你自己的分區(qū)表不是隨便寫的常數(shù)。腳本里的rectype 0x00判斷的是數(shù)據(jù)記錄只有這一類才真正占用 Flash 地址0x04那條分支是留給你擴(kuò)展高位的如果固件地址超過 64KB 就必須補(bǔ)全否則算出來的上限會(huì)偏小反而誤報(bào)。把這個(gè)腳本掛到編譯之后跑一次返回非零就中斷構(gòu)建。養(yǎng)成習(xí)慣之后加功能時(shí)會(huì)不自覺地關(guān)注體積增長比事后救火強(qiáng)。3.4 燒錄與上電驗(yàn)證兩個(gè)判斷標(biāo)準(zhǔn)燒錄一般有兩條路串口 ISP 和調(diào)試器。串口 ISP 需要把啟動(dòng)腳拉到指定電平再上電讓芯片進(jìn)下載模式調(diào)試器則是直接連 SWD 口能順帶在線調(diào)試。第一次建議用調(diào)試器出問題能看到芯片有沒有起來量產(chǎn)和維護(hù)用串口不依賴調(diào)試器。燒完之后的驗(yàn)證分兩步。第一步看串口日志上電后有沒有打印啟動(dòng)信息初始化到哪一步有沒有報(bào)錯(cuò)。日志停在哪一行問題就在那附近。第二步用手機(jī)端的通用 BLE 調(diào)試 App 掃描看能不能掃到設(shè)備名信號(hào)強(qiáng)度是否正常服務(wù)列表里有沒有你預(yù)期的 UUID。判斷標(biāo)準(zhǔn)要具體能掃到但連不上問題在連接參數(shù)或配對(duì)配置能連上但服務(wù)列表是空的問題在屬性表注冊(cè)順序掃都掃不到先查廣播使能有沒有調(diào)用再查天線。這三條分清楚排查就不會(huì)亂撞。4. 自定義 GATT 服務(wù)廣播數(shù)據(jù)、屬性表與連接參數(shù)例程能跑通只是起點(diǎn)真正落地時(shí)一定要加自己的服務(wù)和特征值。這章講三件事廣播包 31 字節(jié)怎么分配、屬性表怎么注冊(cè)出一個(gè)最小可用的自定義服務(wù)、連接參數(shù)和 MTU 怎么先測再定。最后補(bǔ)一段低功耗配置因?yàn)楹芏囗?xiàng)目死在「功能都對(duì)功耗超標(biāo)」這一步。4.1 廣播包與掃描響應(yīng)31 字節(jié)怎么分配傳統(tǒng)廣播包上限 31 字節(jié)每一段都由「1 字節(jié)長度 1 字節(jié)類型 內(nèi)容」組成長度字節(jié)不包含它自己。BLE 5.2 支持?jǐn)U展廣播可以超過 31 字節(jié)但手機(jī)端的兼容性和模組側(cè)的支持度都不統(tǒng)一實(shí)際項(xiàng)目里我一般還是按 31 字節(jié)來規(guī)劃把廠商自定義數(shù)據(jù)放到掃描響應(yīng)里。/* 廣播數(shù)據(jù)長度字節(jié) 1(類型) 內(nèi)容長度 */ static uint8_t adv_payload[] { 0x02, 0x01, 0x06, /* Flags通用可發(fā)現(xiàn)不支持 BR/EDR */ 0x05, 0x09, P, B, 0, 3, /* 0x09 完整設(shè)備名長度 14 */ 0x03, 0x03, 0x0F, 0x18, /* 0x03 完整 16bit UUID 列表 */ }; /* 掃描響應(yīng)單獨(dú)一包也限 31 字節(jié)廠商自定義字段放這里更寬松 */ static uint8_t scan_rsp[] { 0x06, 0xFF, 0x34, 0x12, 0x01, 0x02, /* 0xFF 廠商自定義前兩字節(jié)是廠商 ID(小端) */ }; /* 使能廣播函數(shù)名以實(shí)際 SDK 為準(zhǔn) */ ble_gap_adv_start(adv_payload, sizeof(adv_payload), scan_rsp, sizeof(scan_rsp), 100 /* 廣播間隔 ms100~500 之間按需取 */);最容易錯(cuò)的地方是長度字節(jié)。比如設(shè)備名是 4 個(gè)字符那么長度應(yīng)該是 5類型 1 字節(jié) 名字 4 字節(jié)寫成 4 會(huì)把名字最后一個(gè)字符吃掉手機(jī)端顯示成三個(gè)字母看著像編碼問題。加一段內(nèi)容就重新數(shù)一遍別憑感覺。廣播間隔這個(gè)參數(shù)要權(quán)衡調(diào)小被發(fā)現(xiàn)更快但平均功耗直線上升調(diào)到 500 ms 以上某些手機(jī)的掃描窗口覆蓋不到會(huì)表現(xiàn)為「偶爾能掃到」。100~300 ms 是常見的起步區(qū)間。4.2 屬性表注冊(cè)一個(gè)自定義服務(wù)的最小閉環(huán)GATT 服務(wù)在代碼里就是一張屬性表表項(xiàng)順序決定 handle 順序handle 又是客戶端讀寫的尋址依據(jù)。所以順序不能亂中間也不能插空項(xiàng)。一個(gè)能讀、能開通知的最小服務(wù)需要四項(xiàng)服務(wù)聲明、特征值聲明、特征值本身、CCCD。/* 自定義 128bit 服務(wù)的屬性表順序即 handle 遞增順序 */ static const att_db_item_t user_db[] { /* 1. 服務(wù)聲明主服務(wù) 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 協(xié)商結(jié)果對(duì)齊別寫成 512 占內(nèi)存 */ { .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 關(guān) */ { .type ATT_TYPE_CCCD, .perm ATT_PERM_READ | ATT_PERM_WRITE, .value { .buf user_cccd, .len 2 } }, }; /* 寫回調(diào)里按 handle 分派handle 用注冊(cè)后的返回值別寫死數(shù)字 */ 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); /* 開/關(guān)通知 */ } else if (handle user_val_handle) { /* 業(yè)務(wù)數(shù)據(jù)處理注意 len 可能小于 max_len */ handle_user_cmd(data, len); } }三處說明。max_len 20對(duì)應(yīng)默認(rèn) MTU 23 減去 3 字節(jié)協(xié)議開銷如果后面協(xié)商到更大 MTU這個(gè)值要同步放開但在沒協(xié)商之前設(shè)太大只是白占 RAM。CCCD 必須占一個(gè)獨(dú)立表項(xiàng)漏了它客戶端開不了通知表現(xiàn)是「訂閱了但收不到數(shù)據(jù)」。回調(diào)里判斷 handle 一定要用注冊(cè)后返回的變量寫死數(shù)字在后期插入新服務(wù)時(shí)必然錯(cuò)位而且錯(cuò)位之后的行為很詭異——寫 A 特征值卻觸發(fā)了 B 的邏輯。注冊(cè)完之后手機(jī)端能看到服務(wù)但點(diǎn)開可能是空的。這種情況先確認(rèn)屬性表里的 UUID 字節(jié)序128 位 UUID 在內(nèi)存里通常按小端倒序存放寫反了客戶端解析出的 UUID 和你以為的不一樣服務(wù)會(huì)被當(dāng)成未知服務(wù)折疊起來。4.3 連接參數(shù)與 MTU先測再定別抄別人的數(shù)連接參數(shù)直接決定吞吐、延遲和功耗三者互相牽制。參數(shù)沒有通用最優(yōu)值只能按場景定。先把幾個(gè)參數(shù)的物理含義和邊界搞清楚再用實(shí)測收斂。參數(shù)常見取值影響注意廣播間隔100~500 ms被發(fā)現(xiàn)速度、平均功耗低于 100 ms 收益不明顯功耗接近翻倍最小連接間隔15~30 ms吞吐、響應(yīng)延遲部分手機(jī)端會(huì)向上收斂到它認(rèn)可的粒度從機(jī)延遲0~4空閑時(shí)省電設(shè)太大配合小間隔寫操作容易超時(shí)監(jiān)督超時(shí)2~6 s斷鏈判定速度必須大于 (1延遲) × 間隔 × 2否則頻繁誤判斷鏈MTU23 或 247單包有效負(fù)載默認(rèn) 23即 20 字節(jié)協(xié)商后按實(shí)際值算調(diào)試連接問題光看手機(jī)界面不夠得把空中抓到的廣播和連接行為拆開看。下面這段腳本用來解析抓包工具或串口導(dǎo)出的廣播十六進(jìn)制串檢查 AD 結(jié)構(gòu)是否合法、有沒有超長。#!/usr/bin/env python3 把廣播原始 hex 逐條拆成 AD 結(jié)構(gòu)定位長度寫錯(cuò)或類型寫錯(cuò)的那一段。 def parse_adv(hexstr: str) - None: data bytes.fromhex(hexstr.replace( , ).replace(\n, )) if len(data) 31: print(f[警告] 長度 {len(data)} 超過傳統(tǒng)廣播包 31 字節(jié)上限) i 0 while i len(data): ln data[i] if ln 0: # 0 表示后續(xù)是填充直接結(jié)束 break if i 1 len(data): print(f[錯(cuò)誤] 偏移 {i} 處長度 {ln} 越界包被截?cái)? 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 粘進(jìn)來空格可有可無 parse_adv(02 01 06 05 09 50 42 30 33 03 03 0F 18)i ln 1是核心跳過一個(gè)長度字節(jié)加 ln 個(gè)字節(jié)的內(nèi)容。ln 0提前退出是因?yàn)閺V播包尾部常用零填充。這段腳本不依賴任何第三方庫抓包工具導(dǎo)出的數(shù)據(jù)直接粘貼就能用定位「名字少了最后一個(gè)字母」「UUID 類型寫成 0x02」這類問題比肉眼數(shù)快得多。MTU 協(xié)商的結(jié)果要在連接建立后主動(dòng)打印一次。有些平臺(tái)默認(rèn)不協(xié)商你以為能發(fā) 200 字節(jié)實(shí)際每包只發(fā)出去 20 字節(jié)剩余全被截?cái)啾憩F(xiàn)是「指令發(fā)一半設(shè)備不響應(yīng)」。日志里加上協(xié)商前后的 MTU 值這個(gè)問題一眼就能看出來。4.4 低功耗休眠、GPIO 與廣播間隔的取舍功耗超標(biāo)是二次開發(fā)里最典型的翻車點(diǎn)。規(guī)格書上的數(shù)字通常是「僅射頻MCU 廣播」的理想值你板子上多一個(gè)上拉電阻、多一路常開的串口數(shù)字就完全不一樣。第一件事是確認(rèn)休眠真的進(jìn)去了。很多 SDK 有休眠前后的鉤子函數(shù)在里面翻轉(zhuǎn)一個(gè) GPIO用示波器看這個(gè)腳的占空比就知道實(shí)際醒著多久。比看電流平均值直觀得多。第二件事是 GPIO 狀態(tài)。休眠時(shí)懸空的輸入腳會(huì)因電平不確定產(chǎn)生漏電上拉電阻在外部有下拉時(shí)會(huì)持續(xù)耗流。原則是不用的腳配置成模擬或下拉輸出外部上拉能省則省能加大阻值就加大。第三件事是外設(shè)時(shí)鐘。串口、定時(shí)器、ADC 在休眠前該關(guān)的關(guān)掉尤其是串口——調(diào)試完忘記關(guān)一晚掉幾百微安很常見。廣播間隔的調(diào)整放在最后先把漏電堵住再談間隔否則你怎么調(diào)間隔都對(duì)不上規(guī)格書。5. 常見問題排查燒錄、連接、功耗的五條踩坑記錄有些坑幾乎每個(gè)項(xiàng)目都會(huì)踩一遍寫在這里省得重復(fù)試錯(cuò)。下面五條都按「現(xiàn)象 → 原因 → 解決」組織遇到相似癥狀可以直接對(duì)照。需要強(qiáng)調(diào)一點(diǎn)BLE 調(diào)試最忌諱同時(shí)改多個(gè)變量一次只改一處改完立刻驗(yàn)證否則問題解決了你也不知道是哪一步生效的。5.1 燒錄報(bào)握手失敗換線換板都沒用現(xiàn)象燒錄工具能識(shí)別到串口點(diǎn)開始后幾秒提示握手失敗或超時(shí)換 USB 線、換板子癥狀一樣。原因多半是沒進(jìn)下載模式。串口 ISP 需要在復(fù)位釋放的瞬間采樣啟動(dòng)腳電平手動(dòng)按鍵的時(shí)序經(jīng)常對(duì)不上另一種可能是燒錄工具版本與模組內(nèi)部固件版本不匹配協(xié)議對(duì)不上同樣表現(xiàn)為握手失敗。解決先改成調(diào)試器燒錄排除時(shí)序問題確認(rèn)固件本身沒問題如果只能用串口用工具里的「自動(dòng)進(jìn)入下載模式」選項(xiàng)讓工具通過 DTR/RTS 控制復(fù)位和啟動(dòng)腳別手動(dòng)按。工具版本按資料包tool/目錄里配套的那份用不要用電腦上殘留的舊版。5.2 廣播數(shù)據(jù)改了手機(jī)掃到的還是舊名字現(xiàn)象代碼里改了設(shè)備名并重新編譯燒錄手機(jī)端掃出來還是原來那個(gè)名字換一臺(tái)手機(jī)也一樣。原因緩存。手機(jī)端對(duì)已配對(duì)或曾掃描到的設(shè)備會(huì)緩存 GATT 和廣播信息Android 側(cè)尤其明顯另一種情況是編譯產(chǎn)物沒真正燒進(jìn)去燒錄的是舊 hex。解決先在手機(jī)藍(lán)牙設(shè)置里刪除該設(shè)備記錄或在調(diào)試 App 里清緩存再掃同時(shí)核對(duì)燒錄日志里的固件時(shí)間和大小確認(rèn)燒的是新產(chǎn)物。判斷是不是緩存最直接的辦法是換一臺(tái)從沒掃過這個(gè)設(shè)備的手機(jī)。5.3 能連上幾秒鐘后自動(dòng)斷開現(xiàn)象連接建立成功服務(wù)也能看到三五秒后連接斷開反復(fù)重連。原因監(jiān)督超時(shí)配置不合理最常見。監(jiān)督超時(shí)必須大于 (1 從機(jī)延遲) × 連接間隔 × 2如果從機(jī)延遲設(shè)成 4、間隔 30 ms超時(shí)至少要 300 ms 以上配成 200 ms 就會(huì)周期性誤判斷鏈。其次是應(yīng)用層在連接回調(diào)里做了耗時(shí)操作阻塞了協(xié)議棧的事件處理。解決先把從機(jī)延遲改成 0、監(jiān)督超時(shí)放大到 4 s 驗(yàn)證連接是否穩(wěn)定穩(wěn)定后逐步往回調(diào)找到臨界點(diǎn)再留一倍余量。回調(diào)里不要做 Flash 擦寫、不要長延時(shí)重活丟到主循環(huán)里做。5.4 功耗比規(guī)格書高一個(gè)數(shù)量級(jí)現(xiàn)象休眠電流實(shí)測幾百微安規(guī)格書寫的是個(gè)位數(shù)微安。原因串口沒關(guān)、GPIO 懸空漏電、調(diào)試日志沒關(guān)、外部上拉電阻常供這四樣占了絕大多數(shù)。日志這一項(xiàng)最隱蔽因?yàn)楣δ苌贤耆！＝鉀Q按順序排查——先關(guān)日志測一次再關(guān)串口測一次再把所有未用 GPIO 配成模擬態(tài)測一次。每關(guān)一項(xiàng)測一次電流變化最大的那項(xiàng)就是主因。用 GPIO 翻轉(zhuǎn)配合示波器看喚醒占空比比盯著萬用表數(shù)字猜有效。5.5 AT 固件和 SDK 固件混著燒功能莫名其妙現(xiàn)象按 SDK 例程燒完串口發(fā) AT 指令沒反應(yīng)或者刷回 AT 固件后自定義服務(wù)消失但廣播名還是自己改的那個(gè)。原因AT 固件和 SDK 固件是兩套完全不同的應(yīng)用共用同一塊 Flash 但入口和分區(qū)不同?；鞜笈渲脜^(qū)殘留舊參數(shù)表現(xiàn)就是「一半新一半舊」。解決切換固件類型前先做一次全片擦除別只擦應(yīng)用區(qū)。切換完成后用默認(rèn)配置跑一遍基礎(chǔ)功能確認(rèn)干凈了再燒自己的業(yè)務(wù)固件。產(chǎn)線上尤其要注意返修板子回爐時(shí)先擦再寫。6. OTA 與產(chǎn)線固化把「能跑」變成「能出廠」樣機(jī)能跑通和能出廠之間隔著 OTA 和參數(shù)固化兩件事。這兩塊資料包里不一定有現(xiàn)成腳本但基于里面的例程補(bǔ)起來不難。OTA 的核心是分區(qū)。常見做法是應(yīng)用區(qū) 備份區(qū)雙 bank新固件先整包寫進(jìn)備份區(qū)校驗(yàn)通過后把啟動(dòng)標(biāo)志指過去重啟由 bootloader 搬運(yùn)或直接跳轉(zhuǎn)。判斷 OTA 是否可靠別只看「升級(jí)成功」這一條要專門測三個(gè)場景升級(jí)過程中斷電、升級(jí)包被截?cái)唷⒔导?jí)回滾。斷電測試最容易被跳過但它恰恰是現(xiàn)場最容易發(fā)生的——用戶在升級(jí)時(shí)鎖屏走了。/* OTA 狀態(tài)機(jī)的最小實(shí)現(xiàn)關(guān)鍵是每一步都落標(biāo)志位掉電后可恢復(fù) */ 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. 先寫備份區(qū)絕不直接覆蓋運(yùn)行區(qū) */ if (flash_write(OTA_BAK_ADDR offset, data, len) ! 0) { ota_set_state(OTA_FAIL); /* 寫失敗立刻標(biāo)記下次上電重來 */ return; } /* 2. 每包寫完更新進(jìn)度標(biāo)志掉電后從標(biāo)志處續(xù)傳 */ 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 校驗(yàn)通過才允許切啟動(dòng)標(biāo)志 */ if (crc32_check(OTA_BAK_ADDR, total_len) 0) { ota_set_state(OTA_READY); ota_commit_boot_flag(); /* 這一步之后才真正生效 */ } else { ota_set_state(OTA_FAIL); /* 校驗(yàn)失敗保留舊固件不切標(biāo)志 */ } }這段代碼的重點(diǎn)不在語法在順序先寫備份區(qū)、再校驗(yàn)、最后切標(biāo)志。把切標(biāo)志放到校驗(yàn)之前一次傳輸錯(cuò)誤就能讓設(shè)備變磚現(xiàn)場只能返修。進(jìn)度標(biāo)志要落在獨(dú)立的配置區(qū)別和固件放一起否則搬運(yùn)固件時(shí)會(huì)一起被擦掉。產(chǎn)線固化是另一件事。每臺(tái)設(shè)備需要寫入唯一的 MAC、設(shè)備名、校準(zhǔn)參數(shù)和密鑰這些不該靠改代碼重新編譯。常規(guī)做法是在 Flash 里劃一小塊參數(shù)區(qū)產(chǎn)線工具通過串口指令寫入應(yīng)用啟動(dòng)時(shí)讀取。參數(shù)區(qū)要帶版本號(hào)和 CRC升級(jí)固件后參數(shù)仍然有效參數(shù)格式變了則按版本號(hào)做兼容遷移。驗(yàn)證方法我一般分三層單機(jī)功能回歸廣播、連接、讀寫、通知四項(xiàng)走一遍、異常注入斷電、斷鏈、超長包、錯(cuò) CRC、小批量老化十幾臺(tái)連續(xù)跑 24 小時(shí)統(tǒng)計(jì)斷鏈次數(shù)和電流波動(dòng)。三層都過才敢說這批固件能出廠。從那以后我每次改完固件都強(qiáng)制走一遍「擦全片 → 燒固件 → 斷電重啟 → 手機(jī)端刪緩存重掃」這四步不管改動(dòng)多小。省下的那兩分鐘往往要用兩天去找回來。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取