跳转至

luatos-cli 使用指南

luatos-cli 是合宙 LuatOS 的命令行工具集,覆盖刷机、日志查看、FOTA 升级包制作、固件资源管理、自动化测试等日常开发工作。它面向两类使用场景:

  • 人工操作:比图形工具更快捷,命令可复制、可记录,适合开发调试;
  • AI / 自动化:所有命令都支持 --format json|jsonl 结构化输出,方便脚本和 AI 助手调用。

支持 Air8101、Air6208、Air1601/1602/1603/1604、Air8000/780EPM、EC618/780E、Air724UG、Air8609W(D126) 等主流型号,详见文末「型号支持对照表」。

获取与安装

按推荐顺序,任选其一:

  1. LuaTools 资源下载(推荐):打开 LuaTools,使用资源下载功能获取最新版 luatos-cli;
  2. 备用下载地址:合宙资源站-LuatOS-CLI;
  3. GitHub Releases:github.com/wendal/luatos-cli/releases(含各平台预编译包与 C 共享库);
  4. 源码构建(需要 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 执行错误),直接判断即可。

搜索