Bulk Data Transfer

The bulk data transfer channel allows the data that is locally stored in a specified format to be quickly transferred to a mobile app.

Overview

With the bulk data transfer channel, the Bluetooth devices can quickly transmit a large amount of cached data to the mobile app after the Bluetooth is connected.

For example, the smart watch or fitness tracker will store the measured activity data such as pace, distance, and heart rate to the flash memory if the Bluetooth is disconnected. After the mobile app is connected to the Bluetooth device, it will send the bulk data transfer command to allow the device to transmit the cached data.

How it works

Commands

Request the bulk data information

• Mobile app to device communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.

• Device to mobile app communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.
  status	1	Status 0: success. The payload is valid. 1: The bulk_type is invalid, meaning that the payload is invalid or there is no payload. Others: reserved
  flag	1	Specify whether the mobile app parses the bulk data. 0: parsing 1: not parsing. The control panel inside the mobile app or the cloud parses the bulk data. Others: reserved
  total_length	4	The total length of the bulk data, in big-endian format.
  total_crc32	4	The total CRC32 value, in big-endian format.
  block_length	2	The block length. The bulk data is read by blocks. The mobile app sends the block number to the device to specify the block to be transmitted. A block is divided into packets for transmission.

Read blocks of data

Each time the device receives the read blocks of data command, it will transmit the data packets of the specified packet length by using the report bulk data command.

• Mobile app to device communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.
  block_number	2	The zero-based block number, identifying the block to be read.

• Device to mobile app communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.
  status	1	Status 0: success. The payload is valid. 1: The bulk_type is invalid, meaning that the payload is invalid or there is no payload. 2: The block_number is invalid. Others: reserved
  block_number	2	The block number, identifying the block to be read.
  block_length	2	The block length, indicating the length of the block to be read.
  packet_length	2	The packet length, indicating the maximum packet size for transmitting a block.
  block_crc16	2	The CRC16 checksum of the block.

Report bulk data

Each time the device receives the read blocks of data command, it will transmit a block in packets by using this command.

Example:

1. If the device has 9 KB data to be transmitted and specifies that the maximum block length is 2 KB, the data is divided into five blocks for transmission and the last block is 1 KB.
2. The mobile app sends a request the bulk data information command. The device returns the total length of 9 KB, the total CRC32 value, and the maximum block length of 2 KB.
3. The mobile app sends a read blocks of data command for reading the first block and specifies this block number as 0. The device returns the block length, the CRC16 value, and the maximum packet length. The mobile app starts the timer and waits for a block after receiving the response from the device.
4. The device starts transmitting a block in packets by using the report bulk data command.
5. After the mobile app receives a complete block through the report bulk data command, it will calculate the checksum. If the checksum is correct, it will read the next block. Otherwise, the failed block will be read again.
6. After all the blocks are read, the mobile app will verify the total length and CRC32.
7. If all the checks are successfully completed, the mobile app will send the erase bulk data command to delete all the cached data that has been transmitted.

• Device to mobile app communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.
  block_number	2	The block number, identifying the block to be transmitted.
  packet_number	2	The current packet number. Zero-based sequence number of data packets for the current block transmission.
  packet_length	2	The length of the current data packet.
  packet_data	packet_length	The current data packet.

Erase bulk data

• Mobile app to device communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.

• Device to mobile app communication

  Field	Bytes	Description
  version	1	The protocol version of the bulk data transfer is fixed to 0x00.
  bulk_type	1	The type of the bulk data, defined by specific products. Its value starts with 1. 0 indicates the generic data type.
  status	1	Status 0: success. 1: failure. Others: reserved.

TLD format

The type length data (TLD) format is used to parse data on the mobile app and store data on local flash. It does not apply to data parsing in the cloud. The bulk data must follow the TLD format to be transmitted to the mobile app for parsing. There are two format types. You can choose one as needed.

Field	Bytes	Description
Type	1	Format type 0x01: stores all the data point (DP) data produced simultaneously. The mobile app parses the data. 0x02: stores all the DP data produced simultaneously, including the overhead for data structure alignment. The mobile app parses the data. Others: reserved
Len	2	Data length
Data	Len	Payload

Type = 0x01

Stores all the data point (DP) data produced simultaneously. The mobile app parses the data.

Data format:

Field	Bytes	Description
UNIX_time	4	Unix timestamp
DP_1		Data of DP 1. For more information, see DP data format.
…
DP_n		Data of DP N. For more information, see DP data format.

