[嵌入式]涂鸦蓝牙SDK开发系列教程——5.应用开发（一）

在前几节课中已经介绍了如何在 涂鸦 IoT 平台 上创建智能产品以及如何搭建涂鸦蓝牙模组的开发环境，在此基础上，本节课将继续以 BTU 模组为例，介绍如何使用 涂鸦蓝牙模组及其 SDK 开发一款温湿度传感器产品。

前期准备

产品创建

首先，要在 涂鸦 IoT 平台 上创建好一个 温湿度传感器 产品，具体方法请参考 产品创建。

环境搭建

本 Demo 的开发环境如下：

• 涂鸦三明治 BLE SoC 主控板 (BTU)
• 涂鸦三明治 温湿度传感器 功能版 (SHT30-DIS)
• USB 转串口工具、串口调试助手
• 生产解决方案 (涂鸦云模组烧录授权平台)
• Telink 烧录器、Telink IDE、Telink BDT
• PC (Windows 10)
• SDK (tuya-ble-sdk-demo-project-tlsr8253)
• 智能手机、智能生活 APP

如果您使用 BTU 模组或同芯片平台模组进行开发，在开发前需准备好上述开发环境 (主控板和功能板可选)；如果您使用其他芯片平台的涂鸦蓝牙模组，请参考 环境搭建 和芯片厂家官网资料进行环境搭建。

烧录授权

在开发前先使用 涂鸦云模组烧录授权平台 对模组进行烧录授权，请按照 烧录授权 中的介绍完成初版固件的配置与烧录，并通过 智能生活 APP 检验设备是否能正常配网。对模组进行授权之后，在调试阶段我们就可以直接使用 Telink BDT 进行固件烧录。

快速上手

如果您准备好了以上开发环境，那么可以按以下步骤快速体验 Demo 功能：

1. 在 tuya-ble-sdk-development-course-demo 中下载本课程配套 Demo；(app_demo)
2. 参考文件结构 将仓库中 app_demo 目录下 除 tuya_ble_sdk_demo.h 外 (包含了 PID 和固件版本信息等，请保留您自己的配置) 的所有文件复制到您的工程中，并在工程配置中添加 头文件路径；
3. 根据您使用的 授权方案 确认是否需要修改初始化参数 use_ext_license_key 和 device_id_len；
4. 根据您的电路设计确认是否需要修改相关引脚编号，可参考引脚分配 ；
5. 编译代码，并使用 Telink BDT 将生成的固件烧录到您的开发板中；
6. 使用 智能生活 APP 扫描设备进行功能体验，可参考功能演示 。

如果您使用的是其他芯片平台的涂鸦蓝牙模组，则不需要复制 Demo 中 board 目录下的文件 (但需要确认 SDK 中 board 目录下的 API 接口函数 是否已实现相关功能)，并使用芯片平台对应的烧录软件进行固件烧录。

SDK 介绍

文件结构

下面以 TLSR825x 平台的 SDK 为例介绍 SDK 的文件结构。

├── ble_sdk_multimode
|    ├── telink_sdk          /* 原厂 SDK */
|    ├── tuya_ble_sdk_demo   /* 涂鸦蓝牙 SDK 及其 Demo，适配了 TLSR825x 平台 */
|    |    ├── app            /* 应用代码，提供了一些 Demo 文件，可直接在此基础上进行扩展 */
|    |    ├── board          /* 芯片平台关联代码，包括相关外设的硬件抽象和为 tuya_ble_sdk 提供的 port 接口及应用层配置文件 */
|    |    ├── components     /* 组件代码，包括一些通用组件，用户自封装的组件也可放置于该目录下 */
|    |    ├── doc            /* 文档资料 */
|    |    ├── tools          /* 工具文件 */
|    |    └── tuya_ble_sdk   /* 涂鸦蓝牙 SDK 代码，主要实现了涂鸦智能设备和智能生活 APP 之间的通信协议，以及事件调度机制 */
|    |
|    └── .cproject 及其他     /* 工程文件 */
|
├── CHANGELOG.md             /* 更新日志 */
├── README.md                /* Readme 文件英文版 */
└── README_zh-CN             /* Readme 文件中文版 */

