TXW8xx SDK BLE配网开发指南
泰芯TXW8xx SDK BLE配网开发指南
责任与版权
责任限制
由于产品版本升级或者其他原因，本文档会不定期更新。除非另行约定，泰芯半导体有限公司对本文档所有内容不提供任何担保或授权。
客户应在遵守法律、法规和安全要求的前提下进行产品设计，并做充分验证。泰芯半导体有限公司对应用帮助或客户产品设计不承担任何义务。客户应对其使用泰芯半导体有限公司的产品和应用自行负责。
在适用法律允许的范围内，泰芯半导体有限公司在任何情况下，都不对因使用本文档相关内容及本文档描述的产品而产生的损失和损害进行超过购买支付价款的赔偿（除在涉及人身伤害的情况中根据适用的法律规定的损害赔偿外）。
版权申明
泰芯半导体有限公司保留随时修改本文档中任何信息的权利，无需提前通知且不承担任何责任。
未经泰芯半导体有限公司书面同意，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。除非获得相关权利人的许可，否则，任何人不能以任何形式对前述软件进行复制、分发、修改、摘录、反编译、反汇编、解密、反向工程、出租、转让、分许可等侵犯本文档描述的享有版权的软件版权的行为，但是适用法禁止此类限制的除外。
修订记录
日期 | 版本 | 描 述 | 修订人 |
2023-11-2 | V1.0 | 初始版本 | DY |
泰芯TXW8xx SDK支持BLE配网功能，支持3种配网方式：
- BLE广播配网：设备以广播方式进行通信，无需建立连接，而且不可扫描。SDK Demo代码对接了泰芯微信小程序：TXBLE配网，使用该小程序可以直接发送广播包对设备进行参数设置。
- BLE可扫描广播配网：支持BLE协议的广播/扫描功能，手机端可以扫描发现设备，但是不能进行连接。手机扫描发现设备后，可发送特定的广播包对设备进行参数设置。SDK Demo代码对接了泰芯微信小程序：TXBLE配网，使用该小程序可以直接发送广播包对设备进行参数设置。
- BLE连接配网：支持BLE协议连接，手机App扫描发现设备并进行连接，设备提供了配网服务。App通过自定义的属性特征进行参数设置。
SDK包含了3种配网方式的demo代码，代码文件：sdk/lib/ble/ble_demo.c
使用此模块需声明以下宏定义：
- #define BLE_EN
- #define BLE_DEMO_MODE 0
BLE_DEMO_MODE 有以下取值：
- 0：使用通用的集成接口，传入参数需包含使能的模式；
- 1：BLE广播配网；
- 2：BLE可扫描广播配网；
- 3：BLE连接配网；
使用BLE广播配网之前，需要对模块进行初始化，可直接使用ble_demo.c提供的示例代码，如下图所示。
ble_adv_init 对模块进行初始化会为设备接收到的广播数据声明回调处理函数。
初始化完成后，使用宏ble_ll_open打开BLE广播配网模式。ble_ll_open参数说明如下：
ble_ll_open(ops, type, chan)
参数说明：
- ops： bt_ops
- type： 0 - BLE广播配网模式
- chan： 该参数固定输入38
返回值：
TXW8xx SDK支持泰芯TXBLE配网微信小程序进行配网。使用泰芯TXBLE配网微信小程序对设备进行配网操作流程如下图所示。
2.打开手机蓝牙广播
3.发送广播数据
1.设置联网参数
进行上述操作后，手机端开始持续广播带联网信息数据的广播包，而设备端进入BLE广播配网模式后，则开始接收范围内的各种广播数据。广播数据会进行过滤和接收超时处理，从而筛选出目标的广播数据。
设备获取到目标的广播数据后，则会交给 ble_adv_parse_param解析，由此获取到必要的配网信息。解析数据过程如下。
回抛BLE事件
设备联网
设置Keymgmt
设置Password
设置SSID
ble_network_configured会对解析到的联网参数进行保存。由于TXW8xx的BLE功能和WiFi功能不能同时工作，所以这里需要关闭蓝牙BLE模式，进入WIFI模式进行联网。
联网参数保存
退出蓝牙BLE模式
计算联网密钥
使用BLE可扫描广播配网之前，需要对模块进行初始化，可直接使用ble_demo.c提供的示例代码，如下图所示。
Length UUID Data
设备名称
相较于BLE广播配网模式，BLE可扫描广播配网需要设置广播数据和扫描响应数据，同时还需要打开设备keep RX和广播功能，具体操作如下：
- 设置设备的BLE广播数据，该广播数据用于手机发现设备。
广播数据内容为AdvData部分，如下图所示。
设备将以ADV_IND类型发送广播数据。
设置广播数据的宏为：
ble_ll_set_advdata(ops, adv_data, len)
参数说明：
- ops： btops
- adv_data： 广播数据
- len： 广播数据的长度
返回值：
- 返回0： 设置成功
- 非0： ERROR
- 设置设备的BLE扫描响应数据，该数据用于回应手机扫描请求，并携带设备信息。
响应数据的内容也为AdvData部分，如上图所示。
设置扫描响应数据的宏为：
ble_ll_set_scan_rsp(ops, scan_resp, len)
参数说明：
- ops： btops
- scan_data： 扫描响应数据
- len： 扫描响应数据的长度
返回值：
- 返回0： 设置成功
- 非0： ERROR
- 使能设备keep RX和广播功能，芯片默认关闭此项功能。
开启此项功能后，BLE可扫描广播配网模式才能保持发送和接收广播数据，若未使能此项功能，手机端无法扫描到设备。
开启此功能的宏为：
ble_ll_set_adv_en(ops, start)
参数说明：
- ops： btops
- start： 0 - 关闭，1 - 开启
返回值：
- 返回0： 设置成功
- 非0： ERROR
初始化完成后，使用宏ble_ll_open打开BLE可扫描广播配网模式。ble_ll_open参数说明如下：
ble_ll_open(ops, type, chan)
参数说明：
- ops： bt_ops
- type： 1 - BLE可扫描广播配网模式
- chan： 该参数固定输入38
返回值：
BLE可扫描广播配网接收广播数据流程与BLE广播配网一致，请参考2.2章节。
进行BLE连接配网功能开发时，核心数据是att_table，att_table是设备配置的GATT服务信息。定义不同的att_table，设备就会提供不同的服务，在进行自定义开发时根据实际需求配置服务信息。
TXW8xx SDK中ble_demo.c对att_table声明如下图所示。
由上图可见，att_table包含了两项服务，分别是默认服务（0x1800）和自定义配网服务（0x1910）。自定义配网服务是我们需要关心的，其包含了四个特征，具体如下：
- Write特征（0x2b11） ： 用于手机端向设备进行写入数据；
- Notify特征（0x2b10）：用于设备向手机端进行信息通知；
- Read特征1（0x2b12） ： 用于手机端向设备进行读取数据，这里是读取设备的SSID；
- Read特征2（0x2b13） ： 用于手机端向设备进行读取数据，这里是读取设备的Password；
BLE连接配网就是通过手机端对设备的写入实现将联网信息传输给设备的，设备接收数据的callback就由att_table中的uble_demo_values指定，ble_demo.c对uble_demo_values的定义如下图所示。
由上图可见，uble_demo_values指明了不同特征属性值的处理，协议代码便可以直接读写，不需要再写额外代码。UBLE_VALUE_TYPE已经枚举了常用的数据类型，如下图所示，如果没有合适的数据类型还可以采用UBLE_VALUE_TYPE_HDL来定义通用的类型，其value可以是回调函数用于处理特殊的数据。
在使用TXW8xx SDK进行BLE连接配网开发时，需要修改的也就是上面两个表。下面简单介绍一下两个表的结构。
uble_demo_att_table表结构如下：
- att_type： UUID
- properties： 特征
- att_value： type或者character value关联的value值
uble_demo_values表结构如下:
- type： 数据类型
- size： 数据大小
- bitoff： 偏移量
- maskbit： 位掩码
- *value： 用于关联任意参数
根据BLE协议可以找到服务与特征的UUID定义，如下图所示。
了解了两个表的结构之后，就可以自定义GATT服务了。创建的自定义GATT服务与att_table对应如下图所示（以Notify为例）。
一般的，一个配网服务只完成联网信息交互的话，只需要一个Write的特征，手机端便可将联网信息写入设备，设备读取和解析数据后进而连上网。
TXW8xx SDK提供的BLE连接配网demo，实现了联网信息的写入和设备SSID和Password的读取，下文会进行操作的说明和演示。
使用BLE连接配网之前，需要对模块进行初始化，可直接使用ble_demo.c提供的示例代码，如下图所示：
Length UUID Data
设备名称
uble_init对BLE协议模块进行初始化，需要使用到定义的att table。
BLE连接配网需要设置广播数据和扫描响应数据，具体操作如下。
- 设置设备的BLE广播数据，该广播数据用于手机发现设备。
广播数据内容为AdvData部分，如下图所示：
设备将以ADV_IND类型发送广播数据。
设置广播数据的宏为：
ble_ll_set_advdata(ops, adv_data, len)
参数说明：
- ops： btops
- adv_data：广播数据
- len： 广播数据的长度
返回值：
- 返回0： 设置成功
- 非0： ERROR
- 设置设备的BLE扫描响应数据，该数据用于回应手机扫描请求，并携带设备信息。
响应数据的内容也为AdvData部分，如上图所示。
设置扫描响应数据的宏为：
ble_ll_set_scan_rsp(ops, scan_resp, len)
参数说明：
- ops： btops
- scan_data： 扫描响应数据
- len： 扫描响应数据的长度
返回值：
- 返回0： 设置成功
- 非0： ERROR
初始化完成后，使用宏ble_ll_open打开BLE连接配网模式。ble_ll_open参数说明如下：
ble_ll_open(ops, type, chan)
参数说明：
TXW8xx BLE连接配网可使用nRF Connect进行测试，操作流程如下。
使用nRF Connect扫描设备。
手机端点击CONNECT后，设备会收到连接请求。
建立连接后，手机端可以查看设备的所有GATT服务，即uble_demo_att_table表定义的服务。
Read特征
Notify特征
Write特征
为满足蓝牙BLE配网需求，TXW8xx BLE连接配网实现了对设备进行Write操作，方便将联网信息发送给设备。
手机端使用nRF Connect配合demo代码进行测试，对设备进行写入操作如下：
发送的联网信息需遵循以下规则：
:SSID,PASSWD,0/1
注：全英字符，0表示不加密，1表示加密。字符小于21byte
手机端发送后，此时设备将接收并进行处理，最终调用uble_test_hdlval进行数据解析。
回抛BLE事件
设备联网
设置Keymgmt
设置Password
设置SSID
最后关闭蓝牙BLE模式，进入WIFI模式进行联网。
设备向App发送数据有2种形式：
- Read：App发送读取指令，设备反馈数据；
- Notify：设备主动发送数据通知App；
TXW8xx BLE连接配网提供了设备Notify的API，以及对设备已保存的联网信息的Read操作，包括对设备的SSID和Password的读取，详细说明如下。
- Notify
设备与手机端建立BLE连接后，设备可以主动发送数据通知App。att_table有关Notify特征定义如下。
这里需要注意Notify特征需要声明CCCD描述符，否则App监听失败。
TXW8xx BLE连接配网开放uble_gatt_notify接口可以实现通知功能，其中参数data即为通知的内容。
若使用nRF Connect进行调试，当点击Notify时，手机端会开始监听数据，如下图所示。
- Read
设备与手机端建立BLE连接后，当手机端点击Read请求时，设备将向手机端发送数据，发送的数据与att_table表有关，设备会根据手机端发送请求的UUID找到att_table表中对应的特征，该特征对应的att_value即为返回的数据，如下图所示。
- 0x2b12 返回设备SSID，大小为21byte；
- 0x2b13 返回设备Password，大小为21byte；
若使用nRF Connect进行调试，nRF Connect同时会将ASCLL码转成对应的字符。如下图所示。
设备保存的Password
设备保存的SSID