LuatOS赋能Air780EPM：FTP通信开发教程正式上线！

随着物联网应用深入，远程文件传输需求日益增长。本教程聚焦LuatOS在Air780EPM平台上的FTP功能实现，提供详尽的代码示例与调试指导。

一、什么是 FTP

1.1 基本概念

FTP 协议

在 4G 物联网场景中，FTP 协议（File Transfer Protocol，文件传输协议）是一种基于 TCP/IP 的标准化文件传输技术。

FTP 协议包括两个组成部分，其一为 FTP 服务器，其二为 FTP 客户端.

FTP 服务器

FTP 服务器（File Transfer Protocol Server）是基于 FTP 协议提供文件存储、传输与管理服务的系统。简单来说，支持 FTP 协议的服务器就是 FTP 服务器， 用来存储文件，用户可以使用 FTP 客户端通过 FTP 协议访问位于 FTP 服务器上的资源.

FTP 客户端

FTP 客户端（FTP Client）是指用户端用于连接 FTP 服务器、并进行文件传输及管理操作的工具或软件。它是 FTP 通信中的 “发起方”，负责向 FTP 服务器发送连接请求、认证信息（如用户名和密码），并执行上传、下载、删除、移动文件等操作。

默认情况下 FTP 协议使用 TCP 端口中的 20 和 21 这两个端口，其中 20 用于传输数据，21 用于传输控制信息.但是，是否使用 20 作为传输数据的端口与 FTP 使用的传输模式有关：

如果采用主动模式，那么数据传输端口就是 20；

如果采用被动模式，要服务器端和客户端协商决定最终使用哪个端口.

FTP 作为成熟的文件传输协议，在 4G 物联网场景中承担 “标准化文件交互通道” 的角色，弥补了物联网中轻量级协议（如 MQTT）在大文件传输上的不足。

1.2 关键特性

基于 TCP 的可靠性：FTP 依赖 TCP 协议实现连接，通过三次握手建立连接、重传机制保障数据完整性，适合物联网中 “固件包”“监控录像” 等关键文件的传输，避免丢失或损坏。

双向文件操作：支持 “上传”（设备 → 服务器，如传感器日志上传）和 “下载”（服务器 → 设备，如固件更新），满足物联网设备与云端的双向数据交互需求。

适配 4G 网络特性：4G 的高带宽支持 FTP 传输较大文件；低延迟特性减少了 FTP 控制连接（端口 21）和数据连接（端口 20）的交互等待时间，提升传输效率。

1.3 典型应用场景

设备固件升级：物联网设备（如工业网关、智能摄像头）通过 4G 网络连接 FTP 服务器，下载最新固件包并完成升级，无需现场操作。

批量数据回传：部署在户外的传感器（如环境监测设备）定期将采集的日志文件（如温度、湿度历史数据）通过 FTP 上传至云端服务器，便于集中分析。

多媒体文件传输：车载终端、安防摄像头等设备通过 4G 网络将拍摄的视频、图片文件经 FTP 传输至后端平台，实现远程监控。

综上，4G 物联网中的 FTP 是一种依托 4G 高带宽、低延迟特性，实现设备与云端大文件可靠传输的成熟方案，广泛应用于固件升级、数据回传、多媒体传输等场景。

关于 FTP 更详细的理论知识说明，请参考:https://blog.csdn.net/HinsCoder/article/details/130911658

或者其他途径自行参考。

下面就跟着教程用模组实际操作演示一下 FTP 协议的实际应用。

二、功能演示概述

本文演示 4G 模组使用 LuatOS 开发时， 4G 通信中 ftp 网络协议的应用功能.

使用 Air780EPM 开发板下载 Air780EPM 的 LuatOS 示例代码中 ftp 的例程，进行验证,例程中实现的功能核心业务逻辑为：

配置 FTP 客户端登录服务器的参数和文件路径

封装一个重试机制，在登录失败、上传文件失败或者下载文件失败时尝试重新执行操作

登录 FTP 服务器，通过重试机制确保登录成功

ftp.push 上传本地文件到服务器，在本地新建文件并写入内容后上传到服务器指定路径，通过重试机制确保上传成功

ftp.pull 从服务器下载文件，保存在本地指定路径，并读取文件长度，当长度小于指定字节时，读取文件内容，通常是设定 512 字节，如果文件太大，会消耗 ram,通过重试机制确保上传成功

主函数循环运行以下流程： 登录服务器、用 ftp.command 操作 ftp 服务器目录以及文件上传下载处理后关闭服务器。

三、准备硬件环境

3.1 780EPM 硬件环境

1、Air780EPM 1.3 版本开发板一块 + 可上网的 sim 卡一张 +4g 天线一根 + 网线一根：

2、sim 卡插入开发板的 sim 卡槽

3、天线装到开发板上

4、网线一端插入开发板网口，另外一端连接可以上外网的路由器网口

5、TYPE-C USB 数据线一根 + USB 转串口数据线一根，Air780EPM 开发板和数据线的硬件接线方式为：

6、Air780EPM 开发板通过 TYPE-C USB 口供电；（外部供电/USB 供电 拨动开关 拨到 USB 供电一端）

7、TYPE-C USB 数据线直接插到开发板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

3.2 780EHM 硬件环境

1、Air780EHM 核心板一块 + 可上网的 sim 卡一张 +4g 天线一根 + 网线一根

2、sim 卡插入开发板的 sim 卡槽

3、天线装到开发板上

4、网线一端插入开发板网口，另外一端连接可以上外网的路由器网口

