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