Linux下载工具使用指南(完善中)

---

文档修订记录

版本	日期	修改内容
V1.0	2026-07-22	初始版本，包含完整的跨平台固件下载流程，涵盖Windows端固件转换、Linux端工具编译和固件下载执行三个阶段

目录

1. 概述
2. 第一阶段：Windows端固件转换
3. 第二阶段：Linux端工具编译
4. 第三阶段：Linux端固件下载执行
5. 注意事项与FAQ

---

1 概述

1.1 工具简介

Linux下载工具（DownloadCLI）是一款用于在Linux环境下对域格EC716/EC718系列CAT1模组进行固件烧录的命令行工具。由于模组固件通常在Windows环境下编译生成，需要先经过域格移芯CAT1 Linux固件生成工具进行格式转换，生成Linux下载工具所需的配置文件和固件镜像，然后再通过DownloadCLI完成固件下载。

1.2 完整工作流程

整个固件下载流程分为三个阶段，涉及Windows和Linux两个操作系统环境：

flowchart LR
    A[阶段一 Windows固件转换] --> B[文件传输到Linux]
    B --> C[阶段二 Linux编译DownloadCLI]
    C --> D[阶段三 Linux端固件下载]

各阶段说明：

阶段	运行环境	操作	输入	输出
阶段一	Windows	使用固件生成工具将Windows固件转换为Linux下载格式	Windows编译的固件包（ZIP/文件夹）	config配置文件、image_*固件目录、format JSON
阶段二	Linux	编译DownloadCLI源码	源码包	DownloadCLI可执行文件
阶段三	Linux	使用DownloadCLI执行固件下载	配置文件 + 固件镜像 + DownloadCLI	模组固件烧录完成

1.3 涉及工具

工具名称	运行环境	作用
域格移芯CAT1 Linux固件生成工具	Windows	将Windows编译的固件转换为Linux下载格式
DownloadCLI	Linux	在Linux环境下执行固件下载

1.4 适用场景

本指南适用于以下场景：

• 在Linux服务器或嵌入式Linux环境下对模组进行固件烧录，务必确保本地环境验证OK后再使用
• 需要通过命令行脚本控制固件下载的场景

---

2 第一阶段：Windows端固件转换

2.1 工具获取与安装

域格移芯CAT1 Linux固件生成工具是一款Windows桌面应用程序，用于将Windows编译的固件转换为Linux下载工具所需的格式。

下载链接：域格移芯CAT1_Linux固件生成工具_v1.0.0.zip

安装步骤

1. 下载并解压工具压缩包到任意目录，目录结构如下：

   域格移芯CAT1_Linux固件生成工具/
   ├── 域格移芯CAT1_Linux固件生成工具.exe
   ├── FlashToolCLI_V4.1.11p01_240401/
   

2. 双击 域格移芯CAT1_Linux固件生成工具.exe 启动工具。

2.2 固件转换操作

步骤一：选择固件源

1. 在"固件源"下拉框中选择输入类型：

   • ZIP文件 -- 选择打包好的固件ZIP压缩包
   • 文件夹 -- 选择已解压的固件目录

2. 点击"浏览"按钮或拖拽文件到输入框。

步骤二：选择输出文件夹

点击"浏览"按钮选择输出目录，建议使用空目录。

步骤三：开始生成

点击"开始生成"按钮开始生成，具体操作参考视频演示。

2.3 输出文件说明

生成完成后，输出目录结构如下：

输出目录/
├── format_{芯片型号}.json          # Flash分区配置文件
├── config/
│   ├── {固件版本}_USB_linux.ini      # USB模式配置文件
│   └── {固件版本}_UART_linux.ini     # UART模式配置文件
└── image_ec716m/ 或 image_ec718m/
    ├── agentboot_usb/
    │   └── agentboot.bin           # USB模式agentboot
    ├── agentboot_uart/
    │   └── agentboot.bin           # UART模式agentboot
    └── {芯片型号}/
        ├── ap_bootloader.bin       # 引导程序
        ├── ap_at_command.bin       # AP固件
        ├── cp-demo-flash.bin       # CP固件
        └── at_command.binpkg       # 固件包

2.4 文件传输到Linux

