蓝牙软件介绍

更新时间:2024-04-17 06:15:26下载pdf

本文介绍 TuyaOS 蓝牙 LE 开发包架构、运行流程、目录,以及常用 API 和常用功能。

软件架构

TuyaOS 是基于组件化的概念设计的,提供了基础服务、安全、网络服务中间件以及丰富的物联网业务功能组件,这些功能组件构成了 TuyaOS 的能力地图。TuyaOS 蓝牙开发框架就是基于 TuyaOS 的能力地图,按照蓝牙设备工作场景的能力需求,构建的不同规格的、适用于不同场景的 SDK 的集合。

这些开发框架提供了统一的接口、丰富的组件能力,您无需关心具体的实现原理,调用接口函数即可快速开发产品功能,并提供统一的开发体验。

蓝牙软件介绍

根据上图可知,TuyaOS 蓝牙 LE 开发包主要分为 4 层:

  • 第 1 层是涂鸦核心适配层(Tuya Kernel Layer,TKL 层),由涂鸦提供的 TKL 层标准接口和芯片原厂 SDK 组成。TKL 层对上提供统一的接口,对下适配不同的芯片平台,适配工作可能由涂鸦开发人员完成,也可能由芯片原厂的开发人员完成。

  • 第 2 层和第 3 层是涂鸦抽象层(Tuya Abstraction Layer,TAL 层),由各种组件组成,是开发包的主体部分。基本功能包括涂鸦配网、数据通信以及系统管理功能。高级服务包括天气服务、HID 靠近响应、时间服务、共享设备、功耗管理,设备管理以及网络能力等功能。

  • 第 4 层是应用层,涵盖电工、照明、家电、传感、穿戴、门锁等多个领域。除了提供标准的产品例程以外,涂鸦还提供了标准 Demo 工程,标准 Demo 工程无需任何改动,即可直接编译烧录,为应用开发人员提供跨平台的应用开发体验。详见 蓝牙基础 Demo

软件运行流程

蓝牙软件介绍

更多信息,参考 设备初始化

开发包目录

蓝牙软件介绍

Demo 目录

蓝牙软件介绍

此处展示的 Demo 是 TuyaOS 蓝牙 LE 开发包最基本的 Demo,您可以通过该 Demo 体验开发包支持的几乎所有功能,当然也可以基于该 Demo 开发任何产品。

  • app_dp_parser:DP 解析例程,包含 DP 接收函数和发送函数,您可以在接收和发送之间添加业务逻辑。

  • app_key:按键例程,短按进入低功耗,长按恢复出厂设置。

  • app_led:LED 例程。

  • tuya_ble_protocol_callback:主要负责涂鸦蓝牙通信协议的事件回调处理以及相关的接口。

  • tuya_sdk_callback:主要负责 TuyaOS SDK 的事件回调处理、各级初始化以及大循环处理。

组件(含库)目录

蓝牙软件介绍 蓝牙软件介绍

组件是 TuyaOS 蓝牙 LE 开发包的主体部分,TuyaOS 的目标就是实现代码的组件化。对产品开发而言,熟练掌握常用组件的基本原理和实现方法能大大提高效率。

  • tal_ble_bulkdata:实现大数据传输功能。

  • tal_ble_ota:实现 OTA 功能。

  • tal_ble_product_test:实现授权(产测)功能。

  • tal_ble_protocol:实现涂鸦蓝牙 LE 配网协议,您无需关心实现细节,直接调用相关接口实现业务功能即可。关于接口介绍,详见 涂鸦蓝牙 LE SDK 说明 的 API 介绍 和 CALL BACK EVENT 介绍章节。

  • tal_ble_uart_common:实现串口通用对接功能。

  • tal_ble_weather:实现查询天气功能。

  • tal_bluetooth:实现蓝牙相关接口封装。

  • tal_driver:实现驱动相关接口封装。

  • tal_key:实现按键功能。

  • tal_oled:实现 OLED 屏幕驱动功能。

  • tal_sdk_test:实现测试功能。

  • tal_system:实现系统相关接口封装。

  • tal_utc:实现 UTC 相关接口。

  • tal_util:实现通用工具接口。

  • tal_ble_mbedtls:实现 AES 和 MD5 等加密接口。

  • tal_ble_secure:实现涂鸦蓝牙 LE 配网协议相关的安全接口。

Vendor 目录

蓝牙软件介绍

Vendor 是开发环境所在目录,包含芯片原厂 SDK、各类适配层以及通用头文件,由涂鸦和芯片原厂共同维护。

芯片原厂 SDK

基于芯片原厂的公开例程开发或由芯片原厂开发人员修改而来。

各类适配层

涉及蓝牙、外设驱动(GPIO、PWM、ADC、IIC、SPI……)、系统驱动(Memory、OTA、Sleep……)、工具接口的适配。

通用头文件

为保证 TKL 层以上能够达到一套代码适用于多个芯片平台的目标,Flash 地址、外设引脚等平台相关的因素都通过统一的宏定义放置于 board.h 中。

头文件目录