Type = 0x02

Stores all the DP data produced simultaneously, including the overhead for data structure alignment. The mobile app parses the data.

Data format:

Field	Bytes	Description
storage_header	6	The overhead that is not parsed.
valid_data_len	2	The total length of the Unix timestamp and the DP data, in big-endian format.
UNIX_time	4	Unix timestamp
DP_1		Data of DP 1. For more information, see DP data format.
…
DP_n		Data of DP N. For more information, see DP data format.
invalid_data	Len-6-2-valid_data_len	The overhead that is not parsed.

DP data format

DP 1 data	–				DP n data
1	2	3 to 4	5 and greater	–	n	n+1	n+2 to n+3	n+4 and greater
Dp_id	Dp_type	Dp_len	Dp_data	–	Dp_id	Dp_type	Dp_len	Dp_data

API

tuya_ble_bulk_data_read_block_size_get

Function	tuya_ble_bulk_data_read_block_size_get
Function prototype	uint32_t tuya_ble_bulk_data_read_block_size_get(void)
Feature description	Read the block length
Parameters	None
Return value	The block length.
Note	tuya_ble_bulk_data_read_block_size_get is used to determine the length of a block based on the maximum transmission unit (MTU) and Bluetooth stack.

Example:

static uint32_t bulk_data_read_block_size = 0;

void tuya_ble_app_bulk_data_handler(tuya_ble_bulk_data_request_t *p_data)
{
    switch (p_data->evt)
    {
        case TUYA_BLE_BULK_DATA_EVT_READ_INFO: {
            bulk_data_read_block_size = tuya_ble_bulk_data_read_block_size_get();
        } break;
		//...
    }

}

tuya_ble_bulk_data_response

Function	tuya_ble_bulk_data_response
Function prototype	tuya_ble_status_t tuya_ble_bulk_data_response(tuya_ble_bulk_data_response_t *p_data)
Feature description	Respond to bulk data transfer request
Parameters	p_data[in]: the return value of the bulk data request
Return value	TUYA_BLE_SUCCESS: success TUYA_BLE_ERR_INVALID_STATE: invalid status, such as Bluetooth disconnected. Bulk data transmission cannot be started. TUYA_BLE_ERR_INVALID_LENGTH: data length error. TUYA_BLE_ERR_NO_MEM: failed to request memory allocation. TUYA_BLE_ERR_NO_EVENT: the queue is full.
Note	The device calls this function to return a response on receiving the bulk data request. The return value must follow the format defined in commands.

Example:

void tuya_ble_app_bulk_data_handler(tuya_ble_bulk_data_request_t *p_data)
{
    uint8_t rsp_flag = 1;
    tuya_ble_bulk_data_response_t rsp_data;

    switch (p_data->evt)
    {
        case TUYA_BLE_BULK_DATA_EVT_READ_INFO: {
            //...
        } break;

        case TUYA_BLE_BULK_DATA_EVT_READ_BLOCK: {
            //...
        } break;

        case TUYA_BLE_BULK_DATA_EVT_SEND_DATA: {
            //...
        } break;

        case TUYA_BLE_BULK_DATA_EVT_ERASE: {
            //...
        } break;

        default: {
            rsp_flag = 0;
        } break;
    }

    if (rsp_flag)
    {
        tuya_ble_bulk_data_response(&rsp_data);
    }
}

Add bulk data transfer events

The Bluetooth SDK sends data or events to the mobile app using messages or registered callbacks.

After the Bluetooth module receives a bulk data transfer command from the mobile app, the Bluetooth SDK will send the following callbacks to the program accordingly. The specific callback handler is intended to be implemented by you. For more information, see Register the message queue.

TUYA_BLE_CB_EVT_BULK_DATA

Event	TUYA_BLE_CB_EVT_BULK_DATA
Data structure	tuya_ble_bulk_data_request_t
Description	Bulk data transfer request callback.
Note	You can implement bulk data transfer handlers in this callback.

Data structure

typedef enum {
    TUYA_BLE_BULK_DATA_EVT_READ_INFO,          /**< Request the bulk data information */
    TUYA_BLE_BULK_DATA_EVT_READ_BLOCK,	     	/**< 	Read blocks of data */
    TUYA_BLE_BULK_DATA_EVT_SEND_DATA,	     	/**< Report bulk data */
    TUYA_BLE_BULK_DATA_EVT_ERASE,               /**< 	Erase bulk data */
    TUYA_BLE_BULK_DATA_EVT_UNKONWN,            /**< Unknown event */
} tuya_ble_bulk_data_evt_type_t;

