跳转至

下载和调试

本文介绍如何配合 Luatools 对 Air8781 进行固件下载与日志抓取。Air8781 出厂固件基于合宙 4G 模组 Air780EPM 内核（core 选 Air780EPM），因此下载与调试方式与 Air780 系列一致。

1. 环境准备

1.1 硬件环境

  • Air8781 整机；
  • USB 数据线（用于供电、USB 下载与日志抓取）；
  • SIM 卡（正常使用需插入可用的 SIM 卡）；
  • 4G 天线（Air8781 外接 IPEX 天线）；
  • 下载调试转接板 AirBurn8781（用于切换下载/调试模式）；
  • 电脑：Windows 10 及以上。

1.2 软件环境

  • Luatools 调试工具（最新版，下载地址）；
  • lib 脚本：用 Luatools 烧录时勾选「添加默认 lib」，使用默认 lib 脚本文件。

内核固件、出厂打包固件、Lua 应用脚本与资源文件已在 默认出厂固件 中说明。

2. 安装 Luatools

  1. 运行环境：Windows 10 及以上；不支持 Mac 和 Linux。
  2. 下载 Luatools v3（文件名 Luatools_v3.exe）。
  3. 建议在某个盘（如 D 盘）根目录新建 Luatools 文件夹，把 Luatools_v3.exe 放进去（目录过深可能导致部分功能异常）。
  4. 双击 Luatools_v3.exe 启动，关闭每日 tips，点「开始」更新；若被杀软拦截，请务必放行。
  5. 更新完成后会生成 _temp / config / log / resource / project 等文件夹。

向合宙技术人员寻求远程支持时，需提交 log 目录下的文件（如 4gdiag 底层日志、ramdump 死机文件、trace_* 调试日志）。

3. 进入下载模式

Air8781 搭配下载调试转接板 AirBurn8781，通过拨动开关切换模式：

  • 拨至「下载」：USB_BOOT 与 3.3V 导通，使 Air8781 进入 USB 下载模式；
  • 拨至「调试」：USB_BOOT 断开，Air8781 正常开机，正常接收 Trace。

转接板详细说明见 产品介绍 的「下载和调试」章节。

4. 下载固件

4.1 量产文件刷机

如果只是要把设备恢复到出厂固件，使用「量产文件刷机」：

  1. 将 Air8781 插到 AirBurn8781 转接板上，拨动开关拨至「下载」，再用 USB 连接 PC；
  2. 打开 Luatools，点击「下载固件」；
  3. 在弹出的「下载固件」窗口中点击「量产文件刷机」；
  4. 点击「选择文件」，选中出厂固件 .soc 文件（例如 Air8781P_001.001.000_LuatOS-SoC_V2052_Air780EPM_110.soc）；
  5. 点击「下载」，等待进度完成即可。

4.2 底层 core + 脚本烧录

如果要二次开发、单独替换脚本或底层 core，请用「项目管理测试」方式：

  1. 将 Air8781 插到 AirBurn8781 转接板上，拨动开关拨至「下载」，再用 USB 连接 PC；

  2. 打开 Luatools，点击「项目管理测试」入口；

    Luatools 项目管理入口

  3. 若未建过项目，先新建一个项目；

  4. 选择底层固件：二次开发选 Air780EPM 内核 .soc，再添加自己的脚本与资源文件；

  5. 添加脚本以及资源文件；

  6. 勾选「添加默认 lib」（require 了扩展库会直接烧录；不勾选会提示缺少 xxx.lua）；

  7. 点击「下载底层和脚本」烧录；

    LuatOS 项目管理界面：选择底层 core、添加脚本、勾选添加默认 lib、下载底层和脚本

  8. 若只是脚本变动、固件不变，点「下载脚本」即可。

5. 抓取日志

Air8781 的日志默认通过 USB 虚拟串口输出，Luatools 自动识别，无需设置波特率。

  1. Luatools「日志打印窗口」勾选「4G 模块 USB 打印」（USB 物理连接时务必勾选）；

    Luatools 日志打印窗口，勾选「4G 模块 USB 打印」

  2. 将 Air8781 拨动开关拨至「调试」，上电 / 重启设备，观察日志；

  3. 典型日志：USB 设备枚举、驻网注册、业务启动、固件版本信息等。

Luatools 抓取的日志保存在工具目录的 log 文件夹下：

  • main_当天日期.txt：工具本身的日志，用于工具报错时查找原因；
  • trace_当天日期_首次记录时间.txt：用户日志，记录 LuatOS 里调用 print、log 等 API 输出的日志；
  • 4gdiag 文件夹：底层日志，LuatOS 日志无法定位问题时使用；
  • ramdump 文件夹：死机 dump 文件，用于死机问题分析。

日志的详细说明和与 EPAT 的配合使用，见 Luatools 下载和详细使用。

6. 常见问题排查

现象 排查方向
设备管理器识别不到端口 确认 USB 线可传数据；确认拨动开关拨至「下载」，看设备管理器虚拟 USB 数量是否增加；检查 USB 驱动
点开始下载没反应 / 提示找不到设备 确认 USB 已直连、拨动开关拨至「下载」让设备进入下载模式；检查 USB 驱动
烧录提示缺少 xxx.lua 项目管理中勾选「添加默认 lib」，或手动补对应 lib 脚本
搜索