• tuya_ble_sdk_demo

  tuya_ble_sdk_demo.c：实现 tuya_ble_sdk 的初始化，封装应用层的事件调度 API

  tuya_ble_sdk_test.c：实现 tuya_ble_sdk 测试用的串口指令，仅供测试，与应用无关

  tuya_ble_bulk_data_demo.c：大数据通道例程

  tuya_ble_product_test_demo.c：整机产测例程

• component

  external\easylogger：调试信息打印接口组件

• board

  TLSR825X\ty_board_tlsr825x：相关外设硬件抽象

  TLSR825X\tuya_ble_port：专为 tuya_ble_sdk 提供的 port 接口和应用层配置文件

  TLSR825X\ota：实现各自平台的 OTA（数据传输协议一致，Flash 操作不同）

应用入口

• tuya_ble_sdk_demo_init：各芯片平台的涂鸦蓝牙模组 SDK 中都提供了 SDK 开发的 Demo 文件，可以直接在 tuya_ble_sdk_demo.c 代码的基础上进行开发；tuya_ble_sdk_demo_init 为 SDK Demo 初始化函数，在此函数的最后加上您的应用初始化代码即可。

  void tuya_ble_sdk_demo_init(void)
  {
      /* 根据是否使用 tuya_ble_sdk_demo.h 中的授权码配置相关参数 */
      if (tuya_ble_device_param.use_ext_license_key) {
          memcpy(tuya_ble_device_param.device_id, device_id_test, DEVICE_ID_LEN);
          memcpy(tuya_ble_device_param.auth_key, auth_key_test, AUTH_KEY_LEN);
          memcpy(tuya_ble_device_param.mac_addr_string, TY_DEVICE_MAC, MAC_STRING_LEN);
      }
      /* 配置 PID 和设备名称 */
      memcpy(tuya_ble_device_param.product_id, TY_DEVICE_PID, tuya_ble_device_param.product_id_len);
      memcpy(tuya_ble_device_param.adv_local_name, TY_DEVICE_NAME, tuya_ble_device_param.adv_local_name_len);
      /* tuya_ble_sdk 初始化 */
      tuya_ble_sdk_init(&tuya_ble_device_param);
      /* 注册 tuya_ble_sdk 回调函数 */
      tuya_ble_callback_queue_register(tuya_ble_sdk_callback);
      /* OTA 初始化、定时器初始化 */
      tuya_ble_ota_init();
      tuya_ble_disconnect_and_reset_timer_init();
      tuya_ble_update_conn_param_timer_init();
      /* 智能产品应用程序初始化 */
      tuya_ble_app_init();
  }
  

• tuya_ble_main_tasks_exec：在不使用 RTOS 的芯片平台架构下，该函数作为涂鸦蓝牙 SDK 的事件主调度器循环执行，位于 tuya_ble_main.c 中；如果有需要循环处理的任务可放置于该函数中，但更建议使用创建定时器的方式来执行，定时器的使用方法可参考 软件定时器?。

  void tuya_ble_main_tasks_exec(void)
  {
      /* 智能产品应用程序主循环 */
      tuya_ble_app_loop();
      /* 主调度器 */
      tuya_sched_execute();
  }
  

常用 API

1. 日志打印

API 列表

API 说明

接口文件：tuya_ble_log.h

/* 开启/关闭日志 */
#define TUYA_APP_LOG_ENABLE 1	/* 0-关闭，1-开启 (custom_tuya_ble_config.h) */
#define TY_LOG_ENABLE       1	/* 0-关闭，1-开启 (board.h) */
/* 设置日志等级 */
#defien TUYA_APP_LOG_LEVEL  TUYA_APP_LOG_LEVEL_DEBUG

/**
 * @brief 打印日志 (xxxx 可替换为 ERROR 或 WARNING 或 INFO 或 DEBUG)
 * @param[in] format: 格式控制符
 * @param[in] …: 可变参数
 * @return 无
 */
