這篇寫給要給 TXW81x 產品加「手機藍牙配網」的軟件工程師:設備出廠沒有 Wi-Fi 賬號密碼,用戶打開手機,通過藍牙把路由器的 SSID 和密碼發給設備,設備收到後連上 Wi-Fi。下面先講 SDK 提供的三種配網方式怎麼選,再講代碼怎麼開、手機端怎麼測、數據格式是什麼。
技術細節以泰芯官方《TXW8xx SDK BLE配網開發指南》和《TXSDK_BLE開發指南》為準。
本文依據的兩份官方指南是泰芯 Wi-Fi SoC 通用文檔(適用於支持 BLE 的芯片),81x 的 SDK 文檔清單裡也把藍牙配網指南列為配套手冊。兩份文檔在宏名、能否與 Wi-Fi 同時工作等細節上有差別,下文會分別說明,以你手上 SDK 的實際代碼為準。
| 方式 | 手機能否掃到設備 | 是否建立連接 | 手機端 |
ble_ll_open 的 type |
BLE_DEMO_MODE |
|---|---|---|---|---|---|
| BLE 廣播配網 | 不能 | 否 | 微信小程序「TXBLE配網」 | 0 | 1 |
| BLE 可掃描廣播配網 | 能 | 否 | 微信小程序「TXBLE配網」 | 1 | 2 |
| BLE 連接配網 | 能 | 是(GATT) | 自家 App;調試可用 nRF Connect | 2 | 3 |
三種方式的工作原理:
ADV_IND)並響應掃描,手機能在列表裡看到它,但仍然不能連接,配網信息還是靠手機發廣播包傳過來。選型建議:
不管哪種方式,設備端的流程都是這幾步:
ble_adv_parse_param 解析,連接方式由 uble_test_hdlval 解析。sysevt_ble_event)裡,把臨時放在 syscfg 的配網信息寫入協議棧並保存到 flash,同時啟動 Wi-Fi 聯網。為什麼要先關藍牙? 《TXW8xx SDK BLE配網開發指南》寫明 BLE 與 Wi-Fi 不能同時工作,所以 demo 是先關 BLE 再聯網。較新的《TXSDK_BLE開發指南》增加了 Wi-Fi/BLE 共存模式,可以先不關藍牙、等聯網成功後再通知手機,見第六節。
BLE 事件機制和 Wi-Fi 協議棧事件是同一套,細節見《TXSDK_WiFi開發指南》第 4 章。
兩份官方文檔的寫法不同:
| 文檔 | 需要的宏 |
|---|---|
| 《TXW8xx SDK BLE配網開發指南》(2023) |
#define BLE_EN,#define BLE_DEMO_MODE 0
|
| 《TXSDK_BLE開發指南》(2024) | #define BLE_SUPPORT |
BLE_DEMO_MODE 的取值:0 表示用通用集成接口(傳入參數裡帶上要使能的模式),1/2/3 分別對應廣播、可掃描廣播、連接配網。先在自己的工程配置裡搜一下這幾個宏,確認當前 SDK 用的是哪一套。
三種配網方式的示例代碼都在 sdk/lib/ble/ble_demo.c,下面的初始化步驟直接參考它即可。
廣播配網:
ble_adv_init:初始化,並為收到的廣播數據注冊回調。ble_ll_open(ops, 0, 38):打開廣播配網模式。可掃描廣播配網:
ble_ll_set_advdata(ops, adv_data, len):設置廣播數據(AdvData,最長 31 字節),供手機發現設備。ble_ll_set_scan_rsp(ops, scan_resp, len):設置掃描響應數據(最長 31 字節),回應手機掃描並攜帶設備信息,例如設備名。ble_ll_set_adv_en(ops, 1):打開 keep RX 和廣播功能,芯片默認是關的。ble_ll_open(ops, 1, 38):打開可掃描廣播配網模式。連接配網:
uble_init(ops, att_table, att_table_size, att_mtu):用定義好的 ATT table 初始化協議模塊,att_mtu 默認 517、最大 517。ble_ll_set_advdata / ble_ll_set_scan_rsp:設置廣播和掃描響應數據,同上。ble_ll_open(ops, 2, 38):打開連接配網模式。ble_ll_open的第三個參數chan固定填 38。以上函數返回 0 表示成功,非 0 表示出錯,記得檢查返回值。
ble_demo.c 中的 uble_demo_att_table 定義了兩個服務:默認服務 0x1800 和自定義配網服務 0x1910。配網服務下有 4 個特征:
| 特征 UUID | 屬性 | 作用 |
|---|---|---|
0x2b11 |
Write | 手機向設備寫入配網數據 |
0x2b10 |
Notify | 設備主動通知手機 |
0x2b12 |
Read | 讀取設備保存的 SSID(21 字節) |
0x2b13 |
Read | 讀取設備保存的密碼(21 字節) |
如果只要完成配網,一個 Write 特征就夠了,其餘是 demo 附帶的調試能力。
往 Write 特征寫入如下字符串:
:SSID,PASSWD,0/1
ATT table(如 uble_demo_att_table):每項包含 att_type(UUID)、properties(特征屬性)、att_value(關聯的值)。必須按「service → characteristic → characteristic_value → characteristic → characteristic_value……」的順序排列,兩個 service 之間的特征都歸屬於上面那個 service。
value table(如 uble_demo_values):每項包含 type、size、bitoff、maskbit、*value。type 取 UBLE_VALUE_TYPE 枚舉:
| 類型 | 說明 |
|---|---|
UINT8 / UINT16 / UINT32
|
整數,協議代碼直接讀寫,不用額外寫代碼 |
UINT8_BIT / UINT16_BIT / UINT32_BIT
|
整數中的某些 bit,直接讀寫 |
BYTES / STRING
|
字節數組 / 字符串,直接讀寫 |
HDL |
沒有固定值,要自己實現回調 |
demo 的 value table 裡有 3 項:一個 HDL 類型(回調 uble_test_hdlval,負責解析配網數據),兩個字符串類型分別綁定 sys_cfgs.ssid 和 sys_cfgs.passwd,所以手機能直接讀寫這兩個參數。
HDL 回調的參數:entry(被執行的 value 項)、read(1 讀、0 寫)、buff(讀時是輸出緩沖,寫時是收到的數據)、size(讀時是緩沖大小,寫時是數據長度)、offset(本次偏移)。返回值:讀操作返回實際讀取長度,寫操作返回 0 表示成功。
uble_gatt_notify(att_hdl, data, len):通過 Notify 發送。uble_gatt_indicate(att_hdl, data, len):通過 Indication 發送。att_hdl 是該特征值在 ATT table 中的索引,從 1 開始數,demo 裡 Notify 特征值的句柄是 10。Notify 特征必須聲明 CCCD 描述符,否則手機端監聽不到通知。
默認流程是收到配網數據就關藍牙去聯網,手機不知道設備到底連沒連上。《TXSDK_BLE開發指南》給出了共存方案,可以在連接配網中回傳聯網狀態:
ble_set_coexist_en(ops, 1, 0):第二個參數 1 打開共存、0 關閉;第三個參數 dec_duty 保留,填 0。sysevt_ble_event 裡先不關閉藍牙。舊版指南寫的是 BLE 與 Wi-Fi 不能同時工作。用共存方案前,先確認你的 SDK 裡有 ble_set_coexist_en 這個接口。
SSS,實際以你在掃描響應數據裡設置的名字為準。uble_demo_att_table 裡定義的全部服務和特征。0x2b11),寫入 :SSID,PASSWD,1 格式的字符串。0x2b12、0x2b13,nRF Connect 會把 ASCII 碼直接顯示成字符。| 現象 | 排查方向 |
|---|---|
| 手機掃不到設備 | 廣播配網模式本來就不可掃描;可掃描廣播模式檢查是否調用了 ble_ll_set_adv_en(ops, 1);連接配網檢查廣播數據和掃描響應是否設置成功 |
| 廣播 / 掃描響應設置失敗 | AdvData 與掃描響應數據各自最長 31 字節 |
| 寫入配網數據後沒反應 | 檢查格式:冒號開頭、英文逗號分隔、末位 0/1;只能用英文字符且長度小於 21 字節 |
| 加密路由器連不上 | 末位加密標志寫成了 0;1 對應加密(WPA2) |
| nRF Connect 收不到 Notify | 特征沒聲明 CCCD,或手機端沒打開通知;uble_gatt_notify 的句柄要按 ATT table 從 1 開始的索引計算 |
| 配網成功,重啟後又要重新配 | 事件處理裡沒有把配網信息保存到 flash |
| 藍牙距離短、連接不穩 | 檢查 40MHz 晶振頻偏,按硬件設計指南用儀器確認 |
| 工程裡找不到藍牙配網 | FPV SDK 需 2.5.1 及以上;確認 BLE_EN 或 BLE_SUPPORT 宏已打開 |
改完代碼需要反複燒錄驗證,單臺燒錄推薦用 創芯蜂 HiveComm,操作見《CKLink 驅動安裝與固件燒錄教程:用 HiveComm 一鍵燒錄》,CKLink 調試器可在創芯蜂淘寶店購買;遇到燒不進可按《TXW 系列芯片固件燒錄(下載)教程:燒錄器接線、操作與失敗排查》排查,其它開發問題可查《TXW81x 開發常見問題匯總:Flash、編譯環境、燒錄、USB 與外設》。