跳转至

下载和调试

本文介绍如何配合 Luatools 对 Air780EGP V1.4 开发板进行固件下载与日志抓取。开发板基于 Air780EGP 4G + GNSS 模组设计，下载与调试方式与 Air780 系列一致。

一、环境准备

1.1 硬件环境

  • Air780EGP V1.4 开发板；
  • Type-C 接口的 USB 数据线（用于供电、USB 下载与日志抓取）；
  • SIM 卡（正常使用需插入可用的 SIM 卡）；
  • 4G 天线与 GNSS 天线（按开发板实际天线接口连接）；
  • 电脑：Windows 10 及以上。

1.2 软件环境

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

固件版本、量产文件与 Demo 源码已在 默认出厂固件 中说明。

二、安装 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_* 调试日志）。

三、进入下载模式

需要通过 USB 烧录软件时，需在上电前让设备进入 USB 下载模式，正常开机则进入调试模式。开发板的供电、USB 连接方式以及如何进入下载模式，详见 电路和使用说明 中「一、开发板使用说明」给出的开发板使用说明 PDF。

以 Air780Exx 系列 V1.4 开发板为例，根据当前运行状态执行以下任一种操作即可进入 BOOT 下载模式：

  1. 开发板未开机时：按住 BOOT 键，然后长按 PWR 开机键；
  2. 开发板已开机时：按下 BOOT 键，然后短按重启键。

判断是否成功进入 BOOT 下载模式：

在电脑设备管理器的串口设备中只出现一个端口，表示已进入下载模式；若出现三个，表示没有进入下载模式，需要重新操作。

设备管理器_设备进入下载模式

设备管理器_设备正常运行

四、下载固件

4.1 量产文件刷机

如果只是要把开发板恢复到默认固件，使用「量产文件刷机」：

  1. 用 USB 连接 PC，给设备开机；
  2. 打开 Luatools，点击右上角的「使用量产文件刷机」，此时会弹出一个新窗口；
  3. 点击「选择文件」，选中 Air780EGP 的 .soc 文件（见 默认出厂固件）；
  4. 点击「下载」，等待进度完成即可。

4.2 底层 core + 脚本烧录

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

  1. 用 USB 连接 PC，给设备开机；

  2. 打开 Luatools，点击右上角的「项目管理」入口，此时会弹出一个新窗口；

    Luatoools_点击项目管理按钮

  3. 若未建过项目，先点击左下角的「创建」；

  4. 右上角选择底层固件：选 Air780EGP 的内核 .soc，再添加自己的脚本与资源文件；

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

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

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

    Luatools_点击下载底层和脚本进行烧录

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

五、抓取日志

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

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

    Luatools_勾选4G模块USB打印

  2. 上电 / 重启设备，观察日志；

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

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

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

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

六、常见问题排查

现象 排查方向
设备管理器识别不到端口 确认 USB 线可传数据；确认已进入下载模式（看设备管理器虚拟 USB 数量是否增加）；检查 USB 驱动
点开始下载没反应 / 提示找不到设备 确认 USB 已直连、设备已进入下载模式（上电前让设备进入 USB 下载模式）；检查 USB 驱动
烧录提示缺少 xxx.lua 项目管理中勾选「添加默认 lib」，或手动补对应 lib 脚本
GNSS 无法定位 确认已连接 GNSS 天线并处于室外开阔环境；确认使用的是包含 libgnss 核心库的固件；注意 UART2 已被内部 GNSS 占用
搜索