File Transfer Service

This topic describes the file transfer service.

Overview

The standard Bluetooth Low Energy (LE) protocol supports the file transfer service, which is used to transfer files from apps to devices. Devices such as smart locks, smartwatches, and fitness trackers need to update data such as voice files and watch face files. These data is typically sent from apps to smart devices. To ensure that files are sent in a unified way, the standard Bluetooth LE protocol supports the file transfer service. You only need to implement the file sending protocol in the microcontroller unit (MCU) through the file sending interface provided by the Bluetooth module.

Supported firmware: Currently, only general Telink Bluetooth LE firmware v2.3.5 and later are supported. Other firmware versions will be supported in the future.

Related protocol

The following protocol applies to the file transfer service based on Bluetooth LE.

File transfer process

Send a file sending request (CMD-0xF5)

Before transferring a file, the Bluetooth module sends the file information to the MCU. The MCU returns a response based on the file information, indicating whether to receive the file and the maximum length of single packets for file reception.

Request from the module

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF5
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	1	File identifier length
	n	File identifier
	4	File version
	4	File length
	16	File MD5
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

• File type: The file type. Valid values:

  • 0: The common file type.
  • Other: Reserved.

• File ID: The file ID. It is defined at the application layer.

• File identifier length: The file identifier length.

• File identifier: The file identifier。

• File version: The file version. Its format is defined at the application layer.

• File length: The file length.

• File MD5: The file MD5 checksum.

Response from the MCU

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF5
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	1	Status
	2	Maximum packet length
	4	Length of the stored file
	16	MD5 checksum of the stored file
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

• File type and file ID: The same as those of the request frame.

• Status: The status. Valid values:

  • 0x00: File sending is allowed.

  • 0x01: File sending is not allowed because the file does not exist.

  • 0x02: The file exists but its version is earlier than or equal to the current version.

  • 0x03: The file size exceeds the upper limit.

  • Other: Reserved.

• Maximum packet length: The maximum packet length in bytes that the MCU supports. The Bluetooth module supports a maximum packet length of 1,024 bytes. If the MCU supports a maximum packet length exceeding 1,024 bytes, the maximum packet length of the Bluetooth module takes precedence. Otherwise, the maximum packet length of the MCU applies.

Send the file offset (CMD-0xF6)

Request from the module

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF6
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	4	File offset
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

• File type and file ID: The same as those of the request frame.

• File offset: The offset where the file transfer starts. It is 4 bytes in length.

Response from the MCU

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF6
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	4	File offset
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

• File type and file ID: The same as those of the request frame.

• File offset: The offset where the file transfer starts. It is 4 bytes in length.

Send the file data (CMD-0xF7)

Request from the module

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x10
Command	1	0xF7
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	2	Packet number
	2	Current packet data length
	2	CRC16 checksum of the current packet data
	n	Current packet data
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Response from the MCU

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF7
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	1	Status
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

File type and file ID: The same as those described in file information.

Status: The status. Valid return values:

• 0x00: Success.

• 0x01: Packet ID error.

• 0x02: Inconsistent length.

• 0x03: CRC verification failure.

• 0x04: Other.

Send an end-of-file indication (CMD-0xF8)

Request from the module

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF8
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

File type and file ID: The same as those described in file information.

Response from the MCU

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command	1	0xF8
Data length	2	Number of bytes in the data field
Data	1	File type
	2	File ID
	1	Status
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

File type and file ID: The same as those described in file information.

Status: The status. Valid return values:

• 0x00: Success.

• 0x01: Incorrect total data length.

• 0x02: MD5 checksum verification failure for the entire file.

• 0x03: Other.

FAQs

Q: How CRC16 checksums are calculated in the protocol?

A: CRC16 checksums are calculated based on the following function:

uint16_t tuya_ble_crc16_compute(uint8_t * p_data, uint16_t size, uint16_t * p_crc) {

    uint16_t poly[2] = {0, 0xa001};            //0x8005 <==> 0xa001
    uint16_t crc;
    int i, j;
    crc = (p_crc == NULL) ? 0xFFFF: *p_crc;

    for(j = size; j > 0; j--) {
        unsigned char ds = *p_data++;

        for(i = 0; i < 8; i++) {
            crc = (crc >> 1) ^ poly[(crc ^ ds) & 1];
            ds = ds >> 1;
        }
    }

    return crc;
}

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.