typedef struct {
    uint16_t block_number;
} tuya_ble_bulk_data_evt_read_block_req_t;

typedef struct {
    uint16_t block_number;
} tuya_ble_bulk_data_evt_send_data_req_t;

typedef struct {
    tuya_ble_bulk_data_evt_type_t evt;  //  The specific bulk data transfer command
    uint8_t bulk_type;
    union
    {
        tuya_ble_bulk_data_evt_read_block_req_t block_data_req_data;
        tuya_ble_bulk_data_evt_send_data_req_t send_data_req_data;
    } params;
} tuya_ble_bulk_data_request_t;

Example:

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t *event)
{
    switch (event->evt)
    {
        //...

        case TUYA_BLE_CB_EVT_BULK_DATA: {  // Implement bulk data transfer handlers.
            tuya_ble_app_bulk_data_handler(&event->bulk_req_data);
        } break;

                //…
    }
}

Sample

Data structure

typedef struct {
    uint8_t status;  /**< 0: success, with valid payload. 1: invalid, with invalid payload or without any payloads. Others: reserved */
    uint8_t flag;  /**< 0: The mobile app parses the bulk data. 1: The control panel inside the mobile app or the cloud parses the bulk data. */
    uint32_t bulk_data_length;  		 /**<  The total length */
    uint32_t bulk_data_crc;	 			  /**<  The total CRC32 */
    uint16_t block_data_length;	 		 /**< 	The block length */
} tuya_ble_bulk_data_evt_read_info_res_t;

typedef struct {
    uint8_t status;  					    /**< 0: success. 1: The format type is invalid. 2: The block number is invalid. Others: reserved */
    uint16_t block_number;	 			  /**<  The block number */
    uint16_t block_data_length;	 		 /**< 	The block length */
    uint16_t block_data_crc16;	 		 /**<  The CRC16 value of a block*/
    uint16_t max_packet_data_length;  /**< The maximum packet size for transmitting a block */
} tuya_ble_bulk_data_evt_read_block_res_t;

typedef struct {
    uint16_t current_block_number;	 	/**< The current block number */
    uint16_t current_block_length;	 	/**< The current block length */
    uint8_t  *p_current_block_data;	 	/**< The pointer to the current block */
} tuya_ble_bulk_data_evt_send_data_res_t;

typedef struct {
    uint8_t status;  					    /**< 0: success. 1: failure. Others: reserved */
} tuya_ble_bulk_data_evt_erase_res_t;

typedef struct {
    tuya_ble_bulk_data_evt_type_t evt;
    uint8_t bulk_type;
    union
    {
        tuya_ble_bulk_data_evt_read_info_res_t bulk_info_res_data;
        tuya_ble_bulk_data_evt_read_block_res_t block_res_data;
        tuya_ble_bulk_data_evt_send_data_res_t send_res_data;
        tuya_ble_bulk_data_evt_erase_res_t erase_res_data;
    } params;
} tuya_ble_bulk_data_response_t;

Example:

void tuya_ble_app_bulk_data_handler(tuya_ble_bulk_data_request_t *p_data)
{
    uint8_t rsp_flag = 1;
    tuya_ble_bulk_data_response_t rsp_data;

    switch (p_data->evt)
    {
        case TUYA_BLE_BULK_DATA_EVT_READ_INFO: {
            // Parse the `p_data`.
            // Assign values to `rsp_data.bulk_info_res_data`
        } break;

        case TUYA_BLE_BULK_DATA_EVT_READ_BLOCK: {
            // Parse `p_data->params.block_data_req_data`
            // Assign values to `rsp_data.block_res_data`
        } break;

        case TUYA_BLE_BULK_DATA_EVT_SEND_DATA: {
            // Parse `p_data->params.send_data_req_data`
            // Assign values to  `rsp_data.send_res_data`
        } break;

        case TUYA_BLE_BULK_DATA_EVT_ERASE: {
            // Parse the `p_data`.
            // Assign values to `rsp_data.erase_res_data`
        } break;

        default: {
            rsp_flag = 0;
        } break;
    }

    if (rsp_flag)
    {
        tuya_ble_bulk_data_response(&rsp_data);       // Return values
        if (rsp_data.evt == TUYA_BLE_BULK_DATA_EVT_SEND_DATA) {
            tuya_ble_free(rsp_data.params.send_res_data.p_current_block_data);
        }
    }
}