16 exremotefile-远程文件管理系统

作者：拓毅恒　|　最后修改：2026-04-28

一、概述

如下图所示，exremotefile 扩展库是 LuatOS 提供的一个远程文件管理系统，它通过创建 Wi-Fi AP 热点和 SERVER 服务器，允许用户在移动设备或电脑上通过浏览器远程管理设备上的文件。

你可以把它想象成一个简易的文件服务器：

创建 AP 热点：设备会创建一个 Wi-Fi 热点，供其他设备连接。
挂载 SD 卡：自动挂载 Flash 中内置文件系统和设备上的 TF/SD 卡，以便访问设备内部存储和 SD 卡中的文件。
启动 SERVER 服务器：提供 Web 界面，用户可以通过浏览器查看、下载和删除文件。

该库适用于需要在本地浏览或下载主控内部文件的设备场景中。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库中各个产品目录下的 project/wifi_ap_read_file

远程文件管理系统

--[[
本核心示例的业务逻辑为：
1、创建并启动一个基础task，在task的任务处理函数内初始化远程文件管理系统；
2、用户可以通过连接设备创建的Wi-Fi热点，在浏览器中访问文件管理界面；
]]

PROJECT = "wifi_ap_read_file"
VERSION = "001.000.000"

-- 在日志中打印项目名和项目版本号
log.info("main", PROJECT, VERSION)

-- 导入exremotefile库
local exremotefile = require "exremotefile"

-- 启动远程文件管理系统（使用默认参数）
exremotefile.open()

-- 如果需要自定义参数，可以使用以下方式
-- exremotefile.open({
--     ap_ssid = "LuatOS_FileHub", -- WiFi名称
--     ap_pwd = "12345678"         -- WiFi密码
-- }, 
-- {
--     spi_id = 1,                 -- SPI编号
--     spi_cs = 20,                -- CS片选引脚
--     is_8000_development_board = false, -- 是否使用8000开发板
--     is_sdio = false             -- 是否使用sdio挂载
-- }, 
-- {
--     server_addr = "192.168.4.1",    -- 服务器地址
--     server_port = 80,           -- 服务器端口
--     user_name = "admin",        -- 用户名
--     user_pwd = "123456"          -- 密码
-- })

-- 运行一段时间后关闭远程文件管理系统
-- sys.timerStart(exremotefile.close, 3600000) -- 1小时后关闭

-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

三、常量详解

exremotefile 扩展库没有常量。

四、函数详解

4.1 exremotefile.open(ap_opts, sdcard_opts, server_opts)

功能

启动文件管理系统，包括创建 AP 热点、挂载 TF/SD 卡和启动 SERVER 文件管理服务器功能。

注意事项

1. 如果文件管理系统已经在运行中，再次调用此函数会返回警告信息，不会重复启动；

2. 启动过程中会先检查 AP 热点参数、SD 卡挂载参数和服务器参数，并使用默认值补充未提供的参数；

3. 系统会自动创建 AP 热点、挂载 SD 卡并启动 SERVER 服务器；

4. 启动完成后，可以通过日志中显示的 Wi-Fi 名称、密码和访问地址来连接和使用文件管理系统；

参数

ap_opts

参数含义：AP热点配置选项表；参数为table类型时，table内容格式说明如下：
{
参数含义：AP热点的名称；
数据类型：string或者nil；
取值范围：无特别限制；
是否必选：可选传入此参数，默认值为"LuatOS_FileHub"；
注意事项：无；
参数示例："MyDevice"；
参数名称： ap_opts.ap_ssid

参数含义：AP热点的密码；
数据类型：string或者nil；
取值范围：密码长度应至少为8个字符，可包含数字和字母；
是否必选：可选传入此参数，默认值为"12345678"；
注意事项：密码必须符合WiFi规范，长度至少8个字符；
参数示例："87654321"；
参数名称： ap_opts.ap_pwd
}

数据类型：table或者nil；
取值范围：参考参数含义内各字段说明；
是否必选：可选传入此参数；注意事项：无；
参数示例：自定义AP热点名称和密码；
{
ap_ssid = "MyDevice",
ap_pwd = "87654321" -- 符合8位密码规范
}

sdcard_opts

参数含义：TF/SD卡挂载配置选项表；参数为table类型时，table内容格式说明如下：
{
参数含义：SPI编号；
数据类型：number或者nil；
取值范围：根据设备支持的SPI数量确定；
是否必选：可选传入此参数，默认值为1；
注意事项：无；
参数示例：0；
参数名称： sdcard_opts.spi_id

参数含义：CS片选引脚；
数据类型：number或者nil；
取值范围：根据设备支持的GPIO引脚确定；
是否必选：可选传入此参数，默认值为20；
注意事项：无；
参数示例：12；
参数名称： sdcard_opts.spi_cs = ,

参数含义：是否使用8000开发板；
数据类型：boolean或者nil；
取值范围：true/false；
是否必选：可选传入此参数，默认值为false；
注意事项：在Air8000开发板上TF和以太网是同一个SPI，使用开发板时必须设置为true；
参数示例：true；
参数名称： sdcard_opts.is_8000_development_board

参数含义：是否使用8101设备；
数据类型：boolean或者nil；
取值范围：true/false；
是否必选：可选传入此参数，默认值为false；
注意事项：无；
参数示例：true；
参数名称： sdcard_opts.is_8101
}

数据类型：table或者nil；
取值范围：参考参数含义内各字段说明；
是否必选：可选传入此参数；
注意事项：无；
参数示例：自定义SD卡挂载参数；
{
spi_id = 0, -- 使用SPI0
spi_cs = 12 -- 使用引脚12作为片选
}

