File Transfer

This topic describes the file transfer service that supports file upload and download. This service enables you to transfer various file types and large files. See Appendix 3: File type for the supported file types.

Processes

File download

• This diagram shows the download progress of a single file. Downloading multiple files works the same way, which repeats the process until all files are downloaded.
• During file transfer, if the module exits the transfer process due to a time-out, the whole process stops.
• During file transfer, heartbeat checks and DP data sending stop.

File upload

Commands

The file transfer service interacts with the MCU through the command 0x37 and its subcommands.

The commands used in the file download process.

Command	Description
Subcommand: 0x01	Initiate file download
Subcommand: 0x02	Sync file information
Subcommand: 0x03	Download file

The commands used in the file upload process.

Command	Description
Subcommand: 0x06	Initiate file upload
Subcommand: 0x07	Upload file

The commands used to control the file transfer process.

Command	Description
Subcommand: 0x04	The MCU initiates or terminates file transfer.
Subcommand: 0x05	Report the result of executing the file transfer command.
Subcommand: 0x08	Send the result of the file transfer.

File download

Initiate file download (subcommand 0x01)

• The module sends this command to notify the MCU of a file download task. The MCU returns whether to execute the download task based on the current operation.

• This command does not apply to download tasks for robot vacuum voice files.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0002
Data	1	Subcommand: 0x01
	1	0x01: Fixed to 0x01.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 37 00 02 01 01 3a

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0003
Data	1	Subcommand: 0x01
	1	Ret: Whether to execute file download. 0x01: Reject 0x00: Accept
	1	When Ret is 0x00, this field indicates the size of each packet for transmission. Valid values: 0x00: 256 bytes 0x01: 512 bytes 0x02: 1,024 bytes 0x03: 2,048 bytes 0x04: 3,072 bytes 0x05: 4,096 bytes 0x06: 5,120 bytes 0x07: 10,240 bytes If Ret is 0x01, this field indicates the rejection reason. 0x01 to 0xFF: See Appendix 2: File transfer status for rejection reasons.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 37 00 03 01 00 07 41

Sync file information (subcommand 0x02)

• The module sends this command to notify the MCU of the information of the download file.

• This command does not apply to download tasks for robot vacuum voice files.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0001 + N
Data	1	Subcommand: 0x02
	N	The payload. See the example of N below.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Field description:

• name: The file name, which can be user-defined.
• id: The file ID. This field is deprecated.
• no: The file identifier.
• len: The file length.
• type: The file type, such as TXT and JPG. See Appendix 3: File type for the supported file types.
• file_info: The user-defined information for each file. The module sends the raw data of this field to the MCU, with the data format being defined by the MCU.
• ext_info: The user-defined information for the file to download. The module sends the raw data of this field to the MCU, with the data format being defined by the MCU.
• act: The action to the download task, such as print and audio play. The following table lists the definition.

Name	Print	Text display	Audio play	Video play	Storage
Type value	1	2	3	4	5

The example of N in a file download request:

{
    "num": n,						// The number of files to be downloaded.
    "name": ["xx", "xx", "xx",..],			// The file name.
    "id": [n,n,n,……],					// The file ID, compatible with legacy projects.
    "no": ["xx","xx",...],				// The file identifier.
    "len": [n,n,n,…],					// The file length.
    "type": [n,n,n,…],					// The type of each file.
    "file_info": ["xx", "xx",…],			// The user-defined data for each file.
    "ext_info": "xxxx",                                 // The user-defined additional data for the file to be downloaded.
    "act": xx						// The action to the file to be downloaded.
}

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0002
Data	1	Subcommand: 0x02
	1	Ret: The result of command execution. 0x00: Success. 0x01: Failure.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 37 00 02 02 00 3d

Download file (subcommand 0x03)

• Data format: packet offset (unsigned short) + payload data.

• When the MCU receives a frame with a length of five bytes and the packet offset is equal to or greater than the file size, the transfer is completed.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x02 + 0x0004 + packet length
Data	1	Subcommand: 0x03
	1	The sequence number of the file being transferred. The first file is 1, the second file is 2, and so on.
	4	The packet offset.
	N	The payload.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: The sequence number of the file is 1 and the packet offset is 0.

55 aa 00 37 xx xx 03 01 00 00 00 00 00 xx xx xx xx xx

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0002
Data	1	Subcommand: 0x03
	1	Ret: The result of command execution. 0x00: Success. 0x01: Failure.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 37 00 02 03 00 3e

Delete file (subcommand 0x20)

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0001 + packet length
Data	1	Subcommand: 0x20
	Packet length	The payload. ["xxx","xxx"]. xxx is the file identifier no. [] means to delete all files.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0001
Data	1	Subcommand: 0x20
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

File upload

Initiate file upload (subcommand 0x06)

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0001 + packet length
Data	1	Subcommand: 0x06
	1	The sequence number of the file being transferred. The first file is 1, the second file is 2, and so on.
	4	The packet offset.
	N	The payload.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The MCU sends this command to the module to request uploading files.

The MCU sends the following data.

Field	Length (byte)	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0001 + N
Data	1	Subcommand: 0x06
	N	The payload. See the example of N below.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The example of N in a file upload request:

{ 
    "num": n,                               // The number of files to be downloaded.
    "files": 
    [ 
        {
            "name": "xx", 		    // The file name.
            "id": n, 			    // The file ID, compatible with legacy projects.
            "len": n, 			    // The file length.
            "type": n, 			    // The type of each file.
            "file_info": "xx"               // The user-defined data for each file.
        }, 
        { 
            "name": "xx", 		    // The file name.
            "id": n, 			    // The file ID
            "len": n, 			    // The file length.
            "type": n,                      // The type of each file.
            "file_info": "xx"               // The user-defined data for each file.
        }, 
        ... 
    ], 
    "ext_info": "xxxx"                    // The additional information.
}

