TXTAIXIN文档
V1.0 / 指南 / 中文

TXSDK_BLE开发指南

下载 PDF

logo

责任与版权

责任限制

由于产品版本升级或者其他原因，本文档会不定期更新。除非另行约定，泰芯半导体有限公司对本文档所有内容不提供任何担保或授权。

客户应在遵守法律、法规和安全要求的前提下进行产品设计，并做充分验证。泰芯半导体有限公司对应用帮助或客户产品设计不承担任何义务。客户应对其使用泰芯半导体有限公司的产品和应用自行负责。

在适用法律允许的范围内，泰芯半导体有限公司在任何情况下，都不对因使用本文档相关内容及本文档描述的产品而产生的损失和损害进行超过购买支付价款的赔偿（除在涉及人身伤害的情况中根据适用的法律规定的损害赔偿外）。

版权申明

泰芯半导体有限公司保留随时修改本文档中任何信息的权利，无需提前通知且不承担任何责任。

未经泰芯半导体有限公司书面同意，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。除非获得相关权利人的许可，否则，任何人不能以任何形式对前述软件进行复制、分发、修改、摘录、反编译、反汇编、解密、反向工程、出租、转让、分许可等侵犯本文档描述的享有版权的软件版权的行为，但是适用法禁止此类限制的除外。

修订记录

日期

版本

描 述

修订人

2024-05-7

V1.0

TX

1. 概述

TXSDK是泰芯半导体发布的WiFi/音视频系列芯片开发SDK。本文档介绍了TXSDK的BLE功能开发方法，本文档只适用于支持BLE功能的芯片。

SDK实现了基础的BLE ATT协议，支持了常用的ATT opcode。可以实现通过BLE ATT协议进行信息交互。

2. ATT Table介绍

SDK设计了BLE ATT table，用于定义BLE设备的GATT服务信息。其他BLE设备（如手机）可以通过这些服务信息与BLE设备进行信息交互，例如进行BLE配网。

定义ATT table需要遵循BLE GATT规范。SDK的ble_demo.c 是BLE配网功能的示例代码，定义了uble_demo_att_table，如下图所示：

该demo代码的att table包含了两项服务，分别是默认服务（0x1800）和自定义配网服务（0x1910）。其中0x1910包含了四个特征：

  • Write特征（0x2b11）：用于手机端向设备进行写入数据
  • Notify特征（0x2b10）：用于设备向手机端进行信息通知
  • Read特征1（0x2b12）：用于手机端读取设备的ssid参数
  • Read特征2 （0x2b13）：用于手机端读取设备的passwd参数

ATT table要按如下顺序填写：

  • service,
  • characteristic
  • characteristic_value
  • characteristic
  • characteristic_value
  • service
  • characteristic
  • characteristic_value
  • characteristic
  • characteristic_value
  • ...

在service之下，下一个service之上的所有characteristic都会被认为是该service的特征。

ATT table还需要关联一个value table，用于和具体的characteristic value进行关联，不同的characteristic所实现的功能不同。

示例代码的value table定义了3个value，分别是：

  • 1个handle类型的value，需要执行uble_test_hdlval函数
  • 1个字符串类型的value，关联到sys_cfgs.ssid，手机可以直接读写sys_cfgs.ssid
  • 1个字符串类型的value，关联到sys_cfgs.passwd，手机可以直接读写sys_cfgs.passwd

当手机访问操作具体的某个特征时，BLE协议代码会解析找到对应的value，执行read、write或 callback 函数。

SDK的value table支持了常见类型，可以简化代码开发。只有handle类型的value需要自己实现callback函数，其他类型的value只需要和实际参数值绑定即可。

enum UBLE_VALUE_TYPE {

//特征的值是uint8类型，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT8,

//特征的值是uint16类型，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT16,

//特征的值是uint32类型，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT32,

//特征的值是uint8数据的bit位，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT8_BIT,

//特征的值是uint16数据的bit位，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT16_BIT,

//特征的值是uint32数据的bit位，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_UINT32_BIT,

//特征的值是uint8数组，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_BYTES,

//特征的值是字符串，支持直接读写，无需增加额外代码

UBLE_VALUE_TYPE_STRING,

//特征没有具体的值，需要执行一些代码，需要自行实现callback函数

UBLE_VALUE_TYPE_HDL,

};