void TUYA_APP_LOG_xxxx(const char *format, …)

应用示例

TUYA_APP_LOG_xxxx("tuya_ble_sdk_init succeeded.");
TUYA_APP_LOG_xxxx("tuya_ble_sdk_init failed, error code: %d.", res);
TUYA_APP_LOG_xxxx("receive data: %x.", data);

2. 软件定时器

API 列表

API 说明

接口文件：tuya_ble_port.h

/**
 * @brief 创建一个定时器
 * @param[in] p_timer_id: 定时器ID
 * @param[in] timeout_value_ms: 超时时间(ms)
 * @param[in] mode：工作模式
 * @param[in] timeout_handler: 超时处理函数
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_timer_create(void** p_timer_id,
                                        uint32_t timeout_value_ms,
                                        tuya_ble_timer_mode mode,
                                        tuya_ble_timer_handler_t timeout_handler);

/**
 * @brief 启动指定定时器
 * @param[in] timer_id: 定时器ID
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_timer_start(void* timer_id);

/**
 * @brief 停止指定定时器
 * @param[in] timer_id: 定时器ID
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_timer_stop(void* timer_id);

/**
 * @brief 重启指定定时器
 * @param[in] timer_id: 定时器ID
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_timer_restart(void* timer_id, uint32_t timeout_value_ms);

/**
 * @brief 删除指定定时器
 * @param[in] timer_id: 定时器ID
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_timer_delete(void* timer_id);

数据类型

/* 定时器工作模式 */
typedef enum {
    TUYA_BLE_TIMER_SINGLE_SHOT, /* 单次触发，定时器超时后停止计数 */
    TUYA_BLE_TIMER_REPEATED,	/* 重复触发，定时器超时后重新开始计数 */
} tuya_ble_timer_mode;

/* 定时器回调函数类型 */
typedef void (*tuya_ble_timer_handler_t)(void*);

应用示例

功能概述：上电后，指示灯点亮 2s 后熄灭，按键按下时指示灯点亮，5s 后再次熄灭。

#include "tuya_ble_port.h"
#include "ty_pin.h"

/* 引脚 */
#define KEY_PIN             GPIO_PA0    /* KEY */
#define LED_PIN             GPIO_PD7    /* LED */
/* 定时时间 */
#define KEY_SCAN_TIME_MS    10          /* 10ms */
#define LED_TURN_TIME_MS_1  2000        /* 2s */
#define LED_TURN_TIME_MS_2  5000        /* 5s */

/* 定时器可删除标志 */
uint8_t delete_flag = 0;
/* 定时器 ID */
tuya_ble_timer_t key_timer;
tuya_ble_timer_t led_timer;

/**
 * @brief key_timer超时处理函数
 * @param 无
 * @return 无
 */
void key_timer_cb(void)
{
    /* 读取按键引脚的电平 */
    ty_pin_level_t pin_level;
    ty_pin_get(KEY_PIN, &pin_level);
    if (TY_PIN_LOW == pin_level) {
        /* 点亮 LED, 重启led_timer, 定时5s */
        ty_pin_set(LED_PIN, TY_PIN_HIGH);
        tuya_ble_timer_restart(led_timer, LED_TURN_TIME_MS_2);
        /* 停止定时器key_timer, 标记key_timer可删除 */
        tuya_ble_timer_stop(key_timer);
        delete_flag = 1;
    }
}

/**
 * @brief led_timer超时处理函数
 * @param 无
 * @return 无
 */
void led_timer_cb(void)
{
    /* 熄灭LED */
    ty_pin_set(LED_PIN, TY_PIN_LOW);
    if (delete_flag) {
        /* 删除定时器key_timer */
        tuya_ble_timer_delete(key_timer);
    } else {
        /* 启动定时器key_timer */
        tuya_ble_timer_start(key_timer);
    }
}

/**
 * @brief 初始化函数
 * @param 无
 * @return 无
 */
