FTP/FTPS

FTP

作者：闫国梁

最后更新时间：2020年8月12日

关键词：FTP，文件服务器，FTP搭建

1 概述

FTP（File Transfer Protocol，文件传输协议） 是 TCP/IP 协议组中的协议之一。FTP协议包括两个组成部分，其一为FTP服务器，其二为FTP客户端。其中FTP服务器用来存储文件，用户可以使用FTP客户端通过FTP协议访问位于FTP服务器上的资源。在开发网站的时候，通常利用FTP协议把网页或程序传到Web服务器上。此外，由于FTP传输效率非常高，在网络上传输大的文件时，一般也采用该协议。

默认情况下FTP协议使用TCP端口中的 20和21这两个端口，其中20用于传输数据，21用于传输控制信息。但是，是否使用20作为传输数据的端口与FTP使用的传输模式有关，如果采用主动模式，那么数据传输端口就是20；如果采用被动模式，则具体最终使用哪个端口要服务器端和客户端协商决定。模块ftp默认是被动模式，不支持主动模式，无法设置主动模式，公网下要想模块正常连接服务器，服务器肯定不能设置为主动模式，否则哪家模块都不能用。

2 相关AT指令介绍

2.1 设置 FTP 控制端口：AT+FTPPORT

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPPORT=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPPORT?

+FTPPORT: OK

测试命令

AT+FTPPORT=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 控制端口号

1~65535

缺省值为 21

2.2 设置 FTP 主动或被动模式：AT+FTPMODE

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPMODE=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPMODE?

+FTPMODE: OK

测试命令

AT+FTPMODE=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 主动被动模式

0

主动模式（暂不支持）

1

被动模式

2.3 设置 FTP 数据传输类型：AT+FTPTYPE

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPTYPE=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPTYPE?

+FTPTYPE: OK

测试命令

AT+FTPTYPE=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 数据传输类型

“A”

FTP ASCII 字符集

“I”

FTP Binary 字符集

2.4 设置 FTP 输入类型：AT+FTPPUTOPT

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPPUTOPT=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPPUTOPT?

+FTPPUTOPT: OK

测试命令

AT+FTPPUTOPT=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 数据传输类型

“APPE”

添加文件

“STOU”

存储唯一的文件

“STOR”

存储文件

2.5 设置 FTP 承载标识：AT+FTPCID

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPCID=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPCID?

+FTPCID: OK

测试命令

AT+FTPCID=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 承载标识

1~3

同+SAPBR 中定义。缺省值为 0。

2.6 设置 FTP 下载续传：AT+FTPREST

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPREST=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPREST?

+FTPREST: OK

测试命令

AT+FTPREST=?

OK

参数定义：

参数

定义

取值

对取值的说明

要续传的断点

2.7 设置 FTP 服务器地址：AT+FTPSERV

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPSERV=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPSERV?

+FTPSERV: OK

测试命令

AT+FTPSERV=?

OK

参数定义：

参 数

定义

取 | 对取值的说明 值 |

FTP 服务器地址， IP 或域名

32-bit 十 进 制 数 ， 用 . 分 开 ， 形 式 如 ： xxx.xxx.xxx.xxx。 如果是 DNS，则为长度不超过 49 的 ASCII 字符串。

2.8 设置 FTP 用户名称：AT+FTPUN

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPUN=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPUN?

+FTPUN: OK

测试命令

AT+FTPUN=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 用户名

为长度不超过 49 的 ASCII 字符串。

2.9 设置 FTP 密码：AT+FTPPW

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPPW=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPPW?

+FTPPW: OK

测试命令

AT+FTPPW=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 密码

为长度不超过 49 的 ASCII 字符串。

2.10 设置 FTP 下载文件名称：AT+FTPGETNAME

设置服务器端目标文件的名称。

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPGETNAME=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPGETNAME?

+FTPGETNAME: OK

测试命令

AT+FTPGETNAME=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 下载文件名称

为长度不超过 99 的 ASCII 字符串。

2.11 设置 FTP 下载文件路径：AT+FTPGETPATH

本命令是设置目标文件在服务器端的路径。

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPGETPATH=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPGETPATH?

+FTPGETPATH: OK

测试命令

AT+FTPGETPATH=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 下载文件路径

长度不超过 255 的 ASCII 字符串。

2.12 设置 FTP 上传文件名称：AT+FTPPUTNAME

设置将文件上传到服务器后的保存名称。

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPPUTNAME=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPPUTNAME?

+FTPPUTNAME: OK

测试命令

AT+FTPPUTNAME=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 上传文件名称

