大数据上传

本文介绍大数据上传功能。

概述

概念介绍

蓝牙设备和涂鸦智能 App 之间的通信一般是基于 DP 数据通信，DP 数据通信可以满足蓝牙产品常见的低速、实时的数据通信，但是在某些特定场景下，蓝牙设备需要传输大量数据。大数据上传，即是按照特定的格式，将存储在设备本地的大量数据，快速传输到 App 端的数据通信协议。

例如：蓝牙智能手表、手环等品类，在断开蓝牙连接后，设备依然会持续产生分钟步数、分钟里程、分钟心率等数据，但是由于这些数据无法在离线情况下上传到手机，设备会先将此类离线数据暂时缓存在本地 Flash 中。当用户重新打开 App，进行蓝牙连接后，App 将通过大数据通道发送指令通知设备上传本地缓存的数据。

功能描述

大数据上传协议是蓝牙设备和 App 之间的数据通信协议。根据标记位（flag）的取值不同，大数据在设备端的存储结构和 App 端解析大数据的方式也有所区别。但是无论采用哪种数据结构，都不会影响大数据传输协议本身。也就是说，传输协议仅用于透传数据，是不依赖数据结构的，数据结构只用于本地存储和 App 解析数据。

如上图所示：

当 flag = 0 时，设备端存储采用 TLD 格式，App 端也会按照 TLD 格式进行数据解析，解析完成的数据由 App 端交由面板/云端进行展示。

TLD 格式由涂鸦预先定义，表示 DP 的集合，可以满足大部分常见的应用场景。使用标准的 TLD 格式可以降低产品面板的开发工作量，缩短开发周期。TLD 格式定义详见下文。

例如，智能手表、手环等品类，在传输端本地存储的分钟步数、分钟里程、分钟心率等数据时就是使用 TLD 格式进行存储和解析。

当 flag = 1 时，设备端存储采用自定义格式，App 端仅负责将数据从设备透传给面板/云端，面板/云端拿到数据后根据自定义格式进行解析并展示。

自定义格式由您和对应的产品经理/面板人员进行沟通协调，可以是任何合理的格式，能满足实际的存储需求和产品需求即可，大数据上传协议对此没有特别限制。当 TLD 格式不能满足需求时，就可以使用自定义格式，可以通过 bulk_type 的取值不同来区分多个不同的自定义格式。

例如：遥控器产品中用来记录灯管施工信息和 Log 信息的数据格式就是两种完全不同的数据格式。

TLD 格式：

• Type：
  • 1：同一时刻产生的 DP 数据，App 解析。
  • 2：同一时刻产生的 DP 数据，包含用于嵌入式内存对齐的无效数据部分，App 解析。
  • 其他值：预留。
• Len：Data 的长度。
• Data：长度受到每包数据最大长度限制。

当 Type 取值为 1 时，TLD 格式规范为：

序号	长度	字段	说明
1	1	Type	Type = 1
2~3	2	Len	Data 的长度
4~7	4	Data - unix_timestamp	Unix 时间戳
8~	DP 1 的总长度	Data - DP 1	DP 数据，见 DP 格式说明
……	……	……	……
~	DP n 的总长度	Data - DP n	DP 数据，见 DP 格式说明

当 Type 取值为 2 时，TLD 格式规范为：

序号	长度	字段	说明
1	1	Type	Type = 2
2~3	2	Len	Data 的长度
4~9	6	storage_header	与嵌入式存储结构相关，App 无需解析
10~11	2	valid_data_len	指 Unix 时间戳 + DP 的总长度，大端传输
12~15	4	Data - unix_timestamp	Unix 时间戳
16~	DP 1 的总长度	Data - DP 1	DP 数据，见 DP 格式说明
……	……	……	……
~	DP n 的总长度	Data - DP n	DP 数据，见 DP 格式说明
~	Len - 6 - 2 - valid_data_len	Invalid_data	无意义的填充数据，全部填 0，主要用于嵌入式内存对齐

DP 格式说明：

序号	长度	字段	说明
1	1	dp_id	在开发平台注册的 dp_id 序号
2	1	dp_type	#define DT_RAW 0 #define DT_BOOL 1 #define DT_VALUE 2 #define DT_STRING 3 #define DT_ENUM 4 #define DT_BITMAP 5
3~4	2	dp_len	DP 数据长度
5~	dp_len	dp_data	DP 数据

数据结构

TUYA_BLE_BULKDATA_EXTERNAL_PARAM_T

typedef struct {
    UINT8_T type;
    UINT8_T flag;
} TUYA_BLE_BULKDATA_EXTERNAL_PARAM_T;

