什么是 LuatOS "固件"？
在 LuatOS 生态中，固件（firmware） 就是烧录到模组芯片中、让硬件"跑起来"的那一套底层软件。
固件好比是手机的出厂操作系统（比如 iOS 或 Android）。手机硬件出厂时就已经装好了系统，你拿到手机后只需要安装 App（Lua 脚本）就可以使用了。
在 LuatOS 里，固件 = 操作系统，你的 Lua 脚本 = App。
固件的文件命名规则
固件文件以 .soc 为后缀，命名格式如下：
LuatOS-SoC_<版本号>_<模组型号>_<编号>.soc举例说明：
| 固件文件名 | 含义 |
|---|---|
LuatOS-SoC_V2018_Air780EPM_104.soc |
V2018 版本、Air780EPM 模组、104号 固件 |
LuatOS-SoC_V2016_Air8101_104.soc |
V2016 版本、Air8101 模组、104号 固件 |
LuatOS-SoC_V2008_Air8000_1.soc |
V2008 版本、Air8000 模组、1号 固件 |
固件里包含什么？
一个 LuatOS 固件由 5 层组成：
┌──────────────────────────┐
│ Lua 标准库 │ ← 字符串、表、数学运算等原生 Lua 功能
│ LuatOS 核心库 │ ← mqtt、http、gpio、uart、lcd 等硬件驱动库
│ Lua 虚拟机 (Lua VM) │ ← 执行 Lua 脚本的运行环境
│ LuatOS 适配层 │ ← 适配不同芯片的桥梁
│ 主芯片系统平台 (FreeRTOS) │ ← 底层的实时操作系统（未开源）
└──────────────────────────┘其中，用户二次开发最关心的是上两层 ------ Lua 标准库 + LuatOS 核心库（gpio、uart、mqtt、lcd 等）。
为什么同一模组有不同编号的固件（如 1号、103号、104号）？
是因为不同编号的固件内置了不同的核心库组合，这是由模组的硬件资源（Flash/RAM 大小）决定的。
以 Air780EPM 为例，104号固件相比 1号固件：
- ✅ 多了：libgnss（定位）、little_flash（SPI Flash）、otp（安全存储）、fft（傅里叶变换）
- ❌ 少了：camera（摄像头）、lcd（显示屏）、eink（墨水屏）、tp（触摸）、u8g2
- 脚本区大小：368KB（104号） vs 256KB（1号）
104 属于 64位固件 （101-199号），1号属于 32位固件（1-99号）。
固件和用户脚本的关系
┌──────────────┐ 烧录 ┌──────────────────┐
│ 固件(.soc) │ ─────────→ │ 模组芯片 │
│ (操作系统) │ │ (手机硬件) │
└──────────────┘ └──────────────────┘
↑
┌──────────────┐ ┌────┴──────┐
│ Lua 脚本 │ ───────────→ │ 运行你的 │
│ (你的 App) │ 下载到 │ 业务逻辑 │
│ main.lua │ 文件系统 └───────────┘
└──────────────┘工作流程：
- 先给模组烧录一个固件（相当于装好操作系统）
- 再通过 Luatools 工具把你的 Lua 脚本下载到模组的文件系统中
- 上电后，固件中的 Lua 虚拟机就会执行你的 Lua 脚本
LuatOS 固件 = "为特定模组定制的、内置了硬件驱动和 Lua 运行环境的嵌入式操作系统镜像文件"，用户只需编写 Lua 脚本作为"应用程序"在其上运行，无需关心底层芯片细节。
Air8101固件的含义
1.基本信息
- 固件版本 ：
V2018（LuatOS-SoC_V2018_Air8101） - 固件下载 ：LuatOS-SoC_V2018_Air8101
- Demo 源码 ：LuatOS-Air8101
- 发布日期 ：2026.07.07
2.104号固件支持的核心功能
| 功能 | 支持情况 |
|---|---|
| airUI 人机交互界面 | ✅ |
| camera（USB/DVP 摄像头拍照+大图解码） | ✅ |
| BLE 蓝牙 | ✅ |
| airlink 设备间通讯 | ✅ |
| audio 音频 | ✅ |
| hzfont 字库 | ✅ |
| TF 卡（fatfs） | ✅ |
| videoplayer 视频播放 | ✅（V2014起支持） |
| lcd JPG 解码 | ✅（V2018起支持） |
| 加密库（crypto/gmssl） | ✅ |
| 触摸屏（tp） | ✅ |
| FOTA 固件升级 | ✅ |
总而言之，Air8101 的 V2018 版本 104号固件 是一个以 UI（AirUI）操作功能为核心的固件版本，同时集成了摄像头拍照、蓝牙、音频、TF卡存储等功能，适用于需要图形界面交互场景的开发。
3.常见固件对比
| 对比项 | LuatOS-SoC_V2016_Air8101_104 | LuatOS-SoC_V2018_Air780EPM_104 |
|---|---|---|
| 目标模组 | Air8101（WiFi 模组，主打 UI 显示） | Air780EPM（4G Cat.1 蜂窝模组，主打 IoT 通信） |
| 固件版本 | V2016 | V2018（较新） |
| 架构 | 64位固件（101-199号） | 64位固件（101-199号） |
| 脚本区 | 512KB | 368KB |
| 文件系统 | 1752KB | 168KB |
| 运行内存(RAM) | 1.5MB（用户可用 Lua 内存约 2MB） | 较小（未明确标注，但远小于 Air8101） |
核心功能定位差异
Air8101 的 104 号固件 → 以 UI 图形界面开发为核心
- ✅ airUI --- 基于 LVGL 9.4 的图形化开发核心库（104号首次新增！）
- ✅ camera --- USB/DVP 摄像头拍照+大图片解码
- ✅ lcd --- 显示屏驱动
- ✅ tp --- 触摸屏
- ✅ hzfont --- 矢量字库
- ✅ audio --- 音频多媒体
- ✅ SIP 通话
- ✅ wlan --- WiFi 网络
- ✅ ble --- 蓝牙
- ✅ videoplayer --- 视频播放（V2014 起支持）
- ❌ 不支持 fft、protobuf、xxtea、iconv、u8g2
Air780EPM 的 104 号固件 → 以 4G 蜂窝通信和物联网为核心
- ✅ mobile --- 蜂窝通信（4G Cat.1）
- ✅ libgnss --- GNSS 定位
- ✅ otp --- 一次性可编程存储
- ✅ little_flash --- SPI Flash 驱动
- ✅ fft --- 快速傅里叶变换
- ✅ 标准 IoT 通信库：mqtt、http、socket、ftp、websocket
- ✅ 标准外设：uart、spi、i2c、gpio、pwm、adc、can
- ❌ 不支持 camera、lcd、tp、u8g2、eink、audio、SIP、ble、wlan、airUI
| 固件 | 用途 |
|---|---|
| V2016_Air8101_104 | 适合带屏幕的 UI 交互设备（如智能面板、HMI 人机界面），有摄像头、触摸屏、WiFi、蓝牙、音频、矢量字库等全套多媒体/显示能力 |
| V2018_Air780EPM_104 | 适合4G 物联网数据采集与通信设备（如远程监测、定位追踪），有 4G 联网、GNSS 定位、OTP 安全存储，但基本无 UI 显示能力 |
简单说：Air8101 的 104 号是"显示+交互"型 ，Air780EPM 的 104 号是"通信+数据"型，两者面向完全不同的应用场景。
项目管理
一个完整的 LuatOS 项目 = 内核固件 + 脚本和资源文件
Luatools 项目管理界面的配置分为两大块：
┌─────────────────────────────────────────────┐
│ ① 内核固件（底层CORE） ← 选择 .soc 文件 │
│ │
│ ② 脚本和资源列表（Script） ← 本问题的重点 │
│ ├── 用户脚本文件（必须） │
│ ├── 资源文件（可选） │
│ └── lib脚本文件（可选） │
│ │
│ ③ ☑ 添加默认lib（推荐勾选） │
└─────────────────────────────────────────────┘具体需要导入的文件
1️⃣ 用户脚本文件（必须）
你自己编写的 .lua 文件，核心通常是 main.lua （程序入口），以及其他自定义的 .lua 模块文件。
| 文件 | 说明 |
|---|---|
main.lua |
必备入口文件，LuatOS 启动后最先执行此文件 |
xxx.lua |
你的业务逻辑模块，通过 require("xxx") 引用 |
💡 可以从合宙官方 Demo 仓库下载：LuatOS: Powerful embedded Lua Engine for loT devices, withmany components - Gitee.com
2️⃣ 资源文件（可选）
除了 .lua 脚本之外的所有其他文件，例如：
| 文件类型 | 示例 |
|---|---|
| 图片 | logo.png、icon.jpg |
| 音频 | alarm.mp3、ring.wav |
| 文本 | config.txt、readme.md |
| 其他 | 字体文件、证书文件等 |
这些文件会被下载到模组的文件系统中，供脚本运行时读取。
3️⃣ lib 脚本文件（可选，推荐用默认）
有两种方式处理 lib 脚本：
| 方式 | 操作 |
|---|---|
| ✅ 推荐：勾选"添加默认lib" | Luatools 自动匹配与当前固件对应的官方 lib 库，省心省力 |
| 手动指定 | 点击"添加文件"选择你自己准备的 lib 脚本文件 |
建议始终勾选"添加默认lib"，除非你有特殊的定制 lib 需求。
操作步骤总结
1. 创建项目
2. 选择底层固件（.soc 文件） ← 内核固件
3. 点击"脚本和资源列表"的添加按钮
├── 添加 main.lua ← 用户脚本（必须）
├── 添加 其他 .lua 文件 ← 用户脚本（可选）
└── 添加 图片/音频等资源文件 ← 资源文件（可选）
4. 勾选 ☑ "添加默认lib" ← 自动使用官方 lib
5. 点击 "下载底层和脚本" 或 "下载脚本"
底层Core：Lua开发的底层Core
增加脚本或资源文件：添加用户脚本、数据及Lib库
默认USB打印trace，trace三个选项是用来选择打印输出方式的
添加默认lib：不建议勾选
升级文件包含core：用于项目打包，可按需选择
升级文件包含脚本：用于项目打包，建议直接勾选
升级文件无资源文件：用于项目打包，不选
USB BOOT下载：使用Boot模式下载
下载脚本：只下载脚本列表中的数据
下载底层和脚本：底层core和脚本列表中的数据都下载
语法检查：单独检查用户编写的脚本有无语法错误
(注意:首次下载时，强烈建议直接下载底层和脚本)
常见问题
1.提示缺少库文件
点击确认后，会提示缺少的具体脚本文件