长度不超过 99 的 ASCII 字符串。

2.13 设置 FTP 上传文件路径：AT+FTPPUTPATH

设置将文件上传到服务器后的保存目录。

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPPUTPATH=

OK

正常返回

ERROR

输入格式有误

查询命令

AT+FTPPUTPATH?

+FTPPUTPATH: OK

测试命令

AT+FTPPUTPATH=?

OK

参数定义：

参数

定义

取值

对取值的说明

FTP 上传文件路径

长度不超过 99 的 ASCII 字符串。

2.14 远程服务器上创建文件目录：AT+FTPMKD

语法规则：

命令类型

语法

返回

说明

执行命令

AT+FTPMKD

OK +FTPMKD: 1,0

创建成功

OK +FTPMKD: 1,

创建失败

+CME ERROR:

如果是命令错误

测试命令

AT+FTPMKD=?

OK

注意事项

执行命令创建的 文件目录由命令A T+FTPGETPATH定义

参数定义：

参数

定义

取值

对取值的说明

错误码

与 AT+FTPGET 命令的定义相同

2.15 远程服务器上删除文件目录：AT+FTPRMD

语法规则：

命令类型

语法

返回

说明

执行命令

AT+FTPRMD

OK +FTPRMD: 1,0

删除成功

OK +FTPRMD: 1,

删除失败

+CME ERROR:

如果是命令错误

测试命令

AT+FTPRMD=?

OK

注意事项

执行命令删除的 文件目录由命令A T+FTPGETPATH定义

参数定义：

参数

定义

取值

对取值的说明

错误码

与 AT+FTPGET 命令的定义相同

2.16 下载文件：AT+FTPGET

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPGET=[,]

OK

输入AT+FTPGET=1 的返回

+FTPGET:2, ……..数据……….. OK

输入： AT+FTPGET=2, 的返回

URC 上报

+FTPGET:1,1

输入 AT+FTPGET=1后，有 此上报，表示有数 据了，第一个参数 1表示为1

+FTPGET:1,

输入AT+FTPGET= 1后，有此上报，表 示FTP下载失败，第 一个参数1表示为1

+FTPGET:1,0

表示 数据传输结束，第 一个参数1表示为1

测试命令

AT+FTPGET=?

OK

参数定义：

参数

定义

取值

对取值的说明

工作模式

1

打开 FTP 会话

2

读入 FTP 下载数据

请求读入的数据长度

1~1460

确认读入的数据长度

1~1460

可能小于。0 表示没有数据可以读入。

错误码

61

网络错误 net error

62

DNS 错误 DNS error

63

连接错误 connect error

64

超时 timeout

65

服务器错误 server error

66

操作禁止operation not allowed

70

应答错误 reply error

71

用户错误 user error

72

口令错误 password error

73

类型错误type error

74

保持错误 rest error

75

被动错误 passive error

76

主动错误active error

77

操作错误 operate error

78

上传错误 upload error

79

下载错误 download error

80~84

FTP SSL 连接错误

85

文件错误

86

主动退出

2.17 上传文件：AT+FTPPUT

语法规则：

命 | 语法 令 | 类 | 型 |

返回

说明

设 | AT | OK 置 | +FTPPUT=[,] | 命 | | 令 | |

输入AT+FTPPUT=1的返回

+FTPPUT:2, …….. //input data here OK

输入： AT+FTPPUT=2, 的返回

OK +FTPPUT: 1,0

输入： AT+FTPPUT=2,0 的返回

U | + R | FTPPUT:1,1, C | 上 | 报 |

输 入AT+FTPPUT=1后，有此上 报，表示可以上传数据了此 时通过输入AT+FTPPUT=2,上 传数据第一个参数1表示为1

+FTPPUT:1,0

表示数据传输会话 结束。第一个参数1表示为1

+FTPPUT:1,

如果 =1，而且FTP会话失败。错 误码定义请参考AT+FTPGET 错误码定义

测 | AT+FTPPUT=? | OK 试 | | 命 | | 令 | |

参数定义：

参数

定义

取值

对取值的说明

FTP 上传工作模式

1

打开 FTP 会话

2

写 FTP 上传数据

请求上传的数据长度

0-

确认可以上传的数据长度

单次可以上传的最大的长度，取决于网络状态

2.18 下载文件(扩展)：AT+FTPEXTGET

语法规则：

命 | 语法 令 | 类 | 型 |

返回

说 明

设 | AT+FTPEXTGET= 置 | 命 | 令 |

OK

当 =0 或1

