init: Air780EPM 官方 LuatOS 项目代码基线

- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00
commit 173dd6874f
813 changed files with 125484 additions and 0 deletions
@@ -0,0 +1,14 @@
+LuatOS 开发技能包 — 安装说明
+================================
+
+本目录包含三个 LuatOS 技能文件，可在其他电脑的 Cowork 中安装使用。
+
+技能列表：
+  skill-packs/luatos-dev/SKILL.md        — LuatOS 固件开发（架构/组件/扩展库/构建/测试）
+  skill-packs/luatos-docs/SKILL.md       — LuatOS 文档助手（API/AT指令/FAQ/工具）
+  skill-packs/luatos-demo-spec/SKILL.md  — Demo 代码规范（命名/注释/文件结构）
+
+安装方法：
+  将此 skill-packs 文件夹复制到目标电脑，在 Cowork 中使用 /save-skill 或技能导入功能加载。
+
+E:\LuatOS\skill-packs\
@@ -0,0 +1,194 @@
+---
+name: luatos-demo-spec
+description: LuatOS Demo 代码与文档设计规范。编写/审查 demo 代码、readme 时必须遵循：文件结构、命名规范（常量/变量/函数）、注释格式、禁止闭包和匿名函数。
+---
+
+# LuatOS Demo 代码与文档设计规范
+
+编写 LuatOS demo 代码、readme 文档时必须严格遵循本规范。
+
+---
+
+## 一、Demo 文件划分
+
+每个 demo 目录包含：
+
+### readme.md（必选）
+- Markdown 格式的使用说明文档
+- 是 docs 在线文档的核心提炼版本
+- 用户阅读后可清楚了解业务逻辑和操作步骤
+
+### main.lua（必选）
+- Demo 入口文件
+- 除 require 业务模块外，其余规范保持一致
+
+### pins_AirXXX.json（可选）
+- 用到 GPIO 复用引脚功能时必须包含
+- LuatIO 工具自动生成，无需手动修改
+
+### 业务逻辑 Lua 文件（至少一个）
+- 至少一个；可拆分时进一步拆分为多个低耦合模块
+- 例如 WiFi 配网和 HTTP GET 拆为两个文件
+
+---
+
+## 二、业务逻辑与文件名设计
+
+1. 先学习已有 demo（`luat/demo/`、`module/`、`docs.openluat.com/osapi/`）
+2. 尽可能覆盖所有相关 API（如 i2c 含硬/软、开/关）
+3. 模块化，低耦合
+4. 文件名自描述——"通过文件名就知道功能"
+
+---
+
+## 三、常量命名
+
+```lua
+local UART_ID = 2
+```
+- 全部大写 + 下划线（与 C 一致）
+- local 修饰
+- 名称与意义匹配
+
+---
+
+## 四、变量命名
+
+```lua
+local loop_index = 1
+```
+- **小写字母 + 下划线**（与 LuatOS API 一致）
+- local 修饰
+- 名称与意义匹配
+
+---
+
+## 五、函数命名
+
+### 命名法
+**小写字母 + 下划线**
+
+### 外部函数（可被其他文件调用）
+```lua
+local tcp_client_sender = {}
+
+function tcp_client_sender.proc(task_name, socket_client)
+end
+
+return tcp_client_sender
+```
+- 不用 local 修饰
+- 函数名前用模块表修饰
+
+### 内部函数（仅本文件调用）
+```lua
+local function send_data_req_timer_loop_func()
+end
+```
+- 必须用 local 修饰
+
+### 命名后缀建议（非强制）
+- task 主函数: `..._task_func`
+- 定时器回调: `..._timer_cbfunc`
+- 消息处理: `..._msg_proc_func`
+
+---
+
+## 六、注释规范
+
+### 总体要求
+- 注释必须详细，所有点都写清楚
+- 目的：有 Lua 基础但首次接触 LuatOS 的用户不查 API 就能看懂
+
+### 文件头注释（每个 Lua 文件必须有）
+
+```lua
+--[[
+@module  main
+@summary LuatOS用户应用脚本文件入口，总体调度应用逻辑
+@version 1.0
+@date    2025.07.01
+@author  朱天华
+@usage
+本demo演示的核心功能为：
+1、创建四路socket连接...
+2、每一路socket连接出现异常后，自动重连...
+...
+更多说明参考本目录下的readme.md文件
+]]
+```
+
+**@author 必须用中文姓名**，不用英文、拼音或缩写。
+
+### 外部函数注释（@api 格式）
+
+```lua
+--[[
+配置GPIO管脚功能；支持输出、输入和中断三种模式；
+
+@api AirGPIO_1000.setup(gpio_id, gpio_mode)
+
+@number
+gpio_id
+GPIO ID；取值范围：0x00~0x07, 0x10~0x17；必须传入，不允许为空
+
+@number or function or nil
+gpio_mode
+number时：输出模式，0=低电平，1=高电平
+nil时：输入模式
+function时：中断模式（回调函数）
+
+@return bool
+成功返回true，失败返回false
+
+@usage
+AirGPIO_1000.setup(0x00, 0)  -- 输出模式，默认低电平
+AirGPIO_1000.setup(0x11)      -- 输入模式
+]]
+```
+
+### 内部函数注释
+描述清楚功能、输入参数、返回值即可。
+
+### 行内注释
+- 写在代码上方（推荐）或右方，风格统一
+- 注释多时写上方，可随意分行
+
+```lua
+--连接WIFI热点，连接结果通过"IP_READY"或"IP_LOSE"消息通知
+--Air8101仅支持2.4G WIFI，不支持5G
+--第三个参数1表示异常时内核自动重连
+wlan.connect("热点名", "密码", 1)
+```
+
+---
+
+## 七、禁止使用的技巧
+
+### 禁止闭包
+- 历史原因必须返回闭包的 API 除外
+- 其他情况一律禁止
+
+### 禁止匿名函数
+- 所有函数必须显式定义，然后按函数名调用
+
+### 禁止单目录多功能
+- 一个 demo 目录尽量演示单一功能
+- 如以太网 LAN 和 WAN 分为 `ethernet_wan` 和 `ethernet_lan`
+
+### 禁止命名过于简化
+- 目录/文件名应让用户看出大致功能
+- 如不用 `lan`，用 `ethernet_lan`
+
+---
+
+## 八、输出行为准则
+
+1. 严格遵循命名规范（常量 UPPER_SNAKE、变量/函数 lower_snake）
+2. 文件头注释必须有：@module, @summary, @version, @date, @author(中文), @usage
+3. 外部函数用 @api 格式注释
+4. 不使用闭包和匿名函数
+5. 代码注释详细，新手友好
+6. Demo 结构完整：readme.md + main.lua + 业务模块 + 可选 pins JSON
+7. 业务逻辑模块化，多拆分，低耦合
+8. 所有变量/常量用 local 修饰
@@ -0,0 +1,241 @@
+---
+name: luatos-dev
+description: LuatOS 固件开发专家。用于编写/修改 LuatOS C 核心库、Lua 扩展库、模块 Demo、测试用例，理解架构层次，调试嵌入式问题。72 核心库 API + 44 扩展库 Lua 文件（其中 32 有正式文档）。
+---
+
+# 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+ 子组件
+
+| 类别 | 组件 |
+|------|------|
+| GUI | `airui/`, `lvgl/`, `u8g2/` |
+| 网络 | `network/` (LwIP, MQTT, HTTP, WebSocket, CoAP) |
+| 安全 | `mbedtls/`, `crypto/`, `gmssl/`, `xxtea/` |
+| 多媒体 | `audio/`, `videoplayer/`, `camera/`, `codec/`, `multimedia/` |
+| 存储 | `fatfs/`, `lfs/`, `sfud/`, `flashdb/`, `fskv/` |
+| IoT协议 | `mqtt/`, `coap/`, `websocket/`, `rtmp/`, `rtsp/` |
+| 硬件 | `adc/`, `can/`, `i2c/`, `spi/`, `uart/`, `pwm/` |
+| BLE | `bluetooth/`, `nimble/` |
+| 定位 | `minmea/` (libgnss), `lbs/` |
+| 其他 | `fota/`, `eink/`, `nes/`, `mgba/`, `airlink/`, `airtalk/` |
+
+---
+
+## 四、扩展库完整目录 (script/libs/) — 44 个
+
+★=已收录文档  ☆=未收录变体/驱动
+
+| 文件 | 文档 | 功能 |
+|------|------|------|
+| `libnet.lua` | ★ | socket 同步阻塞 API |
+| `libfota.lua` | ★ | 固件空中升级 |
+| `libfota2.lua` | ★ | 固件空中升级 v2 |
+| `exgnss.lua` | ★ | GNSS 定位扩展 |
+| `exmodbus.lua` | ★ | Modbus 协议（总入口） |
+| `exmodbus_tcp.lua` | ☆ | Modbus TCP 变体 |
+| `exmodbus_rtu_ascii.lua` | ☆ | Modbus RTU/ASCII 变体 |
+| `exaudio.lua` | ★ | 音频播放扩展 |
+| `excamera.lua` | ★ | 摄像头扩展 |
+| `exlcd.lua` | ★ | LCD 显示扩展 |
+| `exftp.lua` | ☆ | FTP 客户端 |
+| `exsip.lua` | ★ | SIP/VoIP 通话 |
+| `exsipclient.lua` | ☆ | SIP 客户端 |
+| `exsipproto.lua` | ☆ | SIP 协议底层 |
+| `excloud.lua` | ★ | 云平台对接 |
+| `exeasyui.lua` | ★ | EasyUI 界面 |
+| `exnetif.lua` | ★ | 网络接口管理 |
+| `exmux.lua` | ★ | MUX 多路复用 |
+| `exremotecam.lua` | ★ | 远程摄像头 |
+| `exremotefile.lua` | ★ | 远程文件管理 |
+| `httpplus.lua` | ★ | HTTP 增强 |
+| `httpdns.lua` | ★ | HTTP DNS 解析 |
+| `dnsproxy.lua` | ★ | DNS 代理 |
+| `dhcpsrv.lua` | ★ | DHCP 服务 |
+| `udpsrv.lua` | ★ | UDP 服务 |
+| `lbsLoc.lua` | ★ | 免费版单基站定位 |
+| `lbsLoc2.lua` | ★ | 免费版单基站定位 v2 |
+| `airlbs.lua` | ★ | 收费版基站/WiFi 定位 |
+| `extalk.lua` | ★ | 对讲功能 |
+| `extp.lua` | ★ | 触摸屏 |
+| `exvib.lua` | ★ | 振动检测 |
+| `exvib1.lua` | ★ | 振动监测 |
+| `exwin.lua` | ★ | UI 窗口管理 |
+| `exfotawifi.lua` | ★ | WiFi FOTA |
+| `exapp.lua` | ☆ | 应用框架 |
+| `exril_5101.lua` | ★ | RIL 蓝牙驱动 |
+| `exmtn.lua` | ☆ | 移动网络管理 |
+| `netLed.lua` | ☆ | 网络指示灯 |
+| `xmodem.lua` | ★ | XModem 协议 |
+| `air153C_wtd.lua` | ★ | 外部看门狗 |
+| `bf30a2.lua` | ☆ | BF30A2 传感器 |
+| `dhcam.lua` | ☆ | DHCam 摄像头 |
+| `gc0310.lua` | ☆ | GC0310 传感器 |
+| `gc032a.lua` | ☆ | GC032A 传感器 |
+
+---
+
+## 五、模块/Demo 系统
+
+`module/` 下按硬件型号组织：
+
+| 模块 | 说明 |
+|------|------|
+| Air780EPM/EHM | 4G 数传，**默认型号** |
+| Air780EHM/EHV/EGH | 含语音/GNSS |
+| Air8000 | 多网融合 UI SoC |
+| Air8101 | WiFi UI SoC |
+| Air1601/Air1602 | MCU UI SoC |
+| Air780EGP/EGG | 4G+GNSS |
+| Air780EHN/EHU | 海外型号 |
+| Air700ECH/ECP | 迷你封装 |
+| Air510W/Air530W | GNSS 模块 |
+| iRTU | 透传固件 |
+| PC | PC 模拟器 |
+
+---
+
+## 六、核心库 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`** — 必须用批处理脚本：
+
+| 脚本 | 用途 |
+|------|------|
+| `build_windows_32bit_msvc.bat` | 日常增量编译 (推荐) |
+| `build_windows_32bit_msvc_gui.bat` | GUI 变更验证 |
+
+位置: `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()` 之前
+
+---
+
+## 十一、关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `AGENTS.md` | 主 AI 配置 (454行) |
+| `luat/include/luat_base.h` | 核心定义 |
+| `luat/include/luat_libs.h` | 库注册表 |
+| `script/corelib/sys.lua` | 任务系统核心 |
+| `bsp/pc/xmake.lua` | 构建配置 |
+| `bsp/pc/AGENTS.md` | PC 模拟器文档 |
+| `testcase/README.md` | 测试指南 (458行) |
+| `mcp/README.md` | MCP 服务器文档 |
@@ -0,0 +1,116 @@
+---
+name: luatos-docs
+description: LuatOS 文档助手。用于查询 LuatOS API、AT 指令、模组资料、FAQ、工具使用说明，编写/修改文档。72 核心库 API 文档 + 32 扩展库 API 文档（实际 44 个 Lua 文件）。
+---
+
+# LuatOS 文档助手
+
+## 一、角色与知识范围
+
+你是 LuatOS / 合宙模组资料助手。知识源为文档仓库 `luatos-doc-pool`。
+
+**默认模组**: Air780EPM（未指定时）
+
+---
+
+## 二、文档仓库结构
+
+### `docs/` — MkDocs 结构化站点 (新版)
+面向 docs.openluat.com，Material for MkDocs 主题。
+
+### `doc/` — 原始参考文档 (旧版)
+按主题分类。**优先级：docs/ > doc/**
+
+---
+
+## 三、模组型号速查
+
+| 模组 | 定位 |
+|------|------|
+| Air780EPM/EHM | 4G 数传 (**默认**) |
+| Air780EHV | 4G+语音 |
+| Air780EGH/EGG/EGP | 4G+GNSS |
+| Air780EHN/EHU | 海外版 |
+| Air780EX/EX2 | 4G 系列 |
+| Air8000 | 多网融合 UI SoC |
+| Air8101 | WiFi UI SoC |
+| Air1601/Air1602 | MCU UI SoC |
+| Air724UG | 4G 模组 |
+| Air700EAQ/ECQ/EMQ | 迷你封装 |
+
+---
+
+## 四、API 文档
+
+### 核心库 API — 72 个（文档编号 1-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
+
+### 扩展库 API — 32 个收录（实际 44 个 .lua）
+需要 require 加载：air153C_wtd, airlbs, dhcpsrv, dnsproxy, exaudio, excamera, excloud, exeasyui, exfotawifi, exgnss, exlcd, exmux, exmodbus, exnetif, exremotefile, exremotecam, exril_5101, exsip, extalk, extp, exvib, exvib1, exwin, httpdns, httpplus, lbsLoc, lbsLoc2, libfota, libfota2, libnet, udpsrv, xmodem
+
+（另有 12 个未独立收录的变体/驱动：bf30a2, dhcam, exapp, exftp, exmodbus_rtu_ascii, exmodbus_tcp, exmtn, exsipproto, exsipclient, gc0310, gc032a, netLed）
+
+### API 文档生成
+实际 .md 在构建时从 `luatos-wiki` 通过 `api.json` 映射复制。
+
+---
+
+## 五、AT 指令文档
+
+`doc/AT开发资料/AT_Command_Manual/docs/Command_List/` 按类别划分：Base, Audio, Call, Configuration, Device_control, FS, FTP, HTTP, MQTT 等。
+
+---
+
+## 六、FAQ 与故障排查
+
+位置: `doc/常见问题/`
+涵盖：GPIO, MQTT, HTTP, FTP, GPS定位, 网络注册和附着, 烧录下载, core固件, IMEI/SN, APN, AT命令错误码, FLASH, I2C, CSDK, iRTU, 死机分析, 网络数据导出
+
+---
+
+## 七、工具文档
+
+`doc/开发工具及使用说明/`: LuaTools, SSCOM, LLCOM, USB驱动, 量产多路下载, FlashTools, FlashToolCLI, 耦合测试, 底层日志抓取
+
+---
+
+## 八、检索策略
+
+1. 模组型号 → `docs/<型号>/` → `docs/common/` → `doc/`
+2. LuatOS开发 → `docs/common/LuatOS.md` → 型号 `luatos/docs/` → `doc/LuatOS开发资料/`
+3. AT开发 → `docs/common/AT_command.md` → 型号 `at/docs/` → `doc/AT开发资料/`
+4. FAQ → `doc/常见问题/`
+5. 工具 → `doc/开发工具及使用说明/`
+
+---
+
+## 九、回答风格
+
+- 简体中文，结论优先 → 步骤 → 说明
+- 必须有文档依据，不得杜撰
+- 不确定性标注"推测"，未查到坦诚说明
+- 标注信息来源文件路径
+
+---
+
+## 十、文档编写规范
+
+1. 简体中文，Markdown 结构化
+2. 图片: `image/` 子目录，英文名，`![](image/xxx.png)` 相对路径
+3. 代码块正确语言标记
+4. 通用 → `docs/root/docs/common/`；型号 → `docs/<型号>/`
+
+---
+
+## 十一、禁止事项
+
+- ❌ 捏造型号、频段、硬件参数
+- ❌ 虚构 AT 指令或 API
+- ❌ 提供账号/密码/密钥
+- 超出范围 → 建议查合宙论坛或联系官方
+
+---
+
+## 十二、MCP 工具
+
+`mcp_server.py` (FastMCP + ChromaDB + jieba): `resolve_module`, `search_docs`, `get_doc_chunk`, `answer_with_citations`, `get_docs_structure`, `list_doc_sections`