luatos-cli

LuatOS 命令行工具集（纯 Rust）——刷机、日志、项目管理、固件资源与构建。

功能特性

• 多芯片刷机：Air8101(BK7258)、Air6208(XT804)、Air1601/Air1602(CCM4211)、Air8000(EC718)、SF32LB58
• FOTA 打包：支持 EC7xx 差分/脚本、CCM4211 全量/脚本、Air8101(BK72XX) 新格式全量/脚本；EC7xx 差分时若底层固件相同自动回落到脚本更新包（--force-par 可强制走差分）
• 二级帮助入口：--help 提示型号入口，guide models / guide model --model <型号> 直接给推荐命令
• 刷机后继续监听：flash run --tail-log-secs <N> 刷机后自动按型号波特率续接日志，减少开机日志丢失
• 日志系统：文本 / 二进制日志查看、录制、解析，支持智能诊断
• 项目与构建：项目向导、配置管理、Lua 依赖分析、luac/LuaDB 构建
• AI 友好输出：全局 --format text|json|jsonl

安装

cargo build --release -p luatos-cli

C 共享库 (luatos-log-ffi)

SOC 日志解码同样以 C ABI 形式发布, 方便 Python (ctypes)、C/C++、Go (cgo)、C# (P/Invoke) 等语言直接消费. 与第三方 pySoclogAnalyze DLL 签名完全兼容 (含日志帧/命令帧双模式), 现有用户可无感替换 DLL.

# C 示例
gcc -O2 -std=c99 -I crates/luatos-log-ffi/include \
    crates/luatos-log-ffi/examples/c/demo.c \
    -L target/release -lluatos_log_ffi -o demo
LD_LIBRARY_PATH=target/release ./demo

# Python ctypes
python3 crates/luatos-log-ffi/examples/python/demo_ctypes.py

从 GitHub Releases 下载预编译的 luatos-log-ffi-<target>.{zip,tar.gz} 包 (含 .dll/.so/.dylib + 头文件 + 示例), 4 个目标平台 (windows-msvc / linux-gnu / darwin x64+arm64) 全覆盖.

详见 docs/luatos-log-c-abi.md.

快速开始

# 查看型号二级帮助
luatos-cli guide models
luatos-cli guide model --model air1601

# 常规刷机
luatos-cli flash run --soc firmware.soc --port COM10

# 刷机后继续监听启动日志（30 秒）
luatos-cli flash run --soc firmware.soc --port COM10 --tail-log-secs 30

# 文本日志
luatos-cli log view --port COM6 --baud 921600

# 二进制日志（Air1601/Air1602/EC718）
luatos-cli log view-binary --port COM10 --baud 2000000 --probe

# Air8101(BK72XX) 新格式脚本 FOTA
luatos-cli fota build --new air8101.soc --script-only -o air8101_script_fota.bin

# Air780EPM / Air780EHM / Air8000 仅脚本 FOTA
luatos-cli fota build --new firmware.soc --script-only

# EC7xx 差分 FOTA：底层固件相同时自动回落到脚本更新包
luatos-cli fota build --new v2.soc --old v1.soc          # 自动回落
luatos-cli fota build --new v2.soc --old v1.soc --force-par  # 强制走 FotaToolkit 差分

型号文档（按型号拆分）

• Air1601 / Air1602 / CCM4211
• Air8000 / EC7xx / Air780E 系列
• Air8101 / BK72xx
• Air6208 / XT804 / Air101/Air103
• SF32LB58

常用命令分组

luatos-cli serial list
luatos-cli soc info firmware.soc
luatos-cli flash run --help
luatos-cli flash script --help
luatos-cli flash test --help
luatos-cli log view --help
luatos-cli log view-binary --help
luatos-cli project wizard --help
luatos-cli doctor --help

flash test 关键字判定说明

• 未传 --keyword 时，默认检查 LuatOS@
• 显式传入 --keyword 时，仅按传入关键字判定
• 可选 --fail-keyword（可重复）用于快速判失败：命中任意一项立即结束并判定 FAIL
• Air1601/Air1602 机型执行 flash test --script <dir> 时，会先全量刷机，再覆盖脚本分区后再抓日志判定关键字
• 结果为 FAIL 时会输出缺失关键字列表（JSON 输出为 missing_keywords）

支持的模组（摘要）

模组	芯片	刷机	脚本区	文件系统	FSKV	FOTA	日志	闭环测试
Air8101	BK7258 (bk72xx)	✅	✅	✅	✅	✅（新格式全量/脚本）	文本	✅
Air6208	XT804 (air6208)	✅	✅	✅	✅	✅（全量）	二进制	✅
Air101/103	XT804	✅	✅	—	—	✅（全量）	二进制	✅
Air1601 / Air1602	CCM4211	✅	✅	✅	✅	✅（全量/脚本）	二进制 (--probe)	✅
Air8000 / Air780E	EC718 (ec7xx)	✅	✅	—	—	✅（差分/脚本）	二进制 (--probe)	✅
Air8101(SF32)	SF32LB58	✅	✅	—	✅	—	文本	—

结构化输出

luatos-cli --format json serial list
luatos-cli --format json flash test --soc firmware.soc --port COM6
luatos-cli --format jsonl flash run --soc firmware.soc --port COM10 --tail-log-secs 30

开发

cargo fmt --check
cargo clippy -- -D warnings
cargo test --workspace

License

MIT