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
问答

发布
问题