luatos-cli 使用指南
luatos-cli 是合宙 LuatOS 的命令行工具集,覆盖刷机、日志查看、FOTA 升级包制作、固件资源管理、自动化测试等日常开发工作。它面向两类使用场景:
- 人工操作:比图形工具更快捷,命令可复制、可记录,适合开发调试;
- AI / 自动化:所有命令都支持
--format json|jsonl结构化输出,方便脚本和 AI 助手调用。
支持 Air8101、Air6208、Air1601/1602/1603/1604、Air8000/780EPM、EC618/780E、Air724UG、Air8609W(D126) 等主流型号,详见文末「型号支持对照表」。
获取与安装
按推荐顺序,任选其一:
- LuaTools 资源下载(推荐):打开 LuaTools,使用资源下载功能获取最新版 luatos-cli;
- 备用下载地址:合宙资源站-LuatOS-CLI;
- GitHub Releases:github.com/wendal/luatos-cli/releases(含各平台预编译包与 C 共享库);
- 源码构建(需要 Rust 环境):
cargo build --release -p luatos-cli
下载解压后即可直接运行,无需安装。Windows 下是 luatos-cli.exe,建议把所在目录加入 PATH,方便任意位置执行。
如果要使用 HZV 视频转换功能,请保留可执行文件旁边的
tools目录(内含随包 FFmpeg),运行时不需要另外安装 Python 或 FFmpeg。
安装完成后验证一下:
luatos-cli --version
luatos-cli guide models # 列出支持的型号和推荐命令
快速上手
以"给开发板刷入固件并查看运行日志"为例,完整走一遍:
# 1. 插好 USB 线,查看当前电脑上的串口
luatos-cli serial list
# 2. 查看固件包信息(确认是哪个型号的固件)
luatos-cli soc info firmware.soc
# 3. 刷入完整固件(把 COM10 换成上一步看到的端口)
luatos-cli flash run --soc firmware.soc --port COM10
# 4. 查看设备运行日志(按 Ctrl+C 退出)
luatos-cli log view --port COM10
如果不确定自己的型号该用哪条命令,先查型号帮助:
luatos-cli guide model --model air1601 # 把 air1601 换成你的型号
它会直接给出该型号推荐的刷机、日志、测试命令。
刷入完整固件
什么时候用:首次烧录、恢复出厂固件、底层固件升级。
luatos-cli flash run --soc firmware.soc --port COM10
--soc指定固件包(.soc文件);--port指定串口,填auto或省略则自动选择;- 固件里的底层 + 脚本会全部写入,脚本也可以现场替换(见下);
- 刷机完成后设备自动复位运行。
常用可选参数:
# 刷机时同时用自己的脚本目录覆盖固件内置脚本(可重复指定多个目录)
luatos-cli flash run --soc firmware.soc --port COM10 --script ./lua
# 刷完继续监听 30 秒启动日志,不丢开机过程
luatos-cli flash run --soc firmware.soc --port COM10 --tail-log-secs 30
# 刷机同时清空 FSKV(键值存储)分区
luatos-cli flash run --soc firmware.soc --port COM10 --clear-kv
不同芯片的注意事项:
- EC618 / Air780E / Air780EG:免 BOOT 模式失败时,先按住 BOOT 键再复位,然后重新运行命令;
- Air8000 / Air780EPM:支持自动重启进入 USB 下载模式,直接
--port auto即可; - Air6208 (XT804):全量刷机与脚本更新分两步(见下一节);
- Air8609W (D126):USB 烧录,按住 BOOT 上电进入升级模式,
--port可填auto或 USB 选择器(如1:2-4-2)。
只更新脚本(开发期最常用)
什么时候用:改了 Lua 代码想快速验证,底层固件不用动。
luatos-cli flash script --soc firmware.soc --port COM10 --script ./lua
--script指向 Lua 脚本目录,会自动编译并写入脚本分区;- 脚本偏大、超出脚本分区时,用
--luac-debug 0去掉调试信息缩小镜像(0=无、1=仅行号、2=仅变量名、99=全部,默认99); - Air6208/Air101/Air103(XT804)固件 + 脚本需要两步执行:
luatos-cli flash run --soc air6208.soc --port COM7
luatos-cli flash script --soc air6208.soc --port COM7 --script ./lua --luac-debug 0
- 也可以用
--bin直接下发已经编译好的脚本镜像。
脚本镜像在下载前会按容量校验,超限直接报错、不会写坏设备,请按提示用 --luac-debug 减小体积或精简脚本。
查看设备日志
什么时候用:调试运行中的设备、抓开机日志、分析异常。
# 文本日志(EC718 系列可 --port auto 自动识别 log 口)
luatos-cli log view --port auto --baud 921600
# 二进制日志(Air1601/1602/1603/1604、EC718 等,--probe 触发日志输出)
luatos-cli log view-binary --port COM10 --baud 6000000 --probe
# 边看边存原始日志(滚动文件)
luatos-cli log view-binary --port COM10 --probe --save ./logs
# 智能诊断:自动识别常见问题并给出建议
luatos-cli log view --port auto --smart
- 文本日志默认波特率 921600,二进制日志默认 2000000(Air1601 V1013+ 用 6000000);
- Air1601/1602/1603/1604、EC718 系列看二进制日志时必须加
--probe; - 也有
log record(录制到文件)和log parse(解析已保存的日志)两个辅助命令。
制作 FOTA 升级包
什么时候用:给已出厂设备推送远程升级包。
# 仅脚本热更新包(最常用,设备上底层不变)
luatos-cli fota build --new v2.soc --script-only -o update.sota
# 差分升级包(需要新旧两个固件包)
luatos-cli fota build --new v2.soc --old v1.soc -o update.sota
# 全量升级包(只给新固件,不给旧的)
luatos-cli fota build --new v2.soc -o update.sota
- 输出是
.sota升级包;EC7xx 差分时若底层固件与旧版相同,会自动回落成脚本更新包(可用--force-par强制走差分); - Air724UG(RDA8910)差分需要 dtools(自动发现,或用
--fota-toolkit指定路径); - 支持 EC7xx、CCM4211、BK72XX(Air8101)、RDA8910、D126(LFTA)等格式。
查看和修改固件包
什么时候用:了解固件包里有什么、替换内置脚本、重新打包。
luatos-cli soc info firmware.soc # 固件信息(芯片型号、分区、容量等)
luatos-cli soc files firmware.soc # 列出包内文件
luatos-cli soc unpack firmware.soc -o out_dir # 解包到目录
# 用新编译的脚本镜像替换包内脚本,生成新固件(自动识别芯片)
luatos-cli soc combine --soc base.soc --bin build/script.bin -o patched.soc
# D126 专用:合并 Lua 脚本目录进 .soc
luatos-cli soc inject-scripts --soc base.soc --script ./lua -o custom.soc
资源分区下载
什么时候用:单独更新字库、TTS、图片等资源,不动固件。
以 Air8101(带 rom.fs.res 描述的固件)为例:
luatos-cli flash flash-res --soc firmware.soc --port COM6 --resource ./resources
# 可重复指定目录,相同相对路径由后面的目录覆盖
luatos-cli flash flash-res --soc firmware.soc --port COM6 --resource ./base --resource ./overrides
资源目录按原相对路径打包成标准 romfs 写入资源分区,不编译 .lua、不改文件内容。约束:单级文件名 ≤ 64 字节,目录最深 4 层。
任意地址读写(低阶操作)
什么时候用:补刷分区表覆盖不到的区域(外置字库、fs 等)、备份 Flash 数据。不熟悉分区布局时请勿使用。
# 往任意地址写入(bootloader/core 区默认受保护,覆盖需 --force)
luatos-cli flash raw --soc firmware.soc --port COM10 \
--addr 0x200000 --file font.bin --erase --verify
# 读回任意区间到文件(Air8101 / D126)
luatos-cli flash dump --soc firmware.soc --port COM10 \
--addr 0x40d000 --len 0x1000 -o dump.bin
注意:
- NOR Flash 不能 0→1 写,通常要加
--erase; - 校验能力因芯片而异:Air8101 可读回逐字节比对,Air1601 用设备回读 MD5,Air6208(XT804) 不支持
--verify; - 读回(
flash dump)目前非 D126 仅 Air8101 支持;D126 按--partition scripts|data|fskv|...分区读回。
闭环测试与 testcase 调试
什么时候用:刷完机自动判定"开机是否正常",或快速跑一个 LuatOS testcase。
# 刷机 → 抓开机日志 → 关键字校验 → PASS/FAIL
luatos-cli flash test --soc firmware.soc --port COM10
luatos-cli flash test --soc firmware.soc --port COM10 \
--keyword "LuatOS@" --fail-keyword panic
- 不传
--keyword时默认检查LuatOS@;--fail-keyword可重复指定,命中任意一个立即判失败; - 失败时会列出缺失的关键字。
trun 把"合成脚本 → 刷机 → 抓日志 → 关键字校验"合成一条命令,适合在 LuatOS 仓库里单点验证 testcase:
luatos-cli trun list --luatos-root D:/github/LuatOS
luatos-cli trun exftp \
--luatos-root D:/github/LuatOS \
--soc base.soc --port COM6 \
--keyword "LuatOS@" --fail-keyword panic
退出码:0=通过,1=关键字缺失或命中失败关键字,3=端口占用等执行错误,方便 CI 集成。
HZV 视频转换
什么时候用:把普通视频转成 AirMaster / 设备播放用的 HZV 格式。
luatos-cli hzv probe input.mp4 # 看源视频参数
luatos-cli hzv convert input.mp4 -o output.hzv --width 480 --height 320 --fps 10
luatos-cli hzv verify output.hzv --deep # 校验生成结果
支持 MJPEG + MP3/PCM、分辨率/帧率调整、画面适配(等比补背景/裁剪/拉伸)。发布包自带 FFmpeg,保留可执行文件旁的 tools 目录即可。
其他工具
| 命令 | 用途 |
|---|---|
luatos-cli project wizard |
向导式创建 LuatOS 项目(选型号、版本、模板) |
luatos-cli project analyze |
项目全量分析:语法检查、依赖、空间占用 |
luatos-cli project import/export |
导入 LuaTools 工程 / 导出 .luatos 归档 |
luatos-cli build luac |
把 Lua 脚本编译为字节码 |
luatos-cli build filesystem |
构建脚本文件系统镜像 |
luatos-cli resource list / download |
从合宙 CDN 列出/下载固件资源 |
luatos-cli device reboot / boot |
重启设备 / 强制进入下载模式 |
luatos-cli doctor |
体检开发环境(串口、项目、固件、工具) |
实用功能
型号帮助入口
luatos-cli guide models # 所有型号及推荐命令
luatos-cli guide model --model air8000 # 指定型号的推荐命令
串口自动识别
刷机和日志命令的 --port 填 auto(或省略)时自动选择串口;同时插着多块板时会列出候选端口并停止,此时请用 serial list 查看后指定具体端口(如 COM12)。EC718 系列的日志口与下载口分离,log view --port auto 会自动识别 log 口。
结构化输出(AI / 脚本友好)
全局 --format text|json|jsonl,任意命令都适用:
luatos-cli --format json serial list
luatos-cli --format jsonl flash run --soc firmware.soc --port COM10 --tail-log-secs 30
JSON 输出为统一信封 { "status": "ok", "command": "...", "data": { ... } },方便程序判断结果。
型号支持对照表
| 模组 | 芯片 | 刷机 | 脚本区 | 文件系统 | FOTA | 日志 | 任意地址读写 | 闭环测试 |
|---|---|---|---|---|---|---|---|---|
| Air8101 | BK7258 | ✅ | ✅ | ✅ | ✅ | 文本 | ✅ | ✅ |
| Air6208 / Air101 / Air103 | XT804 | ✅ | ✅ | ✅(6208) | ✅ | 二进制 | 仅写 | ✅ |
| Air1601 / 1602 / 1603 / 1604 | CCM4211 | ✅ | ✅ | ✅ | ✅ | 二进制 | ✅(MD5 校验) | ✅ |
| Air8000 / Air780EPM / Air780EHx | EC718 | ✅ | ✅ | — | ✅ | 二进制 | — | ✅ |
| EC618 / Air780E / Air780EG | EC618 | ✅ | ✅ | — | ✅ | 二进制 | — | ✅ |
| Air724UG | RDA8910 | ✅ | ✅ | — | ✅ | 二进制 | — | — |
| Air8609W(D126) | D126 | ✅(USB) | ✅ | ✅ | ✅ | 文本 | 分区读回 | — |
各型号的详细命令与注意事项,以 luatos-cli guide model --model <型号> 的输出为准。
常见问题
同时插了多块板,怎么指定刷哪一块?
用 luatos-cli serial list 看清各端口对应关系,然后 --port 明确指定(如 COM12);自动模式遇到多板会列候选并停止,不会乱刷。
刷机报"脚本镜像超出脚本分区"怎么办?
加 --luac-debug 0 去掉调试信息,或精简脚本/依赖库。工具在下载前就会校验容量,报错不会影响设备。
EC618/Air780E 免 BOOT 刷机失败?
按住 BOOT 键再复位(或重新上电),保持按住的状态下运行 flash run --port auto。
Air6208 为什么刷完脚本没生效?
XT804 的固件与脚本是两阶段:先 flash run 刷固件,再 flash script --script ./lua 更新脚本。
二进制日志一片空白?
Air1601/1602/1603/1604 与 EC718 系列需要加 --probe 触发日志输出;另外注意日志口与下载口可能不是同一个,--port auto 可自动识别。
想脚本化/接入 CI?
所有命令支持 --format json|jsonl;flash test/trun 有明确退出码(0 通过 / 1 失败 / 3 执行错误),直接判断即可。