使用8000开发板的配置示例
{
is_8000_development_board = true
}

使用8101设备的配置示例
{
is_8101 = true
}

server_opts

参数含义：服务器配置选项表；参数为table类型时，table内容格式说明如下：
{
参数含义：服务器地址；
数据类型：string或者nil；
取值范围：有效的IP地址；
是否必选：可选传入此参数，默认值为"192.168.4.1"；
注意事项：支持自定义AP地址，需确保与子网掩码一致，并用该地址访问；
参数示例："192.168.4.1"；
参数名称： sdcard_opts.server_addr

参数含义：服务器端口；
数据类型：number或者nil；
取值范围：1-65535；
是否必选：可选传入此参数，默认值为80；
注意事项：无；
参数示例：8080；
参数名称： sdcard_opts.server_port

参数含义：用户名；
数据类型：string或者nil；
取值范围：无特别限制；
是否必选：可选传入此参数，默认值为"admin"；
注意事项：无；
参数示例："user"；
参数名称： sdcard_opts.user_name

参数含义：密码；
数据类型：string或者nil；
取值范围：无特别限制；
是否必选：可选传入此参数，默认值为"123456"；
注意事项：无；
参数示例："password"；
参数名称： sdcard_opts.user_pwd
}

数据类型：table或者nil；
取值范围：参考参数含义内各字段说明；
是否必选：可选传入此参数；
注意事项：无；
参数示例：自定义服务器参数；
{
server_port = 8080, -- 使用8080端口
user_name = "user", -- 自定义用户名
user_pwd = "password" -- 自定义密码
}

返回值

无

示例

-- 示例1：使用默认参数创建server服务器
-- 启动后连接默认AP热点，直接访问日志中默认的地址"http://192.168.4.1:80/explorer.html"来访问文件管理服务器。
exremotefile.open()

-- 示例2：自定义参数启动
-- 启动后连接自定义AP热点，访问日志中自定义的地址"http://"server_addr":"server_port"/explorer.html"来访问文件管理服务器。
-- 例如下面一段代码，对应的访问地址为：http://192.168.4.1:80/explorer.html
exremotefile.open({
    ap_ssid = "LuatOS_FileHub", -- WiFi名称
    ap_pwd = "12345678"         -- WiFi密码
}, 
{
    spi_id = 1,                 -- SPI编号
    spi_cs = 20,                -- CS片选引脚
    is_8000_development_board = false, -- 是否使用8000开发板
    is_8101 = false             -- 是否使用8101设备
}, 
{
    server_addr = "192.168.4.1",    -- 服务器地址
    server_port = 80,           -- 服务器端口
    user_name = "admin",        -- 用户名
    user_pwd = "123456"          -- 密码
})

-- 示例3：自定义参数启动（使用8000开发板）
-- 启动后连接默认AP热点，访问日志中的地址"http://192.168.4.1:80/explorer.html"来访问文件管理服务器。
exremotefile.open(nil, {is_8000_development_board = true})

-- 示例4：自定义参数启动（不挂载SD卡）
-- 启动后连接默认AP热点，仅管理设备内部文件，不挂载SD卡
-- 适用于客户自行管理SD卡的场景
exremotefile.open(nil, nil, {
    server_addr = "192.168.4.1",
    server_port = 80,
    user_name = "admin",
    user_pwd = "123456"
})

4.2 exremotefile.close()

功能

关闭文件管理系统，包括停止 SERVER 文件服务器、取消 TF/SD 卡挂载（仅在使用open挂载sd卡时才会卸载）和停止 AP 热点。

注意事项

1. 如果文件管理系统尚未启动，调用此函数会返回警告信息；

2. 关闭过程中会依次停止 SERVER 服务器、停止 AP 热点、取消挂载 SD 卡、关闭 SPI 和相关 GPIO；

3. 关闭完成后，将释放所有相关资源；

参数

无

返回值

无

示例

-- 关闭文件管理系统
exremotefile.close()

五、产品支持说明

Air8000/8000A/8000W 等 Air8000 系列和 Air8101 等具有 Wi-Fi 功能的产品都支持 exremotefile 库。

六、常见问题与解决方案

6.1 无法连接到 AP 热点

问题描述：启动文件管理系统后，移动设备无法搜索到或连接到 AP 热点。

解决方案：

检查设备的天线是否连接良好；
尝试重启设备并重试；
确认自定义的 AP 名称和密码是否符合 Wi-Fi 规范（例如，密码长度是否 ≥8 位）。

6.2 无法挂载 SD 卡

问题描述：文件管理系统启动后，无法访问 SD 卡中的文件。

解决方案：

确认 SD 卡已经正确插入设备；
检查 SD 卡是否格式化为 FAT32；
尝试使用已知正常的 SD 卡；
确认 SPI 参数是否配置正确，特别是片选引脚；
对于 Air8000 开发板，需要启用 is_8000_development_board 选项。

6.3 无法访问文件管理界面

问题描述：连接到 AP 热点后，无法在浏览器中访问文件管理界面。

解决方案：

确认 LuatOS/script/libs 扩展库目录下 explorer.html 文件是否烧录到设备中；
通过日志确认设备已经获取到正确的 IP 地址；
检查访问的 URL 是否正确；
确认服务器端口配置是否正确；
查看设备日志，确认 SERVER 服务器是否成功启动。

6.4 无法下载 SD 卡中文件

问题描述：文件管理系统启动后，下载 SD 卡内文件夹中的文件失败。

解决方案：

SD 卡目录下文件夹名称不能为中文，否则会识别失败，无法下载文件夹中文件；
确认文件夹命名是否符合规范，不能用特殊字符做开头结尾。