void app_init(void)
{
    /* 初始化按键和指示灯引脚，点亮 LED */
    ty_pin_init(KEY_PIN, TY_PIN_MODE_IN_PU);
    ty_pin_init(LED_PIN, TY_PIN_MODE_OUT_PP_LOW);
    ty_pin_set(LED_PIN, TY_PIN_HIGH);
    /* 创建一个定时器: key_timer, 定时10ms, 重复触发, 注册超时处理函数key_timer_cb */
    tuya_ble_timer_create(&key_timer, KEY_SCAN_TIME_MS, TUYA_BLE_TIMER_REPEATED, (tuya_ble_timer_handler_t)key_timer_cb);
    /* 创建一个定时器并启动: led_timer, 定时2s, 单次触发, 注册超时处理函数led_timer_cb */
    tuya_ble_timer_create(&led_timer, LED_TURN_TIME_MS_1, TUYA_BLE_TIMER_SINGLE_SHOT, (tuya_ble_timer_handler_t)led_timer_cb);
    tuya_ble_timer_start(led_timer);
}

3. DP上报

API 列表

API 说明

接口文件：tuya_ble_api.h

/**
 * @brief 发送DP数据
 * @param[in] sn: 发送序号，由应用程序自行定义管理的序号，每发送一次递增1
 * @param[in] type: 发送类型
 * @param[in] mode: 发送模式
 * @param[in] ack: 是否需要应答标志
 * @param[in] p_dp_data: DP数据
 * @param[in] dp_data_len: 数据总长度，最大不能超过TUYA_BLE_SEND_MAX_DATA_LEN-7
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_dp_data_send(uint32_t sn,
                                        tuya_ble_dp_data_send_type_t type,
                                        tuya_ble_dp_data_send_mode_t mode,
                                        tuya_ble_dp_data_send_ack_t ack,
                                        uint8_t *p_dp_data,
                                        uint32_t dp_data_len);

数据类型

/* 发送类型 */
typedef enum {
    DP_SEND_TYPE_ACTIVE = 0,        /* 设备主动发送 */
    DP_SEND_TYPE_PASSIVE,           /* 设备响应APP的DP数据查询指令 */
} tuya_ble_dp_data_send_type_t;

/* 发送模式 */
typedef enum {
    DP_SEND_FOR_CLOUD_PANEL = 0,    /* APP将接收到的数据上传到云端，同时发送到面板显示 */
    DP_SEND_FOR_CLOUD,              /* APP仅将接收到的数据上传到云端 */
    DP_SEND_FOR_PANEL,              /* APP仅将接收到的数据发送到面板显示 */
    DP_SEND_FOR_NONE,               /* 既不上传到云端，也不发送到面板显示 */
} tuya_ble_dp_data_send_mode_t;

/* 响应模式 */
typedef enum {
    DP_SEND_WITH_RESPONSE = 0,      /* 需要APP响应 */
    DP_SEND_WITHOUT_RESPONSE,       /* 不需要APP响应 */
} tuya_ble_dp_data_send_ack_t;

DP 说明

涂鸦 IoT 平台是以 DP 模型管理数据的。任何设备产生的数据都需要抽象为 DP 模型形式，一个 DP 模型由四部分组成：DP ID、DP 数据类型、DP 数据长度、DP 数据。更多详情，请参考 自定义功能。

涂鸦蓝牙模组 SDK 的 DP 模型管理协议如下：

DP 数据类型及其数据长度范围规定如下：

每个 DP 数据的最大长度在涂鸦 IoT 平台定义时指定。dp_type = 0 或 3 时, dp_len 数值自定义，但必须小于在涂鸦 IoT 平台定义时的最大长度。

tuya_ble_dp_data_send 的参数 p_dp_data 指向的数据必须以下表格式组装上报：

注：n-1 = (4 + dp1_len) - 1；m-1 = n + (4 + dp2_len) - 1。

一次可发送多个 DP 数据，只要总长度不超过限制即可，最大长度为 TUYA_BLE_SEND_MAX_DATA_LEN-7，其中 TUYA_BLE_SEND_MAX_DATA_LEN 可配置。

