文件传输服务

文件传输服务分为文件下载功能和文件上传功能。文件传输服务支持大文件传输，支持多种文件类型。文件类型对应表可通过 附录三：文件类型值对应表 查询。

功能流程

文件下载流程

• 此示意图展示单个文件下载流程，多文件下载是在此示意图上的循环。
• 在文件传输的过程中，模组端如果因为数据超时发送退出，则退出所有下载流程。
• 在文件传输的过程中会 停止心跳查询，以及终止 DP 下发等其他的相关操作。文件传输流程只执行文件传输相关交互。

文件上传流程

指令列表

文件服务通过 0x37 命令和子命令，与 MCU 进行交互。

文件下载服务涉及以下协议指令：

命令字	命令说明
子命令 0x01	文件下载启动通知
子命令 0x02	文件下载信息同步
子命令 0x03	文件包下载传输

文件上传服务涉及以下协议指令：

命令字	命令说明
子命令 0x06	文件上传启动通知
子命令 0x07	文件包上传

文件传输状态控制服务涉及以下协议指令：

命令字	命令说明
子命令 0x04	MCU 主动获取/中断文件传输
子命令 0x05	文件执行结果上报
子命令 0x08	文件传输结果下发

文件下载服务

文件下载启动通知（子命令 0x01）

• 当下载事件被触发时，使用此命令通知 MCU。MCU 根据当前设备情况，确认是否执行文件下载操作。

• 当使用的业务为非扫地机语音文件下载功能时，此命令触发下载启动通知。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x01
	1	0x01：固定为 0x01
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 37 00 02 01 01 3a

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0003
数据	1	子命令：0x01
	1	Ret：是否同意启动下载服务 0x01：拒绝 0x00：同意
	1	Ret 为 0x00 时：此字节表示文件传输时每包文件的传输大小，目前支持的设置参数如下： 0x00：256 字节 0x01：512 字节 0x02：1024 字节 0x03：2048 字节 0x04：3072 字节 0x05：4096 字节 0x06：5120 字节 0x07：10240 字节 Ret 为 0x01 时：此字节表示拒绝启动下载服务的原因。0x01—0xFF：拒绝原因请参考 附录二：文件传输状态表
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 37 00 03 01 00 07 41

文件下载信息同步（子命令 0x02）

• 当下载事件被触发时，使用此命令通知 MCU 当前所下载文件信息。

• 扫地机语音文件下载业务无此功能命令。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0001+N
数据	1	子命令：0x02
	N	数据包内容，具体示例见下方 文件下载信息同步数据 N 示例
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

字段说明：

• name：文件的名称，您可自定义文件的名称。
• id：文件的 ID，该字段不再使用。
• no：文件的标识符。
• len：文件的长度。
• type：文件的类型，例如 .txt 和 .jpg 等。具体参考 附录三：文件类型值对应表。
• file_info：每个文件的自定义数据，需要对应文件有自定义填充的信息时，可使用此字段填充。此字段信息由 Wi-Fi 模组透传，具体的数据格式由 MCU 自定义。
• ext_info：此次下载文件的自定义数据。此字段信息由 Wi-Fi 模组透传，具体的数据格式由 MCU 自定义。
• act：对于此次下载的文件需要执行的操作，例如：打印、语音播放等，具体定义如下：

名称	打印	文本显示	语音播放	视频播放	存储
类型数值	1	2	3	4	5

文件下载信息同步数据 N 示例：

{
    "num": n,						//此次批量下载文件数量 
    "name": ["xx", "xx", "xx",..],			//文件名称 
    "id": [n,n,n,……],					//文件序号，与老项目兼容使用
    "no": ["xx","xx",...],				//文件标识符
    "len": [n,n,n,…],					//文件长度
    "type": [n,n,n,…],					//每个文件类型
    "file_info": ["xx", "xx",…],			//每个文件自定义数据
    "ext_info": "xxxx",                                 //自定义数据，用于此次下载的拓展数据
    "act": xx						//此次下载的文件的对应操作
}

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x02
	1	Ret：执行结果。 0x00：成功 0x01：失败
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 03 37 00 02 02 00 3d

文件包下载传输（子命令 0x03）

• 升级包传输数据格式：包偏移（unsigned short） + 包数据。

• MCU 若收到该帧数据长度为 5 且包偏移 ≥ 文件大小，则包传输结束。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x02 + 0x0004 + 数据包长度
数据	1	子命令：0x03
	1	当前对应传输文件偏移序号。第一个文件为 1，第二个文件为 2……
	4	当前文件包的包偏移量
	N	数据包内容
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：文件序号为 1，包偏移量为 0

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

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x03
	1	Ret：执行结果 0x00：成功 0x01：失败
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 03 37 00 02 03 00 3e

文件删除通知（子命令 0x20）

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0001 + 数据包长度
数据	1	子命令：0x20
	数据包长度	数据内容 ["xxx","xxx"]，xxx 为文件标识字符串 no [] 为删除全部文件
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0001
数据	1	子命令：0x20
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

文件上传服务

文件上传启动通知（子命令 0x06）

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0001 + 数据包长度
数据	1	子命令：0x06
	1	当前对应传输文件偏移序号。第一个文件为 1，第二个文件为 2……
	4	当前文件包的包偏移量
	N	数据包内容
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU 需要文件上传时，使用此命令通知模组进入文件上传状态。

MCU 发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0001+N
数据	1	子命令：0x06
	N	数据包内容，具体示例见下方 文件上传启动通知数据 N 示例
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

