LuatOS扩展库API——【exremotefile】远程文件管理系统

上海合宙LuatOS2026-04-11 17:55

LuatOS，是一款面向物联网设备打造的轻量级嵌入式 Lua 脚本运行框架与实时系统，基于 Lua 5.3 深度优化，主要适用于 4G-Cat.1、MCU 这类 物联网终端。开发时采用 Lua 脚本模式，核心设计围绕协程多任务展开，同时其丰富的配套资源也为开发提供了便利，数十个核心库与扩展库，搭配上千个应用 demo，可满足物联网基础开发的各类需求。

一、概述

如下图所示，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

远程文件管理系统

lua 复制代码 
--[[
本核心示例的业务逻辑为：
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

lua 复制代码 
> 参数含义：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 = ,
> 
> 参数含义：是否使用sdio挂载；  
> 数据类型：boolean或者nil；  
> 取值范围：true/false；  
> 是否必选：可选传入此参数，默认值为false；  
> 注意事项：无；  
> 参数示例：false；  
> 参数名称： sdcard\_opts.is\_sdio  
> }
> 
> 数据类型：table或者nil；  
> 取值范围：参考参数含义内各字段说明；  
> 是否必选：可选传入此参数；  
> 注意事项：无；  
> 参数示例：自定义SD卡挂载参数；  
> {  
> spi\_id = 0, -- 使用SPI0  
> spi\_cs = 12 -- 使用引脚12作为片选  
> }
> 
> 使用8000开发板的配置示例  
> {  
> is\_8000\_development\_board = true  
> }

server_opts

lua 复制代码 
> 参数含义：服务器配置选项表；参数为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" -- 自定义密码  
> }

返回值

无

示例

lua 复制代码 
-- 示例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_sdio = false             -- 是否使用sdio挂载
}, 
{
    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.2 exremotefile.close()

功能

关闭文件管理系统，包括停止 SERVER 文件服务器、取消 TF/SD 卡挂载和停止 AP 热点。

注意事项

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

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

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

参数

无

返回值

无

示例

lua 复制代码 
-- 关闭文件管理系统
exremotefile.close()

五、常见问题与解决方案

5.1 无法连接到 AP 热点

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

解决方案：

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

5.2 无法挂载 SD 卡

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

解决方案：

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

5.3 无法访问文件管理界面

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

解决方案：

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

5.4 无法下载 SD 卡中文件

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

解决方案：

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

六、模组支持说明

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

相关推荐
dexie_tech2 小时前
不惧高频挑战，电流传感器带宽升级
功能测试·科技·物联网·测试工具·能源
思为无线NiceRF3 小时前
高空线路安装智能安全帽全双工组网对讲系统（含优先级管控）应用方案
嵌入式硬件·物联网
上海合宙LuatOS4 小时前
LuatOS扩展库API——【exremotecam】网络摄像头控制
开发语言·网络·物联网·lua·luatos
国产化创客5 小时前
ESP32 (ESPectre)+Grafana构建专业级CSI监控面板
物联网·grafana·信息与通信·智能硬件
Vis-Lin6 小时前
BLE 协议栈：L2CAP 信道详解
网络·物联网·网络协议·蓝牙·iot·ble
无忧智库7 小时前
某新区“十五五”智慧城市数字底座与数字孪生城市建设全栈技术深度解析（WORD）
人工智能·物联网·智慧城市
北京耐用通信7 小时前
CC-Link IE转Modbus TCP集成实战：耐达讯自动化网关在五星级酒店节能改造中的应用
人工智能·物联网·网络协议·自动化·信息与通信
三佛科技-134163842127 小时前
无线遥控器开关方案开发 ,无线遥控器开关MCU控制方案设计-基于国产单片机
单片机·嵌入式硬件·物联网·智能家居·pcb工艺
热门推荐
01GitHub 镜像站点02一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛03OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程04AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南05【STM32】HAL库 CubeMX 教程 --- 通用定时器 TIM2 定时06VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）07Oh My Codex 快速使用指南08实测！Gemma 4 成功跑在安卓手机上：离线 AI 助手终于来了09CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南10UV安装并设置国内源