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 的 typeBLE_DEMO_MODE
BLE 广播配网不能否微信小程序「TXBLE配网」01
BLE 可扫描广播配网能否微信小程序「TXBLE配网」12
BLE 连接配网能是(GATT)自家 App;调试可用 nRF Connect23

三种方式的工作原理:

  • 广播配网:设备只「听」,不发广播也不接受连接。手机持续发送带配网信息的广播包,设备在范围内接收各种广播,经过过滤和超时处理挑出目标数据。实现最简单。
  • 可扫描广播配网:设备会发广播(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属性作用
0x2b11Write手机向设备写入配网数据
0x2b10Notify设备主动通知手机
0x2b12Read读取设备保存的 SSID(21 字节)
0x2b13Read读取设备保存的密码(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
问答

发布
问题