文件上传启动通知数据 N 示例：

{ 
    "num": n,                               //此次批量下载文件数量 
    "files": 
    [ 
        {
            "name": "xx", 		    //文件名称 
            "id": n, 			    //文件序号 
            "len": n, 			    //文件长度 
            "type": n, 			    //每个文件类型 
            "file_info": "xx"               //每个文件自定义数据 
        }, 
        { 
            "name": "xx", 		    //文件名称 
            "id": n, 			    //文件序号 
            "len": n, 			    //文件长度 
            "type": n,                      //每个文件类型 
            "file_info": "xx"               //每个文件自定义数据 
        }, 
        ... 
    ], 
    "ext_info": "xxxx"                    //扩展信息 
}

模组返回

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x06
	1	Ret：执行结果 0x00：成功 0x01：失败
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

文件上传（子命令 0x07）

• 文件包上传需先通过 文件上传启动通知 通知模组进入文件上传状态。
• 文件包传输数据格式：包偏移（unsigned short） + 包数据。
• 模组若收到该帧数据长度为 4 且包偏移 ≥ 文件大小，则包传输结束。

MCU 发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x00020x0004 + 数据包长度
数据	1	子命令：0x07
	2	当前对应传输文件 ID
	4	文件包偏移
	N	数据包内容
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

模组发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0003
数据	1	子命令：0x07
	1	Ret：操作结果 0x00：成功 0x01：失败 0x02：已取消
	1	Ret 为 0x00 时：此字节返回 0x00 Ret为 0x01 时：此字节表示失败原因，0x01—0x0FF，具体原因请参考 附录三：文件类型值对应表
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

文件传输状态控制

MCU 主动获取/中断文件传输（子命令 0x04）

当 MCU 在文件传输过程中需要主动获取传输状态、中断传输，可使用此命令。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0003
数据	1	子命令：0x04
	1	Ret： 0x00：终止传输（所有流程终止） 0x01：终止当前文件传输（多文件下载时，使用此命令只会终止当前传输的文件，并开启下个文件的传输） 0x02：获取当前传输状态 ……
	1	Ret： 0x00/0x01：此字节表示终止下载服务的原因 0x01—0xFF：拒绝原因，请参考 附录二：文件传输状态表 Ret 为其他：此字节填充 0x00
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 03 37 00 03 04 02 00 42

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0003
数据	1	子命令：0x04
	1	Ret： 0x01：终止传输 0x02：获取当前传输状态
	1	Ret 为 0x01 时：表示执行结果，0x00：成功，0x01：失败 Ret 为 0x02 时：表示的传输状态，请参考 附录二：文件传输状态表
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 37 00 03 04 02 00 3f

文件传输结果上报（子命令 0x05）

此功能命令是用于 MCU 反馈文件的执行状态，是否成功执行。此功能是 可选 功能，具体的执行依赖业务场景。当业务需要展示执行状态时，通过此功能命令反馈。协议中 Act 的数据也是可选的，根据具体业务来反馈。

此功能中的 ID 数据对应于 0x3702 命令中的 ID（文件序号），这个是唯一的，也需要做好对应关系。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x01+l+L+2
数据	1	子命令：0x05
	1	ID 的长度
	L	文件的 ID：对应于 0x3702 命令字中的 ID 数据
	1	Act： 0x00：执行完成 0x01：执行中 0x02：执行失败
	1	Act 为 0x00 时，此字节填充 0x00 Act 为 0x01 时，此字节填充执行进度百分比，例如 20% 就设置为 20 Act 为 0x02 时，此字段表示失败原因，具体参考 附录一：文件下载异常原因
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：打印机业务，打印 ID 为 10 的文件进行 20%

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

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x05
	1	Ret： 0x00：成功 0x01：数据不合法 0x02：上报失败
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 37 00 02 05 00 3d

文件传输结果下发（子命令 0x08）

此命令用于模组下发文件传输结果，无论是文件下载还是文件上传，均用此命令来通知 MCU 传输结果。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0004
数据	1	子命令：0x08
	1	0x01：文件下载 0x02：文件上传
	1	Ret：执行结果。 0x00：成功 0x01：失败
	1	Ret 为 0x00 时：此字节返回 0x00。 Ret 为 0x01 时：此字节表示失败原因，0x01—0x0FF，请参考 附录二：文件传输状态表
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 37 00 04 08 01 00 00 43

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0001
数据	1	子命令：0x08
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 03 37 00 01 08 42

附录

附录一：文件下载异常原因

异常原因描述	状态值
设备关机	0x00
传输超时	0x01
电量不足	0x02
过热	0x03
文件过大	0x04
设备空间不足	0x05
设备工作状态异常（示例：缺纸/卡纸/开盖）	0x06

附录二：文件传输状态表

传输状态	描述	状态值
状态 1	无文件传输触发	0x00
状态 2	启动文件传输中	0x01
状态 3	文件传输中	0x02
状态 4	文件传输/下载完成	0x03
状态 5	文件上传云端成功	0x04
状态 6	文件传输与 MCU 交互超时失败	0x05
状态 7	文件上传获取云端 URL 失败	0x06
状态 8	文件上传云端失败	0x07
状态 9	文件下载云端数据获取失败	0x08
状态 10	文件传输 MCU 回复失败	0x09

附录三：文件类型值对应表

说明	数值
txt	1
doc	2
pdf	3
excle	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