应用示例

功能概述：(温度更新时)上报温度数据，(蓝牙连接时)上报所有数据。

/* DP ID */
#define DP_ID_TEMP_CURRENT          1	/* 温度 */
#define DP_ID_TEMP_ALARM            14	/* 温度报警 */

/* DP数据类型(可以直接使用tuya_ble_mutli_tsf_protocol.h中的定义) */
#define DT_RAW                      0	/* 透传 */
#define DT_BOOL                     1	/* 布尔 */
#define DT_VALUE                    2	/* 数值 */
#define DT_STRING                   3	/* 字符串 */
#define DT_ENUM                     4	/* 枚举 */

/* DP模型字段偏移量 */
#define DP_DATA_INDEX_OFFSET_ID     0	/* dp_id */
#define DP_DATA_INDEX_OFFSET_TYPE   1	/* dp_type */
#define DP_DATA_INDEX_OFFSET_LEN_H  2	/* dp_len */
#define DP_DATA_INDEX_OFFSET_LEN_L  3	/* dp_len */
#define DP_DATA_INDEX_OFFSET_DATA   4	/* dp_data */

/* DP数据变量 */
static int32_t sg_cur_temp = 0, sg_prv_temp = 0;
static uint8_t sg_temp_alarm = 0;

/* DP组装上报数组 */
static uint8_t sg_repo_array[255+4];

/* 发送序号 */
static uint32_t sg_sn = 0;

/**
 * @brief 上报一个DP数据
 * @param[in] dp_id: DP ID
 * @param[in] dp_type: DP数据类型
 * @param[in] dp_len: DP数据长度
 * @param[in] dp_data: DP数据
 * @return 无
 */
static void __report_one_dp_data(const uint8_t dp_id, const uint8_t dp_type, const uint16_t dp_len, const uint8_t *dp_data)
{
    uint16_t i;
    /* 将DP数据存入数组 */
    sg_repo_array[DP_DATA_INDEX_OFFSET_ID] = dp_id;
    sg_repo_array[DP_DATA_INDEX_OFFSET_TYPE] = dp_type;
    sg_repo_array[DP_DATA_INDEX_OFFSET_LEN_H] = (uint8_t)(dp_len >> 8);
    sg_repo_array[DP_DATA_INDEX_OFFSET_LEN_L] = (uint8_t)dp_len;
    for (i = 0; i < dp_len; i++) {
        sg_repo_array[DP_DATA_INDEX_OFFSET_DATA + i] = *(dp_data + (dp_len-i-1));
    }
    /* 调用API发送DP数据 */
    tuya_ble_dp_data_send(sg_sn++, DP_SEND_TYPE_ACTIVE, DP_SEND_FOR_CLOUD_PANEL, DP_SEND_WITHOUT_RESPONSE, sg_repo_array, dp_len + DP_DATA_INDEX_OFFSET_DATA);
}

/**
 * @brief 上报温度数据
 * @param 无
 * @return 无
 */
void app_repo_dp_temp(void)
{
    if (sg_cur_temp != sg_prv_temp)) {
        __report_one_dp_data(DP_ID_TEMP_CURRENT, DT_VALUE, 4, (uint8_t *)&sg_cur_temp);
        sg_prv_temp = sg_cur_temp;
    }
}

/**
 * @brief 添加一个DP数据
 * @param[in] dp_id: DP ID
 * @param[in] dp_type: DP数据类型
 * @param[in] dp_len: DP数据长度
 * @param[in] dp_data: DP数据
 * @param[in] addr: DP存储起始地址
 * @return 已存储数据总长度
 */