生成完成后，需要将整个输出目录拷贝到Linux环境中。可通过以下方式传输：

• SCP命令：scp -r 输出目录 user@linux_ip:/目标路径
• SFTP工具：使用FileZilla等工具上传
• U盘拷贝：将文件复制到U盘，再在Linux环境中挂载读取

---

3 第二阶段：Linux端工具编译

3.1 编译环境准备

依赖安装

编译目标为32位Linux可执行程序，需提前安装32位编译库：

# Ubuntu/Debian
sudo apt-get install gcc-multilib

# CentOS/RHEL
sudo yum install glibc-devel.i686

3.2 源码编译

步骤一：获取源码

下载链接：YUGE_EC716_EC718_Linux_Download_Tool.zip

将DownloadCLI源码包解压到Linux环境中，目录结构如下：

DownloadCLI源码/
├── inc/           # 头文件目录
├── src/           # 源码文件目录

步骤二：前置修改（关键步骤）

Linux系统下编译时，termbits.h 头文件内的 struct termios 结构体与系统标准头文件存在重定义冲突，需要进行修改：

1. 打开 inc/termbits.h 文件
2. 注释屏蔽 struct termios 结构体定义，保留下方 struct termios2 结构体：

// struct termios {
//     tcflag_t c_iflag;        /* input mode flags */
//     tcflag_t c_oflag;        /* output mode flags */
//     tcflag_t c_cflag;        /* control mode flags */
//     tcflag_t c_lflag;        /* local mode flags */
//     cc_t c_line;             /* line discipline */
//     cc_t c_cc[NCCS];         /* control characters */
// };

struct termios2 {
    tcflag_t c_iflag;        /* input mode flags */
    tcflag_t c_oflag;        /* output mode flags */
    tcflag_t c_cflag;        /* control mode flags */
    tcflag_t c_lflag;        /* local mode flags */
    cc_t c_line;             /* line discipline */
    cc_t c_cc[NCCS];         /* control characters */
    speed_t c_ispeed;        /* input speed */
    speed_t c_ospeed;        /* output speed */
};

步骤三：执行编译

gcc -m32 -D_LINUX -g -o gccout/DownloadCLI -I inc src/download_cli.c src/action.c src/linux_comm.c src/utils.c src/package.c src/crc.c src/sha256.c src/ini.c src/cJSON.c

编译参数说明

参数	说明
-m32	编译生成 32 位可执行程序，适配 CAT1 Linux 模组运行环境
-D_LINUX	定义 Linux 系统编译宏，启用 Linux 平台串口通信逻辑
-g	加入调试符号，便于程序异常时 GDB 定位问题
-o gccout/DownloadCLI	指定输出程序路径与名称，生成文件存放于 gccout 目录
-I inc	指定头文件检索目录为 inc 文件夹
末尾.c 文件列表	项目全部业务源码文件，编译时需完整携带

编译验证

编译成功后，gccout 目录下将生成 DownloadCLI 可执行文件：

ls -la gccout/DownloadCLI

---

4 第三阶段：Linux端固件下载执行

4.1 部署准备

目录结构准备

在Linux环境中，将编译好的 DownloadCLI 和Windows端生成的固件配置文件组织为以下结构：

firmware_download/
├── DownloadCLI                   # 编译好的下载工具
├── format_{芯片型号}.json        # Flash分区配置文件（来自Windows）
├── config/
│   ├── {固件版本}_USB_linux.ini    # USB模式配置文件（来自Windows）
│   └── {固件版本}_UART_linux.ini   # UART模式配置文件（来自Windows）
└── image_*/                      # 固件镜像目录（来自Windows）
    ├── agentboot_usb/
    ├── agentboot_uart/
    └── {芯片型号}/

路径依赖说明：DownloadCLI 需要与配置文件、format JSON文件及image目录位于同一父目录下，配置文件中引用的固件路径为相对路径，需确保目录结构完整。

4.2 下载命令

USB模式下载

./DownloadCLI -p /dev/ttyACM0 -c config/YM310.X09S_AT.A60_R4.2.9.260721_USB_linux.ini

UART模式下载

./DownloadCLI -p /dev/ttyS0 -c config/YM310.X09S_AT.A60_R4.2.9.260721_UART_linux.ini

