luatos-dev

LuatOS 固件开发技能

一、项目概述

LuatOS 是合宙（openLuat）基于 Lua 5.3.5 的嵌入式 IoT 操作系统，支持 Air8000/Air8101/Air780E 系列等硬件平台。

构建系统: xmake (3.0.4+) 目标平台: ARM/RISC-V MCU + PC 模拟器 (Windows/Linux/macOS) 许可证: MIT

---

二、核心概念：核心库 vs 扩展库

核心库 (Core Library) = 固件内置的 C 代码层功能。位于 components/ 和 luat/modules/。固件编译时内置，无需加载，直接调用。例如：gpio.setup()、socket.tcp()、mqtt.create()。

文档收录 72 个核心库 API（编号 1-72）。

扩展库 (Extension Library) = 对核心库接口的 Lua 二次封装。位于 script/libs/ 下的 .lua 文件。代码内需要 require 加载才能使用。例如：require("libnet")、require("exgnss")。

script/libs/ 实际有 44 个 .lua 文件，其中 32 个有正式文档收录，12 个未收录的为变体或底层驱动。

每个型号的固件封装的核心库不同 → 功能不同。核心库功能只要固件内存在就可以直接调用其接口。

---

三、四层架构

┌─────────────────────────────┐
│  Layer 4: 脚本层 (script/)  │  Lua 库 + 应用模板
│  corelib/ | libs/ | turnkey/│
├─────────────────────────────┤
│  Layer 3: 组件层             │  60+ 子组件
│  components/                │  网络/安全/GUI/多媒体/存储/IoT
├─────────────────────────────┤
│  Layer 2: 核心框架 (luat/)  │  HAL + VFS + 任务调度
│  modules/ | vfs/ | include/ │
├─────────────────────────────┤
│  Layer 1: Lua 虚拟机 (lua/) │  Lua 5.3.5 优化版
└─────────────────────────────┘
                    ↕ BSP 层 (bsp/) 平台适配

Layer 1: Lua VM (lua/) — Lua 5.3.5 优化版

Layer 2: 核心框架 (luat/)

• luat/include/ — 核心 C 头文件
• luat/modules/ — C 实现的 Lua 库
• luat/vfs/ — 虚拟文件系统

Layer 3: 组件 (components/) — 60+ 子组件

---

四、扩展库完整目录 (script/libs/) — 44 个

★=已收录文档 ☆=未收录变体/驱动

---

五、模块/Demo 系统

module/ 下按硬件型号组织：

---

六、核心库 API — 72 个

adc, airlink, airui, audio, bit64, ble, camera, can, cc, codec, crypto, eink, errDump, fastlz, fatfs, fft, fota, fs, fskv, ftp, gmssl, gpio, hmeta, ht1621, http, httpsrv, hzfont, i2c, i2s, iconv, io, ioqueue, iotauth, iperf, json, lcd, libgnss, little_flash, log, lora2, mcu, miniz, mobile, mqtt, netdrv, onewire, os, otp, pack, pins, pm, protobuf, pwm, rsa, rtc, rtmp, rtos, sfud, sms, socket, spi, string, sys, tp, u8g2, uart, wdt, websocket, wlan, xxtea, ymodem, zbuff

---

七、构建系统

禁止直接运行 xmake -y — 必须用批处理脚本：

位置: bsp/pc/，运行: cmd /c build_windows_32bit_msvc.bat

---

八、编码规范

C 代码

• 核心 API 用 luat_ 前缀
• 模块文件: luat_lib_<module>.c
• #include "luat_base.h" 必须作为第一个 include
• 返回值: 0=成功，负数=错误

Lua 代码

• sys.taskInit(function() ... end) 用于异步
• sys.run() 必须在末尾
• 日志: log.info/warn/error(tag, msg)
• 库结构: local mod = {} → 函数 → return mod
• 加载: local mylib = require("mylib")

反模式

• ❌ 不要轮询 — 用 sys.wait()
• ❌ 不要阻塞主线程
• ❌ 不要用全局变量存模块状态
• ❌ 不要绕开 luat_ API
• ❌ 不要在 modules/ 加平台特定代码

---

九、测试框架

testcase/
├── common/scripts/    # testrunner.lua, testsuite.lua
├── utest/             # C 层 xxx.utest() 套件
├── unit/              # Lua 单元测试(按功能域分组)
│   ├── driver/
│   ├── fs/
│   ├── crypto/
│   ├── net/
│   └── ...
├── func/              # 功能/集成测试
│   ├── network/
│   ├── airlink/
│   ├── appstore/
│   └── eink/
├── platform/          # 平台/芯片专属测试
│   └── air1601/
├── ndk/               # NDK 通用回归套件
└── tools/             # 独立工具/分析测试
    └── memprof/

运行: build/out/luatos-lua.exe ../../testcase/common/scripts/ ../../testcase/<type>/<domain>/<feature>/scripts/

创建测试: 先按类型选父目录(unit/func/platform/utest),再加 metas.json + main.lua + <feature>_test.lua (函数名 test_ 开头)

---

十、常见陷阱

• lua_newuserdata 不会零初始化 → 必须 memset
• 异步回调可能在不同线程执行
• 不能 memcpy 运行时管理的异步句柄
• xmake remove_files 后 add_files 无效
• PC 测试必须 os.exit(0)，写在 sys.run() 之前

---

十一、关键文件