这篇写给要给 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/1ATT 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 与外设》。