handle类型value的callback 函数定义如下：

  • 参数entry ： 被执行的value entry
  • 参数 read ：读写标识，1： read 操作，0： write操作
  • 参数 buff ：

read操作时为输出buffer，用于填充读取的数据

write操作时为输入buffer，存储的是接收到的数据

  • 参数 size

read操作时为输出buffer的size

write操作时为接收数据的长度

  • 参数 offset：本次操作的偏移值。
  • 返回值：
    • read操作时，返回实际读取的数据长度
    • write操作时，表示是否成功。0：成功，非0：失败。

ATT table结构体定义说明如下：

  • att_type： UUID
  • properties： 特征
  • att_value： type uuid 或者character value关联的value值

value table的结构体定义说明：

  • type：数据类型
  • size：数据大小
  • bitoff： 位域偏移量
  • maskbit：位域掩码
  • *value： 用于关联任意参数

3. BLE API介绍

SDK实现了基础的BLE ATT协议，可以支持GATT服务信息读取，特征读写，事件通知。

3.1. uble_init

uble_init函数是ble att协议初始化API，执行该API需要att atble参数。

int32 uble_init(struct bt_ops *ops, const struct uble_gatt_data *att_table, uint16 att_table_size, uint16 att_mtu)

  • 参数 ops [in]：BLE功能句柄
  • 参数 att_table [in]：ATT table
  • 参数 att_table_size [in]：ATT table Size
  • 参数 att_mtu [in]：ATT MTU，默认是517，最大支持517。
  • 返回值：表示是否成功。0：成功，非0：失败

3.2. uble_gatt_notify

uble_gatt_notify API用于BLE设备通NOTIFY操作发送数据给手机app。

int32 uble_gatt_notify(uint16 att_hdl, uint8 *data, int32 len)

  • 参数 att_hdl [in]：特征值的句柄
  • 参数 data [in]：需要发送的数据
  • 参数 len [in]：数据长度
  • 返回值：表示是否成功。0：成功，非0：失败

3.3. uble_gatt_indicate

uble_gatt_indicate API用于BLE设备通INDICATION操作发送数据给手机app。

int32 uble_gatt_indicate(uint16 att_hdl, uint8 *data, int32 len)

  • 参数 att_hdl [in]：特征值的句柄
  • 参数 data [in]：需要发送的数据
  • 参数 len [in]：数据长度
  • 返回值：表示是否成功。0：成功，非0：失败

执行uble_gatt_notify和uble_gatt_indicate所需的句柄就是对应的特征值在att table中的索引（从1开始）。例如示例uble_demo_att_table的中notify特征值的句柄就是10。

4. BLE配网开发

SDK的BLE功能通常是用来开发BLE配网功能，SDK默认提供了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_SUPPORT

4.1. BLE广播配网

4.1.1. 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

返回值：

  • 返回0：开启成功
  • 非0： ERROR

4.2.2. 解析小程序发送的参数

TXSDK支持泰芯TXBLE配网微信小程序进行配网。使用泰芯TXBLE配网微信小程序对设备进行配网操作流程如下图所示。

1692329759385

  1. 打开手机蓝牙广播
  2. 发送广播数据
  3. 配网信息

1.设置联网参数

进行上述操作后，手机端开始持续广播带联网信息数据的广播包，而设备端进入BLE广播配网模式后，则开始接收范围内的各种广播数据。广播数据会进行过滤和接收超时处理，从而筛选出目标的广播数据。

设备获取到目标的广播数据后，则会交给 ble_adv_parse_param解析，由此获取到必要的配网信息。解析数据过程如下。

在回抛给应用的 BLE 事件中，需要将临时存放在syscfg的配网信息写入协议栈内部和保存到flash，同时启动wifi进行联网。具体实现如下。

应用关注BLE事件

事件机制详细介绍请参考TXSDK_WiFi开发指南-第4章节WiFi协议栈Event机制

sysevt_ble_event实例

4.2. BLE 可扫描广播配网

4.2.1. BLE可扫描广播配网初始化

使用BLE可扫描广播配网之前需要对模块进行初始化，可直接使用ble_demo.c提供的示例代码，如下图所示。

Length UUID Data

设备名称

