跳转至

下载和调试

本文介绍如何配合 Luatools 对 Air8201 系列进行固件下载与日志抓取。Air8201 出厂固件基于合宙 Air780E 系列 4G 模组内核，因此下载与调试方式与 Air780E 系列一致。两个子系列的下载通道不同，需特别注意：

  • Air8201G：板上没有 USB 接口，USB 信号经 BTB 连接器 / 焊盘引出，需配合 Air8201G 扩展调试板，或通过焊盘上的下载串口经 USB 转 TTL 进行下载与日志抓取；
  • Air8201H：板载 USB Type-C 母口，可直接用 USB 线连接电脑下载与抓日志。

1. 环境准备

1.1 硬件环境

  • Air8201G 或 Air8201H 整机；
  • Air8201G：Air8201G 扩展调试板，或 USB 转 TTL 串口模块（CH340 / FT232 等，支持 3.3V 电平）与杜邦线 / 烧录治具；
  • Air8201H：USB 数据线（需支持数据传输）；
  • SIM 卡（正常使用需插入可用的 SIM 卡）；
  • 4G / GNSS 天线；
  • 供电：电池或外部 5V 电源（Air8201G 输入最高耐压 40V、Air8201H 为 6V，详见对应型号硬件资料）；
  • 电脑：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. 连接设备并进入下载模式

Air8201H（Type-C）

用 USB 数据线连接 Air8201H 板载 Type-C 与电脑，正常上电开机后 Luatools 即可识别；如下载不稳定，可在上电 / 复位前把 BOOT 拉高（与 VDD_EXT 短接），使设备强制进入下载模式。

Air8201G（扩展调试板 / 串口）

Air8201G 的 USB 与下载串口经 BTB / 焊盘引出：使用 Air8201G 扩展调试板时，将模组正确装入调试板 BTB，再用 USB 线连接调试板与电脑；使用 USB 转 TTL 直连焊盘时注意：

  • USB 转 TTL 的 TXD 接模组侧 RXD、RXD 接模组侧 TXD，GND 与焊盘 GND 共地；
  • USB 转 TTL 电平务必选 3.3V，不要使用 5V 电平；
  • 进入下载模式时，需在上电 / 复位前把 BOOT 拉高（与 VDD_EXT 短接），再给设备上电，使设备进入下载模式；正常上电开机则进入调试模式。

焊盘定义与调试板安装的视频教程，见 Air8201G 使用指南。

4. 下载固件

4.1 量产文件刷机

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

  1. 按上述方式连接设备，让设备进入下载模式并上电；
  2. 打开 Luatools，点击「下载固件」；
  3. 在弹出的「下载固件」窗口中点击「量产文件刷机」；
  4. 点击「选择文件」，选中 Air8201 对应型号的出厂固件 .soc 文件；
  5. 点击「下载」，等待进度完成即可。

4.2 底层 core + 脚本烧录

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

  1. 连接好设备，让设备进入下载模式并上电；

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

    Luatools 项目管理入口

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

  4. 选择底层固件：Air8201G 选 Air780EGH 对应内核、Air8201H 选 Air780EHM 对应内核的 .soc 文件，再添加自己的脚本与资源文件；

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

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

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

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

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

5. 抓取日志

  • Air8201H 经板载 Type-C 连接时，模组会枚举出虚拟串口，在 Luatools 日志打印窗口直接选择对应串口即可；
  • Air8201G 使用 USB 转 TTL 串口时没有 USB 虚拟串口，需在 Luatools 的「日志打印窗口」勾选「通用串口打印」并选择 USB 转 TTL 对应的 COM 口：

Luatools 通用串口打印设置

两路串口用途不同：

  • UART0（DBG_UART，调试串口）：波特率固定 921600，输出底层调试信息，不能当通用串口使用；低功耗场景的日志只能用 UART0 + EPAT 抓取；
  • UART1（MAIN_UART）：通用串口，输出 LuatOS 应用日志。

上电 / 重启设备后观察日志，典型日志包括：开机启动、驻网注册、GNSS 定位、业务启动、固件版本信息等。

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

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

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

6. 常见问题排查

现象 排查方向
设备管理器识别不到串口 / 设备 Air8201H 检查 USB 线是否支持数据传输；Air8201G 检查扩展调试板是否扣合到位，或 USB 转 TTL 驱动与共地
点开始下载没反应 / 提示找不到设备 确认 TXD/RXD 未接反、电平为 3.3V；确认上电 / 复位前已把 BOOT 拉高进入下载模式
日志乱码 UART0 波特率固定 921600，确认串口工具波特率设置一致；检查共地与 TXD/RXD 接线
烧录提示缺少 xxx.lua 项目管理中勾选「添加默认 lib」，或手动补对应 lib 脚本
GNSS 不定位 确认 GNSS 天线已接好；Air8201G 为内置 GNSS、Air8201H 为外置低功耗 GNSS 芯片，排查方式见 Air8201G 资料中心
搜索