蓝牙软件介绍
  • tuya_error_code.h:涂鸦对错误类型的定义。

  • tuya_cloud_types.h:涂鸦对数据类型、枚举、宏、结构体的定义。

  • tuya_iot_config:涂鸦对系统配置、组件使能/配置的定义。

常用 API

初始化

  • tuya_init_first():一般用于基础外设、配置信息、内存处理相关的初始化。

  • tuya_init_second():一般用于 Log、软定时、蓝牙基础协议相关的初始化。

  • tuya_init_third():一般用于复杂外设、外设组件相关的初始化。

  • tuya_init_last():一般用于初始化的收尾工作,包含蓝牙配网协议的初始化、测试代码的初始化、开启广播等动作。在执行完该 API 之后,一般会进入主循环。

  • tuya_ble_protocol_init:蓝牙配网协议的初始化。

主循环

tuya_main_loop():TuyaOS 蓝牙 LE 开发包基于前后台软件框架,提供了主循环内的回调接口 tuya_main_loop(),您可依据需求自定义相关操作注入该接口。

注意

  • 该接口的返回值会影响低功耗功能,请勿随意修改。

  • 该接口主要用于您添加调试、验证性的操作,需 谨慎使用。该接口占用过多时间片会影响整个系统框架的稳定性。

事件回调

  • tuya_ble_evt_callback:蓝牙基础协议事件回调处理函数,包含协议栈初始化完成、连接、断开、连接参数更新、接收数据等蓝牙基础事件。

  • tuya_ble_protocol_callback:蓝牙配网协议事件回调处理函数,包含配网成功、时间戳更新成功、接收应用数据、解绑成功、接收 OTA 数据等应用层常用功能。

数据收发

  • TUYA_BLE_CB_EVT_DP_DATA_RECEIVED:应用层数据接收回调,接收的数据符合 DP 数据格式,请参考 DP 小节。

  • tuya_ble_dp_data_send:应用层数据发送函数。

  • tuya_ble_dp_data_with_time_send:应用层数据发送函数,带时间戳。

  • TAL_BLE_EVT_WRITE_REQ:蓝牙基础数据接收回调。

  • tal_ble_server_common_send:蓝牙基础数据发送函数。

状态查询

tuya_ble_connect_status_get()

typedef enum {
    UNBONDING_UNCONN = 0,  //未绑定未连接
    UNBONDING_CONN,        //未绑定已连接已认证
    BONDING_UNCONN,        //已绑定未连接
    BONDING_CONN,          //已绑定已连接已认证
    BONDING_UNAUTH_CONN,   //已绑定已连接未认证
    UNBONDING_UNAUTH_CONN, //未绑定已连接未认证
    UNKNOW_STATUS
} tuya_ble_connect_status_t;

各状态之间的转换关系如下图所示:

蓝牙软件介绍

常用功能

蓝牙数据流

下图演示了蓝牙 LE 数据在 SDK 中的流转过程,其他过程类似。

蓝牙软件介绍

表格形式,方便复制:

手机发送数据 手机接收数据
TKL:芯片原厂蓝牙 LE 数据接收回调 + tkl_ble_gatt_evt_func tkl_ble_gatts_value_notify + 芯片原厂蓝牙 LE 数据发送函数
TAL:TKL_BLE_GATT_EVT_WRITE_REQ + tal_ble_event_callback tal_ble_server_common_send
TUYA:TAL_BLE_EVT_WRITE_REQ + tuya_ble_gatt_receive_data tuya_ble_gatt_send_data
接收单包:TUYA_BLE_EVT_MTU_DATA_RECEIVE + tuya_ble_handle_ble_data_evt tuya_ble_gatt_send_data_enqueue + tuya_ble_gatt_send_data_handle
tuya_ble_commonData_rx_proc,组包,解密 tuya_ble_commData_send,组包,加密
接收指令:TUYA_BLE_EVT_BLE_CMD + tuya_ble_handle_ble_cmd_evt TUYA_BLE_EVT_DP_DATA_SEND - tuya_ble_handle_dp_data_send_evt
tuya_ble_evt_process,指令分发 tuya_ble_dp_data_send
FRM_DP_DATA_WRITE_REQ + tuya_ble_handle_dp_data_write_req app_dp_report
TUYA_BLE_CB_EVT_DP_DATA_RECEIVED + app_dp_parser

测试代码

开启测试代码:设置宏 TUYA_SDK_TEST 的值为 1

关闭测试代码:设置宏 TUYA_SDK_TEST 的值为 0

测试代码结合测试上位机(Logic)可实现大部分配网、通信、外设等功能的测试,可帮助您更好地开发产品,但是生产固件请务必关闭测试功能

Log 管理

蓝牙软件介绍

Log 输出接口

tuya_log_output_cb

动态内存

动态内存的大小:BOARD_HEAP_SIZE

关于驱动

涂鸦通过 TKL 层提供最小功能集所需的驱动接口,TKL 只是涂鸦标准化的接口,并非所有驱动都有 TKL。

为了保证开发效率,如果 TKL 层对应的驱动没有实现或者没有相关驱动,您可以按照实际需求,直接调用芯片原厂提供的接口。