这篇写给要给 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 与外设 .