跳转至

下载和调试

本文介绍如何配合 Luatools 对 Air8203 进行固件下载与日志抓取。Air8203 出厂固件基于合宙 Air780E 系列 4G 模组内核，因此下载与调试方式与 Air780E 系列一致。需要注意的是，Air8203 板上没有 Type-C 等 USB 接口，固件下载与日志抓取都通过板边的 DOWNLOAD 测试点经 USB 转 TTL 串口进行。

1. 环境准备

1.1 硬件环境

  • Air8203 整机；
  • USB 转 TTL 串口模块（CH340 / FT232 等，支持 3.3V 电平；如需同时下载与抓日志可准备 2 个或多通道模块）；
  • 杜邦线 / 烧录治具（连接 USB 转 TTL 与 DOWNLOAD 测试点）；
  • SIM 卡（Micro-SIM，正常使用需插入可用的 SIM 卡）；
  • 4G / GNSS 外置天线（Air8203 均为 IPEX 外接天线，金属外壳装机时需先经 IPEX 转 SMA 同轴线再接外置天线）；
  • 供电：VIN（5-36V，建议稳态不超过 24V）或电池；
  • 电脑：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. 连接 DOWNLOAD 测试点并进入下载模式

Air8203 板边预留 5 针 DOWNLOAD 测试点，包含模组的 UART 收发信号、BOOT、电源地等，各测试点的具体定义与位置以 原理图及PCB封装 为准。

接线时注意：

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

4. 下载固件

4.1 量产文件刷机

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

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

4.2 底层 core + 脚本烧录

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

  1. USB 转 TTL 接好 DOWNLOAD 测试点，让设备进入下载模式并上电；

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

    Luatools 项目管理入口

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

  4. 选择底层固件：选 Air8203 对应子型号的 Air780E 系列内核 .soc（H 系列选 Air780EHM、V 系列选 Air780EHV、U 系列选 Air780EHU、N 系列选 Air780EHN），再添加自己的脚本与资源文件；

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

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

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

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

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

5. 抓取日志

Air8203 没有 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. 常见问题排查

现象 排查方向
设备管理器识别不到串口 检查 USB 转 TTL 模块的驱动；确认 USB 线可传数据；确认模块已与测试点 GND 共地
点开始下载没反应 / 提示找不到设备 确认 TXD/RXD 未接反、电平为 3.3V；确认上电 / 复位前已把 BOOT 拉高进入下载模式
日志乱码 UART0 波特率固定 921600，确认串口工具波特率设置一致；检查共地与 TXD/RXD 接线
烧录提示缺少 xxx.lua 项目管理中勾选「添加默认 lib」，或手动补对应 lib 脚本
GNSS 不定位 / GNSS 相关耗电异常 确认 GNSS IPEX 已接好外置有源天线；GPIO25 拉高可关闭 GNSS 供电，详见 电路和使用说明
搜索