• type：大数据类型。

  • 0x00：通用对接，用于涂鸦模组，SDK 开发人员不用关心。
  • 其他：如果需要 App 解析，则由涂鸦定义，目前仅支持 type 取值为 1 的类型。如果不需要 App 解析，由客户自定义。不同的产品维度可重复定义，从 1 开始。

• flag：对应协议中的 flag，是否需要 App 基线解析大数据。

  • 0x00：需要 App 基线解析数据。按照 DP 格式解析，type 取值为 1。
  • 0x01：不需要 App 基线解析数据。
  • 0x02：需要 App 基线解析数据。按照 type 的值进行解析，预留，暂未支持。

TUYA_BLE_BULKDATA_INFO_T

typedef struct {
    UINT32_T total_length;
    UINT32_T total_crc32;
    UINT32_T block_length;
} TUYA_BLE_BULKDATA_INFO_T;

• total_length：本 type 类型的大数据总长度。
• total_crc32：本 type 类型的大数据总 CRC32。
• block_length：大数据读取以块为单位，手机 App 每次发送要读取的块号（从 0 开始计数），块数据会以回复的单包长度为单位，分包发送。

TUYA_BLE_BULKDATA_CB_T

typedef VOID_T (*TUYA_BLE_BULKDATA_INFO_CB)(TUYA_BLE_BULKDATA_INFO_T* info);
typedef VOID_T (*TUYA_BLE_BULKDATA_REPORT_CB)(UINT8_T* p_block_buf, UINT32_T block_length, UINT32_T block_number);
typedef VOID_T (*TUYA_BLE_BULKDATA_ERASE_CB)(UINT8_T type, UINT8_T* status);

typedef struct {
    TUYA_BLE_BULKDATA_INFO_CB info_cb;
    TUYA_BLE_BULKDATA_REPORT_CB report_cb;
    TUYA_BLE_BULKDATA_ERASE_CB erase_cb;
} TUYA_BLE_BULKDATA_CB_T;

• info_cb：大数据信息填充回调接口，用于应用层将大数据的总长度、总 CRC32，单包传输大小传递给大数据传输组件。
• report_cb：大数据数据上报回调接口，用于应用层将本地存储的数据传递给大数据传输组件。
• erase_cb：大数据擦除回调接口，用于大数据传输组件通知应用层擦除本地数据，并将擦除结果返回给大数据传输组件。

接口说明

组件的多实例配置

大数据传输组件支持多实例，即一个组件即可满足不同类型的数据传输。

例如，在遥控器项目的实际案例中，bulk_type 取值为 1 表示传输 T8 灯管的施工信息，bulk_type 取值为 2 表示传输设备本地的 Log 信息，此时需要两个大数据传输组件的实例来单独处理两种不同类型信息的传输过程。这种情况下，通过设置 TUYA_BLE_BULKDATA_TYPE_NUM 的值为 2，来实现大数据传输组件的多实例功能。

TUYA_BLE_BULKDATA_TYPE_NUM 的默认值为 1。

#ifndef TUYA_BLE_BULKDATA_TYPE_NUM
#define TUYA_BLE_BULKDATA_TYPE_NUM                  (1)
#endif

如果需要修改 TUYA_BLE_BULKDATA_TYPE_NUM 的值，建议不要直接修改上述默认值，推荐在 app_config.h 中重新定义该宏的值。

组件的初始化

接口说明

UINT32_T tuya_ble_bulk_data_init(TUYA_BLE_BULKDATA_EXTERNAL_PARAM_T* param, TUYA_BLE_BULKDATA_CB_T* cb);

参数说明

参数	说明
param	详见上文中对 TUYA_BLE_BULKDATA_EXTERNAL_PARAM_T 的解析。
cb	详见上文中对 TUYA_BLE_BULKDATA_CB_T 的解析。

信息填充回调接口

用于应用层将大数据的总长度、总 CRC32 和单包传输大小传递给大数据传输组件。

接口说明

typedef VOID_T (*TUYA_BLE_BULKDATA_INFO_CB)(TUYA_BLE_BULKDATA_INFO_T* info);

参数说明

参数	说明
info	详见上文中对 TUYA_BLE_BULKDATA_INFO_T 的解析。 其中，total_length 和 total_crc32 由应用层根据已存储的数据计算得到，block_length 由应用层根据实际情况来决定，一般测试用值为 512，最大值不超过 TUYA_BLE_SEND_MAX_DATA_LEN（1490）。

数据上报回调接口

用于应用层将本地存储的数据传递给大数据传输组件。

接口说明