AT+FTPEXTGET=,

+FTPEXTGET:2, OK

当 =2

AT+FTPEXTGET=,,

+FTPEXTGET:3, …… //这里是输出到串口的数据 OK

当 =3

查 | AT+FTPEXTGET? 询 | 命 | 令 |

+FTPEXTGET: [,] OK

测 | AT+FTPEXTGET=? 试 | 命 | 令 |

OK

U | +FTPEXTGET:1,0 R | C | 上 | 报 |

=1且 FTPEXTGET结束，会有如此上报

+FTPEXTGET:1,

=1且 FTPEXTGET出错，会有如此上报 。错误码定义请参考AT+FTPGET 错误码定义

+FTPEXTGET:2,

=2

+FTPEXTGET:3,

=3

注 | 1） 当FTPEXTPUT 意 | =1时，不可使用本命令 2） 事 | 如 项 | 果文件大小()<300KB，可以使

用这个命令；如果文件大小()
>=300KB，请使用缺省的FTPGET
method (AT+FTPEXTGET=0) 3）
本命令的使用方法请参考本
章最后一部分：使用方法举例

参数定义：

参数

定义

取值

对取值的说明

工作模式

0

使用缺省的FTPGET方法

1

使用扩展的FTPGET方法

2

保存下载的数据到文件中

3

输出下载的数据到串口

文件名

字符串型，最长64个字符

保存到文件的所有数据长度，用于mode 2

<302512

单位：字节

输出到串口的数据长度，用于mode 3

<302512

单位：字节

读取文件数据的起始位置，用于mode 3

读取长度，用于mode 3

单位：字节

FTPEXTGET的状态

0

不在FTPEXTGET过程中

1

处于FTPEXTGET过程

错误码

与AT+FTPGET命令的定义相同

2.19 上传文件(扩展)：AT+FTPEXTPUT

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPEXTPUT=[,,,]

OK

当=0或1

+FTPEXTPUT: , …… //这里从串口输入数据 OK

当=2

测试命令

AT+FTPEXTPUT=?

OK

注意事项

本命令的使用方法请参考本章最后一部分：使用方法举例

参数定义：

参数

定义

取值

对取值的说明

工作模式

0

使用缺省的FTPPUT方法

1

使用扩展的FTPPUT方法

2

将数据PUT到RAM

每次PUT的起始位置

0-300K

单位：byte

每次PUT的数据长度

0-300K

单位：byte

串口数据传输的超时时间

1000-1000000

单位：ms

2.20 下载文件并保存到文件系统中：AT+FTPGETTOFS

语法规则：

命令类型

语法

返回

设置命令

AT+FTPGETTOFS=,[,,]

OK

成功

ERROR

失败

查询命令

AT+FTPGETTOFS?

+FTPGETTOFS: [,,] OK

URC上报

+FTPGETTOFS:0,

如果下载成功

+FTPGETTOFS:

如果下载失败

测试命令

AT+FTPGETTOFS=?

OK

注意事项

重连以后会断点续传 如果两次 下载都用同一个文件名， 上次下载的内容会被覆盖

参数定义：

参数

定义

取值

对取值的说明

工作模式

0

不在FTPGETTOFS过程

1

处于FTPGETTOFS过程

文件保存的位置， 是ROM还是SD卡。Disk1或 Disk2可被AT+FSDRIVE获取

0

保存于ROM，文件夹 为“Disk1::raw-latex:`\ user`:raw-latex:`\ftp`”

1

保存于SD卡，文件夹为“D isk2::raw-latex:`\ftp`”

文件名

字符串型，最长64个字符

自动重连次数

0-255

缺省值：3

等多少秒开始自动重连

0-60

单位：秒，缺省值：5

当前 从FTP服务器GET多少数据

当前 保存到文件系统多少数据

总共 保存到文件系统多少数据

错误码

与 AT+FTPGET命令的定义相同

2.21 从文件系统上传文件到服务器：AT+FTPPUTFRMFS

语法规则：

命令类型

语法

返回

执行命令

AT+FTPPUTFRMFS=[,,]

OK

查询命令

AT+FTPPUTFRMFS?

+FTPPUTFRMFS: [,] OK

测试命令

AT+FTPPUTFRMFS=?

OK

URC上报

+FTPPUTFRMFS:0,

当上传结束，有此上报

+FTPPUTFRMFS:

当上传出错，有此上报。 定义 请参考AT+FTPGET命令的定义

注意事项

自动重连后从断点开始续传

参数定义：

参数

定义

取值

对取值的说明

文件名