相较于BLE广播配网模式，BLE可扫描广播配网需要设置广播数据和扫描响应数据，同时还需要打开设备keep RX和广播功能，具体操作如下：

  1. 设置设备的BLE广播数据，该广播数据用于手机发现设备。

广播数据内容为AdvData部分，最大长度为31byte，如下图所示。

设备将以ADV_IND类型发送广播数据。

设置广播数据的宏为：

ble_ll_set_advdata(ops, adv_data, len)

参数说明：

  • ops： btops
  • adv_data： 广播数据
  • len： 广播数据的长度

返回值：

  • 返回0： 设置成功
  • 非0： ERROR
  1. 设置设备的BLE扫描响应数据，该数据用于回应手机扫描请求，并携带设备信息。

响应数据的内容也为AdvData部分，最大长度为31byte，如上图所示。

设置扫描响应数据的宏为：

ble_ll_set_scan_rsp(ops, scan_resp, len)

参数说明：

  • ops： btops
  • scan_data： 扫描响应数据
  • len： 扫描响应数据的长度

返回值：

  • 返回0： 设置成功
  • 非0： ERROR
  1. 使能设备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

返回值：

    • 返回0：开启成功
    • 非0： ERROR

4.2.2. 解析小程序发送的参数

BLE可扫描广播配网接收广播数据流程与BLE广播配网一致，请参考3.1.2章节。

4.3. BLE连接配网

4.3.1. BLE连接配网初始化

使用BLE连接配网需要先定义符合app BLE配网需求的ATT table，然后对模块进行初始化，可直接使用ble_demo.c提供的示例代码，如下图所示：

Length UUID Data

设备名称

uble_init对BLE协议模块进行初始化，需要使用到定义的att table。

BLE连接配网需要设置广播数据和扫描响应数据，具体操作如下。

  1. 设置设备的BLE广播数据，该广播数据用于手机发现设备。

广播数据内容为AdvData部分，最大长度31byte，如下图所示：

设备将以ADV_IND类型发送广播数据。

设置广播数据的宏为：

ble_ll_set_advdata(ops, adv_data, len)

参数说明：

  • ops： btops
  • adv_data：广播数据
  • len： 广播数据的长度

返回值：

  • 返回0： 设置成功
  • 非0： ERROR
  1. 设置设备的BLE扫描响应数据，该数据用于回应手机扫描请求，并携带设备信息。

响应数据的内容也为AdvData部分，最大长度31byte，如上图所示。

设置扫描响应数据的宏为：

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)

参数说明：

  • ops： bt_ops
    • type： 2 - BLE连接配网模式
    • chan： 该参数固定输入38

返回值：

    • 返回0： 开启成功
    • 非0： ERROR

4.3.2. 解析客户端发送的数据

TXSDK BLE连接配网功能可以使用nRF Connect APP进行测试验证。详细流程如下。

  1. 扫描到设备名为SSS的蓝牙设备：

  1. 连接成功后，可以看到设备提供的各项服务与特征：

  1. 选择第二个自定义服务的第一个特征（WRITE）进行发送，配网数据格式如下

:SSID,PASSWD,0/1

全英字符，0表示不加密，1表示加密（WPA2）。字符小于21byte。

  1. 设备接收到配网数据后，最终由 uble_test_hdlval解析，由此获取到必要的配网信息。解析数据过程如下。

回抛BLE事件处理与BLE广播配网基本一致，请参考3.1.2章节。

  1. BLE连接配网可拓展连接状态反馈的功能，这个功能实现需要启动WIFI和BLE共存模式。

该接口需在BLE打开前设置，参数说明如下：

ble_set_coexist_en(ops, coexist, dec_duty)

参数说明：

  • ops： bt_ops
  • coexist： 0 - 关闭

1 - 打开

  • dec_duty： 保留，填0即可

返回值：

  • 返回0： 成功
  • 非0： ERROR
  1. 使能WIFI和BLE共存模式之后，在BLE事件sysevt_ble_event处理中，就可以先不关闭蓝牙，而是在WIFI连接成功事件中处理，示例如下。

  1. notify功能还需要在nRF Connect上打开（即CCCD特征）

  1. 使能后，往设备写入配网参数（即步骤3），设备连接成功，返回notify信息。