typedef VOID_T (*TUYA_BLE_BULKDATA_REPORT_CB)(UINT8_T* p_block_buf, UINT32_T block_length, UINT32_T block_number);

参数说明

参数	说明
p_block_buf	设备本地存储大数据的起始地址
block_length	本次要读取的大数据长度
block_number	本次要读取的大数据块号，用于计算本次要读取的偏移地址

擦除回调接口

用于大数据传输组件通知应用层擦除本地数据，并将擦除结果返回给大数据传输组件。

接口说明

typedef VOID_T (*TUYA_BLE_BULKDATA_ERASE_CB)(UINT8_T type, UINT8_T* status);

参数说明

参数	说明
type	本次要擦除的大数据类型
status	本次擦除结果

上传入口函数

大数据协议处理函数，该函数已经完全封装在大数据传输组件中，不需要您特别关注。

接口说明

VOID_T tuya_ble_bulk_data_demo_handler(tuya_ble_bulk_data_request_t* p_data);

参数说明

参数	说明
p_data	大数据协议数据，详见协议介绍

生成测试数据

该接口仅用于测试。

用于生成测试数据，配合上位机生成不同类型的测试数据，用于测试大数据传输的基本功能。

接口说明

UINT32_T tuya_ble_bulk_data_generation(UINT32_T timestep, UINT8_T* buf, UINT32_T size);

参数说明

参数	说明
timestep	测试数据的时间戳
buf	测试数据
size	测试数据的长度

使用方法

通信流程

代码开发

在 app_config.h 中启用大数据传输组件。

#define TUYA_BLE_FEATURE_BULKDATA_ENABLE 1

在 tuya_sdk_callback.c 中添加如下代码即可实现基本功能。如果测试功能（TUYA_SDK_TEST）是开启的，这些代码已经启用了。代码中涉及到的每个 API 在接口说明中都有涉及。

#include "tuya_ble_bulkdata_demo.h"

#define TUYA_BLE_BULKDATA_BLOCK_SIZE 512

STATIC TUYA_BLE_BULKDATA_EXTERNAL_PARAM_T tuya_ble_external_param = {
    .type = 1,
    .flag = NEED_PARSING_BY_APP,
};
STATIC TUYA_BLE_BULKDATA_CB_T tuya_ble_bulkdata_cb = {0};

VOID_T tuya_ble_bulkdata_info_cb(TUYA_BLE_BULKDATA_INFO_T* info)
{
//    info->total_length = 0;
//    info->total_crc32 = 0;
    info->block_length = TUYA_BLE_BULKDATA_BLOCK_SIZE;
}

VOID_T tuya_ble_bulkdata_report_cb(UINT8_T* p_block_buf, UINT32_T block_length, UINT32_T block_number)
{
    UINT32_T read_addr = BOARD_FLASH_SDK_TEST_START_ADDR + block_number*TUYA_BLE_BULKDATA_BLOCK_SIZE;
    tuya_ble_nv_read(read_addr, p_block_buf, block_length);
}

VOID_T tuya_ble_bulkdata_erase_cb(UINT8_T type, UINT8_T* status)
{
    // Erase all data by type
    // Return result by status
}

OPERATE_RET tuya_init_last(VOID_T)
{
    …………

    tuya_ble_bulkdata_cb.info_cb = tuya_ble_bulkdata_info_cb;
    tuya_ble_bulkdata_cb.report_cb = tuya_ble_bulkdata_report_cb;
    tuya_ble_bulkdata_cb.erase_cb = tuya_ble_bulkdata_erase_cb;
    tuya_ble_bulk_data_init(&tuya_ble_external_param, &tuya_ble_bulkdata_cb);

    return OPRT_OK;
}

功能测试

前置条件

• 您已经下载了涂鸦智能 App。
• 请确认您的设备处于配网状态。

操作步骤

通过上位机（模拟实际产品）和手机 App 进行数据交互。

1. 设置设备的 PID 为大数据专用 PID。相关代码可以搜索 case TEST_CID_SET_PID。

   

2. 使用涂鸦智能 App 搜索并连接设备。

   

3. 绑定成功。

   

4. 绑定成功后，使用上位机模拟生成要传输的大数据。相关代码可以搜索 case TEST_CID_SET_BULK_DATA。

   

5. 在设备面板首页下拉刷新，触发大数据传输，等待传输完成。

   

6. 在设备面板第二页查看传输完成的数据，单击 步数 选项卡。

   

7. 查看传输完成的数据。

   

   上位机使用的相关问题，请访问 Logic 上位机使用指南。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-蓝牙设备开发 版块进行沟通咨询。

咨询前建议首先查阅 官方资料 或参考已有帖子，并认真阅读 发帖规范。