字符串型，由数字 和字母组成，最长128字节

自动重连次数

0-255

缺省值：3

等多少秒开始自动重连

0-60

单位：秒，缺省值：5

FTP上传状态

0

不在上传状态

1

处于上传状态

当前从 文件系统上传了多少数据

单位：字节

从文 件系统共上传了多少数据

单位：字节

2.22 从文件系统加载到RAM中并用FTPPUT上传：AT+FTPFILEPUT

语法规则：

命令类型

语法

返回

设置命令

AT+FTPFILEPUT=[,]

OK

测试命令

AT+FTPFILEPUT=?

OK

注意事项

当FTPEXTPUT命令=1时，本命令不可用

2.23 获取远程服务器上文件目录：AT+FTPLIST

语法规则：

命 | 语法 令 | 类 | 型 |

返回

执 | AT+FTPLIST=[,] 行 | 命 | 令 |

如果=1，则命令格式为： AT+FTPLIST=1 返回值为： OK或 +CME ERROR:

如果=2，则命令格式为： AT+FTPLIST=2, 返回值为： +FTPLIST：2, ….数据… OK

测 | AT+FTPLIST=? 试 | 命 | 令 |

OK

U | 输入AT+FTPLIST=1后， R | 如果是一个成功的FT C | P会话，后续会有如下的URC上报： 上 | +FTPLIST:1,1 报 | 如果是FTP数据传输

结束，后续会有如下的URC上报：
+FTPLIST:1,0
如果FTP会话
失败，后续会有如下的URC上报：
+FTPLIST:1,

参数定义：

参数

定义

取值

对取值的说明

工作模式

1

打开FTP 获取文件目录会话

2

读取FTP 获取文件目录的数据

请求的数据的长度

1~1460

实际的数据长度

1~1460

同+FTPGET中定义

2.24 获取远程服务器上文件大小：AT+FTPSIZE

语法规则：

命令类型

语法

返回

说明

执行命令

AT+FTPSIZE

OK +FTPSIZE: 1,0,

获取文件大小成功

OK +FTPSIZE: 1,,0

获取文件大小失败

+CME ERROR:

如果是命令错误

测试命令

AT+FTPSIZE=?

OK

注意事项

文件由命令 AT+FTPGETNAME和A T+FTPGETPATH指定

参数定义：

参数

定义

取值

对取值的说明

文件大小

单位：字节

错误码

与AT+FTPGET命令的定义相同

2.25 获取FTP状态：AT+FTPSTATE

语法规则：

命令类型

语法

返回

执行命令

AT+FTPSTATE

+FTPSTATE: OK

测试命令

AT+FTPSTATE=?

OK

参数定义：

参数

定义

取值

对取值的说明

工作状态

0

Idle

1

FTP会话进行中，包括FTPGET、FTPPUT、FTPDELE

2.26 保存FTP应用上下文：AT+FTPSCONT

语法规则：

命 | 语 令 | 法 类 | 型 |

返回

说明

查 | AT+ | +FTPSCONT: +FTPSERV: | 询 | FTP | +FTPPORT: +FTPUN: +FTPPW: | 命 | SCO | +FTPCID: +FTPMODE: +FTPTYPE: | 令 | NT? | +FTPPUTOPT: +FTPREST: |

| +FTPGETNAME: +FTPGETPATH: |
| +FTPPUTNAME: +FTPPUTPATH: |
| +FTPTIMEOUT: OK |

执 | AT | OK 行 | +FT | 命 | PSC | 令 | ONT |

将FTP 上下文保存，等模块重启后， 将自动载入上下文参数并生效

2.27 删除服务器上指定的文件：AT+FTPDELE

语法规则：

命令类型

语法

返回

执行命令

AT+FTPDELE

OK

测试命令

AT+FTPDELE=?

OK

URC上报

+FTPDELE:1,0

表示删除成功。 第一个参数1表示FTP会话打开

+FTPDELE:1,

表示FTP文件删除失败。 错误码定义请参考AT+FTPGET 错误码定义

注意事项

文件由命令AT+FTP GETNAME和AT+FTPGETPATH指定

2.28 退出当前FTP会话：AT+FTPQUIT

语法规则：

命令类型

语法

返回

说明

设置命令

AT+FTPQUIT

OK

成功

ERROR

失败

测试命令

AT+FTPQUIT=?

OK

4 相关资料以及购买链接

《AT指令手册》

相关开发板购买链接 Air724UG开发板 Air724 开发板使用说明

5 常见问题

服务器搭建教程

可参考

https://luatdoc.papapoi.com/470/