5、TYPE-C USB 数据线一根 + USB 转串口数据线一根，Air780EHM 核心板和数据线的硬件接线方式为：

6、Air780EHM 核心板通过 TYPE-C USB 口供电；（外部供电/USB 供电 拨动开关 拨到 USB 供电一端）

7、TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

8、USB 转串口数据线，一般来说，白线连接开发板的 UART1_TX，绿线连接开发板的 UART1_RX，黑线连接核心板的 GND，另外一端连接电脑 USB 口；

9、可选 AirPHY_1000 配件板一块，Air780EHM 核心板和 AirPHY_1000 配件板的硬件接线方式为:

四、准备软件环境

在开始实践本示例之前，先准备一下软件环境：

4.1 Luatools 工具，如果是第一次使用 Luatools 工具，请仔细阅读此链接教程。

4.2 内核固件文件（底层 core 固件文件）：LuatOS-SoC_V2014_Air780EPM_1.soc；参考项目使用的内核固件；如有更新可以使用最新固件。

4.3 luatos 需要的脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/ftp

main.lua：主程序入口；

netdrv_device.lua：网卡驱动设备，可以配置使用netdrv文件夹内的四种网卡(单4g网卡，单wifi网卡，单spi以太网卡，多网卡)中的任何一种网卡；

netdrv 文件夹：三种网卡，单 4g 网卡、单 spi 以太网卡、多网卡，供 netdrv_device.lua 加载配置,按需选择。

ftp_up_download.lua,功能演示核心脚本，在 main.lua 中加载运行。

**4.4 **lib 脚本文件：使用 Luatools 烧录时，勾选 添加默认 lib 选项，使用默认 lib 脚本文件；

准备好软件环境之后，接下来查看如何烧录项目文件到 Air780EPM 开发板，将本篇文章中演示使用的项目文件烧录到 Air780EPM 开发板中。

**4.5 **访问 ftp 服务器

以下准备了三种访问 ftp 服务器的方法

本文使用方法 1，通过 Windows 资源管理器访问，若无法访问，请尝试方法 2 或者方法 3:

测试服务器客户端配置参数，非 ssl 加密： local server_ip = "121.43.224.154" -- 服务器 IP local server_port = 21 -- 服务器端口号 local server_username = "ftp_user" -- 服务器登陆用户名 local server_password = "3QujbiMG" -- 服务器登陆密码

方法 1 Windows 资源管理器: - 打开“我的电脑”，在地址栏输入“ftp://121.43.224.154/”，按回车键。

在登录界面输入用户名和密码，点击登录，即可看到服务器上保存的文件。

方法 2 IE 浏览器访问: - 打开 IE 浏览器，在浏览器输入 121.43.224.154，回车，然后输入用户名和密码，点击登录，进入服务器。

方法 3 客户端软件：下载安装 Xftp 客户端软件，并配置好 ftp 服务器地址，端口号，用户名，密码等信息，即可登录，安装教程可自行上网查找。

注意选择 FTP 协议，如果新建会话后无法打开会话，可以再次检查登录信息是否正确。

五、API 接口说明

ftp-API 地址：https://docs.openluat.com/osapi/core/ftp/

六、示例代码和功能展示

6.1 流程介绍

1、搭建好硬件环境

2、demo 脚本代码 netdrv_device.lua 中，按照自己的网卡需求启用对应的 Lua 文件

3、如果需要单 4G 网卡，打开 require "netdrv_4g"，其余注释掉

4、如果需要以太网卡，打开 require "netdrv_eth_spi"，其余注释掉

5、如果需要多网卡，打开 require "netdrv_multiple"，其余注释掉

6、本示例使用的服务器参考第四章节 5. 访问 ftp 服务器，如果是自己的 ftp 服务器，在脚本代码 ftp_up_download.lua 的 config 表中按自己的服务器 IP，端口号，用户名，密码修改参数。

7、Luatools 烧录内核固件和修改后的 demo 脚本代码

8、烧录成功后，自动开机运行，查看打印日志，如果正常运行，会打印 ftp 登录成功，文件目录，上传下载文件结果等信息。

6.2 代码和 log

6.2.1 代码示例

（复制链接查看 ftp 的完整 demo）https://gitee.com/openLuat/LuatOS/blob/master/module/Air780EPM/demo/ftp/main.lua

6.2.2 核心代码部分

6.2.3 例程 log 打印如下：

6.2.4 luatools 页面显示如下：

6.2.5 ftp 服务器查看上传的文件

七、总结

本文档主要介绍 4G 通信中 FTP 通信的应用。

结合 demo 例程讲解了 FTP 基本原理，介绍了 FTP 主要 API,旨在最简单的快速上手 Air8000 的 LuatOS 的 FTP 开发.

八、常见问题

8.1 关于不支持主动模式：

模块 ftp 默认是被动模式，不支持主动模式，无法设置主动模式，公网下要想模块正常连接服务器，服务器肯定不能设置为主动模式，否则哪家模块都不能用.

8.2 ftp 服务器用 vsftpd

vsftpd 是一个 FTP 服务器软件， 是一个 UNIX 类操作系统上运行的服务器的名字，vsftpd 是 very secure FTP daemon 的缩写，安全性是它的一个最大的特点，它可以运行在诸如 Linux、BSD、Solaris、 HP-UNIX 等系统上面，是一个完全免费的、开放源代码的 ftp 服务器软件，负责搭建和提供文件存储、访问服务（相当于 “文件仓库”）,通过监听网络端口（默认 21 端口）接收客户端的连接请求，并根据配置允许用户上传、下载文件。

今天的内容就分享到这里了~