The module returns the following data.

Field	Length (byte)	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0002
Data	1	Subcommand: 0x06
	1	Ret: The result of command execution. 0x00: Success. 0x01: Failure.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Upload file (subcommand 0x07)

• To upload a file, the MCU must first send a file upload request to the module.
• Data format: packet offset (unsigned short) + payload data.
• When the module receives a frame with a length of four bytes and the packet offset is equal to or greater than the file size, the transfer is completed.

The MCU sends the following data.

Field	Length (byte)	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x00020x0004 + packet length
Data	1	Subcommand: 0x07
	2	The ID of the file being transferred.
	4	The packet offset.
	N	The payload.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module sends the following data.

Field	Length (byte)	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0003
Data	1	Subcommand: 0x07
	1	Ret: The result of operation. 0x00: Success. 0x01: Failure. 0x02: Canceled.
	1	When Ret is 0x00, 0x00 is returned. When Ret is 0x01, an error code from 0x01 to 0x0FF is returned. For more information, see Appendix 3: File type.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Control file transfer

MCU initiates or terminates file transfer (subcommand 0x04)

The MCU can use this command to request the transfer status or terminate a file transfer.

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0003
Data	1	Subcommand: 0x04
	1	Ret: 0x00: Terminate all file transfers. 0x01: Terminate the current file transfer. When multiple files are being downloaded, this command will terminate the current transfer and proceed to downloading the next file. 0x02: Get the current file transfer status. …
	1	Ret: 0x00/0x01: The reason for terminating the file download. 0x01 to 0xFF: The rejection reason. See Appendix 2: File transfer status. Ret for other values: This field is 0x00.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 37 00 03 04 02 00 42

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0003
Data	1	Subcommand: 0x04
	1	Ret: 0x01: Terminate the file transfer. 0x02: Get the current file transfer status.
	1	When Ret is 0x01: This field indicates the operation result, 0x00 for success and 0x01 for failure. When Ret is 0x02: This field indicates the transfer status. See Appendix 2: File transfer status.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 37 00 03 04 02 00 3f

Report file transfer result (subcommand 0x05)

The MCU can use this command to send the execution status of the file transfer to the module. This command is optional. You can implement it to present the execution status. Data of Act is also optional, depending on your product features.

The file ID is the file sequence number specified with the command 0x3702. Make sure they match.

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x01 + l + L + 2
Data	1	Subcommand: 0x05
	1	The length of ID.
	L	The ID of the file, corresponding to the id field specified with the command 0x3702.
	1	Act: 0x00: Task is done. 0x01: Task is in progress. 0x02: Task fails.
	1	When Act is 0x00, set this field to 0x00. When Act is 0x01, set this field to the progress in percentage, for example, the value 20 for 20%. When Act is 0x02, this field indicates the error code. For more information, see Appendix 1: File download exceptions.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: A printer is printing a file of ID 10 and the task progress is at 20%.

55 aa 03 37 05 05 01 0a 01 14 63

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0002
Data	1	Subcommand: 0x05
	1	Ret: 0x00: Success. 0x01: Invalid data. 0x02: Failure.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 37 00 02 05 00 3d

Send file transfer result (subcommand 0x08)

The module can use this command to notify the MCU of the result of file download or upload.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x37
Data length	2	0x0004
Data	1	Subcommand: 0x08
	1	0x01: File download. 0x02: File upload.
	1	Ret: The result of command execution. 0x00: Success. 0x01: Failure.
	1	When Ret is 0x00, 0x00 is returned. When Ret is 0x01, an error code from 0x01 to 0x0FF is returned. For more information, see Appendix 2: File transfer status.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 37 00 04 08 01 00 00 43

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x37
Data length	2	0x0001
Data	1	Subcommand: 0x08
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 37 00 01 08 42

Appendix

Appendix 1: File download exceptions

Description	Status value
Device is shut down.	0x00
File transfer times out.	0x01
Battery level is low.	0x02
Device is overheating.	0x03
File is large.	0x04
Memory is not enough.	0x05
Operation anomaly occurs. For example, out of paper, paper jam, and cover open.	0x06

Appendix 2: File transfer status

Status	Description	Status value
Status 1	No file transfer task.	0x00
Status 2	File transfer is starting.	0x01
Status 3	File transfer is in progress.	0x02
Status 4	File transfer/download is completed.	0x03
Status 5	File is uploaded to the server.	0x04
Status 6	File transfer with the MCU times out.	0x05
Status 7	Failed to get the URL for file upload.	0x06
Status 8	Failed to upload the file to the server.	0x07
Status 9	Failed to get the file from the server.	0x08
Status 10	The MCU fails to respond to file transfer.	0x09

Appendix 3: File type

Description	Value
TXT	1
doc	2
PDF	3
EXCEL	4
PNG	5
JPG	6
BMP	7
TIF	8
GIF	9
PCX	10
TGA	11
Exif	12
FPX	13
SVG	14
PSD	15
CDR	16
PCD	17
DXF	18
UFO	19
EPS	20
AI	21
Raw	22
WMF	23
WebP	24
AVIF	25
WAV	26
FLAC	27
APE	28
ALAC	29
WavPack (WV)	30
MP3	31
AAC	32
Ogg Vorbis	33
Opus	34
MP4	35