TXW81x 藍牙(BLE)配網教程:三種配網方式、SDK 開啟與手機端測試

發布於 2026-11-08 21:59:49

這篇寫給要給 TXW81x 產品加「手機藍牙配網」的軟件工程師:設備出廠沒有 Wi-Fi 賬號密碼,用戶打開手機,通過藍牙把路由器的 SSID 和密碼發給設備,設備收到後連上 Wi-Fi。下面先講 SDK 提供的三種配網方式怎麼選,再講代碼怎麼開、手機端怎麼測、數據格式是什麼。

技術細節以泰芯官方《TXW8xx SDK BLE配網開發指南》和《TXSDK_BLE開發指南》為準。

一、先確認:81x 的藍牙能做什麼

  • 芯片層面:TXW812/813/816/817/818 的數據手冊都寫明支持「藍牙快速配網」和 Wi-Fi/BLE 共存(812/813/816/818 寫的是 PTA 共存)。
  • SDK 層面:按官方 SDK 選型表,FPV SDK 從 2.5.1 起支持藍牙配網,2.5.0 沒有。手上 SDK 版本太老的先升級,版本選擇可以看 《TXW81x 型號怎麼選:812/813/816/817/818 區別與 SDK 版本選擇》。
  • 定位:SDK 實現的是基礎的 BLE ATT 協議(GATT 服務讀取、特征讀寫、通知),主要用途就是配網,不要把它當成完整的藍牙協議棧來規劃功能。
  • 硬件:81x 內置 Wi-Fi 和 BLE,必須外接 40MHz 高速晶振。硬件設計指南特別提醒,要用 BLE 的方案,40M 晶振的頻偏精度要用儀器確認,負載電容盡量靠近晶振放置。
本文依據的兩份官方指南是泰芯 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)並響應掃描,手機能在列表裡看到它,但仍然不能連接,配網信息還是靠手機發廣播包傳過來。
  • 連接配網:設備提供一個自定義 GATT 配網服務,手機連上後往特征裡寫配網數據,還能讀回已保存的 SSID / 密碼,或者接收設備的 Notify 通知。

選型建議:

  1. 想零 App 開發、盡快跑通 → 廣播配網,直接用泰芯的小程序。
  2. 希望用戶在手機上能看到設備、確認是哪一臺 → 可掃描廣播配網。
  3. 有自己的 App,需要回傳配網結果或做更多交互 → 連接配網。

三、配網的整體流程

不管哪種方式,設備端的流程都是這幾步:

  1. 初始化 BLE 模塊,打開對應的配網模式。
  2. 收到手機發來的配網數據:廣播方式由 ble_adv_parse_param 解析,連接方式由 uble_test_hdlval 解析。
  3. 解析出 SSID、密碼和加密方式(Keymgmt),拋出 BLE 事件。
  4. 應用在 BLE 事件(示例為 sysevt_ble_event)裡,把臨時放在 syscfg 的配網信息寫入協議棧並保存到 flash,同時啟動 Wi-Fi 聯網。
  5. 關閉 BLE,轉入 Wi-Fi 模式連接路由器。
為什麼要先關藍牙? 《TXW8xx SDK BLE配網開發指南》寫明 BLE 與 Wi-Fi 不能同時工作,所以 demo 是先關 BLE 再聯網。較新的《TXSDK_BLE開發指南》增加了 Wi-Fi/BLE 共存模式,可以先不關藍牙、等聯網成功後再通知手機,見第六節。

BLE 事件機制和 Wi-Fi 協議棧事件是同一套,細節見《TXSDK_WiFi開發指南》第 4 章。

四、SDK 裡怎麼開啟

1. 打開宏開關

兩份官方文檔的寫法不同:

文檔 需要的宏
《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,下面的初始化步驟直接參考它即可。

2. 各模式的初始化

廣播配網:

  1. ble_adv_init:初始化,並為收到的廣播數據注冊回調。
  2. ble_ll_open(ops, 0, 38):打開廣播配網模式。

可掃描廣播配網:

  1. ble_ll_set_advdata(ops, adv_data, len):設置廣播數據(AdvData,最長 31 字節),供手機發現設備。
  2. ble_ll_set_scan_rsp(ops, scan_resp, len):設置掃描響應數據(最長 31 字節),回應手機掃描並攜帶設備信息,例如設備名。
  3. ble_ll_set_adv_en(ops, 1):打開 keep RX 和廣播功能,芯片默認是關的。
  4. ble_ll_open(ops, 1, 38):打開可掃描廣播配網模式。

連接配網:

  1. uble_init(ops, att_table, att_table_size, att_mtu):用定義好的 ATT table 初始化協議模塊,att_mtu 默認 517、最大 517。
  2. ble_ll_set_advdata / ble_ll_set_scan_rsp:設置廣播和掃描響應數據,同上。
  3. ble_ll_open(ops, 2, 38):打開連接配網模式。
ble_ll_open 的第三個參數 chan 固定填 38。以上函數返回 0 表示成功,非 0 表示出錯,記得檢查返回值。

五、連接配網:GATT 服務和數據格式

demo 裡的服務定義

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
  • 以英文冒號開頭,SSID、密碼、加密標志之間用英文逗號分隔。
  • 最後一位:0 表示不加密,1 表示加密(WPA2)。
  • 只能用英文字符,長度要小於 21 字節。

想自定義服務時要改哪兩張表

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 描述符,否則手機端監聽不到通知。

六、配網成功後回傳結果(Wi-Fi/BLE 共存)

默認流程是收到配網數據就關藍牙去聯網,手機不知道設備到底連沒連上。《TXSDK_BLE開發指南》給出了共存方案,可以在連接配網中回傳聯網狀態:

  1. 在打開 BLE 之前調用 ble_set_coexist_en(ops, 1, 0):第二個參數 1 打開共存、0 關閉;第三個參數 dec_duty 保留,填 0。
  2. 在 sysevt_ble_event 裡先不關閉藍牙。
  3. 在 Wi-Fi 連接成功的事件裡,再通過 Notify 告訴手機結果,然後關閉藍牙。
舊版指南寫的是 BLE 與 Wi-Fi 不能同時工作。用共存方案前,先確認你的 SDK 裡有 ble_set_coexist_en 這個接口。

七、手機端怎麼配

用「TXBLE配網」小程序(廣播 / 可掃描廣播配網)

  1. 設備端打開廣播配網或可掃描廣播配網模式。
  2. 微信打開泰芯小程序「TXBLE配網」,填寫聯網參數(SSID、密碼等)。
  3. 打開手機藍牙廣播,發送廣播數據。手機會持續廣播帶配網信息的數據包,直到設備接收。

用 nRF Connect 測試連接配網

  1. 設備端打開連接配網模式,用 nRF Connect 掃描。《TXSDK_BLE開發指南》的 demo 中設備名為 SSS,實際以你在掃描響應數據裡設置的名字為準。
  2. 點 CONNECT 建立連接,能看到 uble_demo_att_table 裡定義的全部服務和特征。
  3. 如果要接收通知,先在 Notify 特征上打開通知(即開啟 CCCD)。
  4. 選擇自定義服務下的 Write 特征(0x2b11),寫入 :SSID,PASSWD,1 格式的字符串。
  5. 設備解析後連接路由器;開啟了共存的話會通過 Notify 返回結果。
  6. 需要核對時,讀 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 與外設》。

參考資料

相關閱讀

開發中遇到問題,歡迎在社區提問,也可以先問 AI 助手。

0 條評論

AI
問答

發布
問題