4.3 命令参数说明

参数	含义	使用说明
-p	指定模组AT串口设备节点	/dev/ttyACM0为USB虚拟串口示例，/dev/ttyS0为UART串口示例，根据实际硬件修改
-c	指定固件下载配置文件	配置文件路径需与实际目录结构匹配，内置模组波特率、分区、校验等下载参数

4.4 下载执行流程

下载工具启动后，将按以下步骤执行（示例流程）：

1. 解析指定的配置文件，获取固件路径和烧录参数
2. 打开指定的串口设备
3. 通过AT命令与模组建立通信
4. 将模组切换到固件下载模式
5. 按照配置文件中的分区信息依次烧录固件
6. 对烧录的数据进行校验
7. 下载完成后，重启模组使新固件生效

4.5 下载状态输出

下载过程中工具会输出实时状态信息到控制台，包含每一步的执行状态和进度。以下为示例输出：

[INFO] Opening serial port: /dev/ttyACM0
[INFO] Config file: config/YM310.X09S_AT.A60_R4.2.9.260721_USB_linux.ini
[INFO] Switching to download mode...
[INFO] Downloading agentboot...
[INFO] Downloading ap_bootloader...
[INFO] Downloading ap_at_command...
[INFO] Downloading cp-demo-flash...
[INFO] Verification completed successfully
[INFO] Download finished

---

5 注意事项与FAQ

5.1 操作约束

供电约束

• 固件下载全程禁止模组断电、重启
• 中途断电将导致模组固件损坏，损坏后USB模式下只能BOOT脚拉高进入下载模式方式下载

串口占用约束

• 下载执行期间，禁止其他进程读写目标AT串口
• 串口抢占会造成下载中断、校验失败
• 执行前使用 lsof | grep /dev/ttyXXX 检查串口占用情况

存储介质约束

• 本工具仅支持模组内置主分区固件烧录
• 不支持外部Flash固件下载

5.2 常见问题

Q1: 编译报 struct termios 重定义错误

• 原因：termbits.h 文件中的 struct termios 结构体与系统标准头文件冲突。
• 解决：参考3.2节步骤二，注释屏蔽 struct termios 结构体定义。

Q2: 程序运行提示串口打开失败

• 原因：串口节点不正确、权限不足或被其他程序占用。

• 解决：

  1. 确认串口节点正确（使用 ls /dev/tty* 查看）
  2. 检查串口权限（使用 sudo chmod 666 /dev/ttyXXX 赋予权限）
  3. 关闭占用串口的其他程序

Q3: 下载中途中断

• 原因：供电不稳定或串口连接问题。

• 解决：

  1. 检查供电稳定性，确保使用可靠电源
  2. 检查串口连接线，建议使用原装数据线
  3. 下载过程中禁止操作串口设备

Q4: 提示"未找到配置文件"

• 原因：配置文件路径不正确或未从Windows端完整拷贝输出目录。

• 解决：

  1. 确认 -c 参数指定的路径正确
  2. 确认输出目录已完整拷贝到Linux环境
  3. 检查目录结构是否完整（包含config和image_*目录）

Q5: 芯片型号检测有误，ap_size参数不正确

• 原因：固件生成工具自动检测芯片型号时出现偏差。

• 解决：

  1. 在Windows端查看固件生成工具的日志文件确认检测到的芯片型号
  2. 如果检测结果与实际不符，检查固件包中的目录名称和文件名

Q6: Windows端生成配置失败

• 原因：固件目录结构不正确或缺少必要文件。

• 解决：

  1. 查看Windows端工具目录下的 tool_log.txt 日志文件
  2. 确认固件源包含 *_USB.ini 文件
  3. 确保 FlashToolCLI_V4.1.11p01_240401 文件夹与主程序在同一目录

5.3 日志查看

Linux端日志

下载工具的运行日志直接输出到控制台，可通过重定向保存到文件：

./DownloadCLI -p /dev/ttyACM0 -c config/YM310.X09S_AT.A60_R4.2.9.260721_USB_linux.ini > download.log 2>&1

Windows端日志

固件生成工具的日志文件位于工具主程序所在目录，文件名为 tool_log.txt。