跳转至

下载和调试

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

1. 环境准备

1.1 硬件环境

  • Air8782 整机；
  • USB 数据线（用于供电、USB 下载与日志抓取）；
  • SIM 卡（正常使用需插入可用的 SIM 卡）；
  • 4G 天线（Air8782 外接 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. 进入下载模式

为了让 Air8782P 更加方便的下载和调试，我们专门设计了一款下载调试转接板 AirBurn8781：

AirBurn8781 功能简介：

  1. 板载杰华特降压 DCDC 芯片 JW5357，将 USB_VBUS 提供的 5V 降压为 4V 给 Air8782P 供电，对应标注为 VBAT 的插针；
  2. 板载杰华特 LDO 芯片 JW7809，输出 3.3V 电压，在需要 Air8782P 下载时，通过拨动开关拨至「下载」即可实现 USB_BOOT 上拉至 3.3V，进而使 Air8782P 进入下载模式；
  3. 拨动开关，拨至「下载」的效果是 USB_BOOT 与 3.3V 导通，进入 USB 下载模式；拨至「调试」的效果是 USB_BOOT 与 3.3V 断开，Air8782P 正常开机，正常接收 Trace；
  4. AirBurn8781 上的 LED 为电源指示灯，用来表明 USB 是否供电正常；
  5. AirBurn8781 上的五根插针信号分别是：
PIN NO. 丝印名称 详细说明
1 VBAT 3.8V，给 Air8782P 的 VBAT 供电；对应接 Air8782P 的 PIN20；
2 GND GND；对应接 Air8782P 的 PIN19；
3 DP USB_DP；对应接 Air8782P 的 PIN18；
4 DN USB_DM；对应接 Air8782P 的 PIN17；
5 BOOT USB_BOOT；对应接 Air8782P 的 PIN16；
  1. 美图欣赏；

  1. 购买地址 Luat.taobao.com ；

4. 下载固件

4.1 量产文件刷机

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

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

4.2 底层 core + 脚本烧录

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

  1. 将 Air8782 插到 AirBurn8781 转接板上，拨动开关拨至「下载」，再用 USB 连接 PC；
  2. 打开 Luatools，点击「项目管理测试」入口；

Luatools 项目管理入口 3. 若未建过项目，先新建一个项目； 4. 选择底层固件：二次开发选 Air780EPM 内核 .soc，再添加自己的脚本与资源文件； 5. 添加脚本以及资源文件； 6. 勾选「添加默认 lib」（require 了扩展库会直接烧录；不勾选会提示缺少 xxx.lua）； 7. 点击「下载底层和脚本」烧录；

LuatOS 项目管理界面：选择底层 core、添加脚本、勾选添加默认 lib、下载底层和脚本 8. 若只是脚本变动、固件不变，点「下载脚本」即可。

5. 抓取日志

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

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

Luatools 日志打印窗口，勾选「4G 模块 USB 打印」 2. 将 Air8782 拨动开关拨至「调试」，上电 / 重启设备，观察日志； 3. 典型日志：USB 设备枚举、驻网注册、485/232/UART 透传、固件版本信息等。

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 脚本
搜索