static uint8_t __add_one_dp_data(const uint8_t dp_id, const uint8_t dp_type, const uint16_t dp_len, const uint8_t *dp_data, uint8_t *addr)
{
    uint16_t i;
    *(addr + DP_DATA_INDEX_OFFSET_ID) = dp_id;
    *(addr + DP_DATA_INDEX_OFFSET_TYPE) = dp_type;
    *(addr + DP_DATA_INDEX_OFFSET_LEN_H) = (UCHAR_T)(dp_len >> 8);
    *(addr + DP_DATA_INDEX_OFFSET_LEN_L) = (UCHAR_T)dp_len;
    for (i = 0; i < dp_len; i++) {
        *(addr + DP_DATA_INDEX_OFFSET_DATA + i) = *(dp_data + (dp_len-i-1));
    }
    return (dp_len + DP_DATA_INDEX_OFFSET_DATA);
}

/**
 * @brief 上报所有数据
 * @param 无
 * @return 无
 */
void app_repo_dp_all(void)
{
    uint32_t total_len = 0;
    /* 添加所有数据到DP组装上报数组 */
    total_len += __add_one_dp_data(DP_ID_TEMP_CURRENT, DT_VALUE, 4, &sg_cur_temp, sg_repo_array);
    total_len += __add_one_dp_data(DP_ID_TEMP_ALARM, DT_ENUM, 1, &sg_temp_alarm, sg_repo_array+total_len);
    /* 调用API发送DP数据 */
    tuya_ble_dp_data_send(sg_sn++, DP_SEND_TYPE_ACTIVE, DP_SEND_FOR_CLOUD_PANEL, DP_SEND_WITHOUT_RESPONSE, sg_repo_array, total_len);
}

4. 设备状态

API 列表

注：设备虚拟 ID 管理着云端历史数据。

API 说明

接口文件：tuya_ble_api.h

/**
 * @brief 查询蓝牙连接状态
 * @param 无
 * @return 蓝牙连接状态
 */
tuya_ble_connect_status_t tuya_ble_connect_status_get(void);

/**
 * @brief 设备端主动解绑
 * @param 无
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_device_unbind(void);

/**
 * @brief 重置设备
 * @param 无
 * @return 操作结果
 */
tuya_ble_status_t tuya_ble_device_factory_reset(void);

数据类型

/* 蓝牙网络状态 */
typedef enum {
    UNBONDING_UNCONN = 0,   /* 未绑定未连接 */
    UNBONDING_CONN,         /* 未绑定已连接 */
    BONDING_UNCONN,         /* 已绑定未连接 */
    BONDING_CONN,           /* 已绑定已连接 */
    BONDING_UNAUTH_CONN,    /* 已绑定已连接未鉴权 */
    UNBONDING_UNAUTH_CONN,  /* 未绑定已连接未鉴权 */
    UNKNOW_STATUS           /* 未知状态 */
} tuya_ble_connect_status_t;

蓝牙网络状态的含义说明如下：

应用示例

功能概述：应用程序申请重新配网时，查询蓝牙连接状态，如果已绑定则调用 API 进行主动解绑；应用程序申请设备重置时，调用 API 进行设备重置。

/**
 * @brief 设备解绑
 * @param 无
 * @return 无
 */
void app_unbind(void)
{
    tuya_ble_connect_status_t ble_conn_sta = tuya_ble_connect_status_get();
    if ((ble_conn_sta == BONDING_UNCONN) ||
        (ble_conn_sta == BONDING_CONN)   ||
        (ble_conn_sta == BONDING_UNAUTH_CONN)) {
        tuya_ble_device_unbind();
    }
}

/**
 * @brief 设备重置
 * @param 无
 * @return 无
 */
void app_reset(void)
{
    tuya_ble_device_factory_reset();
}

5. Callback

在 tuya_ble_sdk_demo.c 中，您可以看到 tuya_ble_sdk_callback 函数。该函数为初始化时注册的消息回调函数，用于涂鸦蓝牙 SDK（TUYA BLE SDK）向设备应用程序发送消息 (状态、数据等)。使用时在对应的 case 下添加要处理的内容即可。

常用的处理事件如下表所示，更多关于 Callback 的信息可参考 API 说明 - Callback。

创作打卡挑战赛

赢取流量/现金/CSDN周边激励大奖