geomative/GeomativeStudio/.qoder/repowiki/zh/content/故障排除/固件升级问题.md

# 固件升级问题

<cite>
**本文引用的文件**
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt)
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp)
- [FileTransfer.cpp](file://cpp/Tools/FileTransfer.cpp)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp)
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat)
- [License-GD20.bat](file://tools/License-GD20.bat)
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp)
- [http_client.h](file://h/httpClient/http_client.h)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性梳理固件升级过程中可能出现的问题与解决策略，重点围绕以下方面：
- 网络连接失败、服务器不可达、文件下载中断、校验错误等常见问题
- 解析日志“Could not resolve host: update.geomative.com”的根本原因与定位方法
- LicenseUpgrade.cpp 中升级流程的实现机制，包括 HTTP 请求处理与文件传输逻辑
- 提供解决方案：检查网络、配置代理、手动下载固件包等
- 指导用户使用 IAP-GD10.bat 等批处理脚本进行离线升级，并验证升级结果
- 为技术支持人员提供恢复模式的操作指南

## 项目结构
本仓库包含升级相关的 UI 交互、网络传输、文件下载、DFU 烧写与批处理脚本等模块。关键路径如下：
- 升级 UI 与流程控制：cpp/Operator/LicenseUpgrade.cpp
- 文件下载与传输：cpp/Tools/FileTransfer_crul.cpp、cpp/Tools/FileTransfer.cpp、cpp/Tools/HttpDownload.cpp
- 网络连接与重连：cpp/Tools/NetWorkOper.cpp
- 日志与诊断：LOG/upg_geo_filetrans_log.txt
- 离线升级脚本：Install/Geomative Studio/tools/IAP-GD10.bat、Install/Geomative Studio/tools/License-GD10.bat、tools/License-GD20.bat
- 在线固件升级流程：cpp/Tools/checkupdate.cpp

```mermaid
graph TB
subgraph "升级UI层"
LU["LicenseUpgrade.cpp"]
end
subgraph "传输与下载层"
FTC["FileTransfer_crul.cpp"]
FT["FileTransfer.cpp"]
HD["HttpDownload.cpp"]
end
subgraph "网络与重连"
NWO["NetWorkOper.cpp"]
end
subgraph "日志与诊断"
LOG["upg_geo_filetrans_log.txt"]
end
subgraph "离线脚本"
IAP["IAP-GD10.bat"]
LGD10["License-GD10.bat"]
LGD20["License-GD20.bat"]
end
subgraph "在线升级"
CU["checkupdate.cpp"]
end
LU --> FTC
LU --> FT
FTC --> LOG
IAP --> LGD10
LGD10 --> LGD20
CU --> LGD20
NWO --> LU
```

图表来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [FileTransfer.cpp](file://cpp/Tools/FileTransfer.cpp#L1-L47)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp#L60-L120)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L62-L125)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)

章节来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [FileTransfer.cpp](file://cpp/Tools/FileTransfer.cpp#L1-L47)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp#L60-L120)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L62-L125)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)

## 核心组件
- LicenseUpgrade：负责选择设备、下载 License 文件、触发 DFU 烧写脚本、显示进度与结果。
- FileTransfer_crul：基于 libcurl 的 HTTP 下载封装，支持超时、进度回调、错误日志与 IPv4 DNS 解析。
- FileTransfer：通用文件传输工具接口与辅助函数。
- HttpDownload：基于 Winsock 的多线程断点续传下载器（备用/对比实现）。
- NetWorkOper：网络连接管理、重连、控制命令收发与设备上下线通知。
- 日志：upg_geo_filetrans_log.txt 记录 DNS 解析失败等错误。
- 批处理脚本：IAP-GD10.bat、License-GD10.bat、License-GD20.bat 实现离线 DFU 烧写。
- checkupdate：在线固件升级流程（文件准备、复制、发送、校验）。

章节来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [FileTransfer.cpp](file://cpp/Tools/FileTransfer.cpp#L1-L47)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp#L60-L120)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L62-L125)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)

## 架构总览
升级流程分为在线与离线两条主线：
- 在线升级：LicenseUpgrade 触发 FileTransfer_crul 下载 FACTORY/LICENSE，随后通过批处理脚本执行 DFU 烧写。
- 离线升级：IAP-GD10.bat 先生成 DFU 文件，再通过 DfuSeCommand 烧写；License-GD10/20.bat 分别烧写 FACTORY 与 LICENSE。

```mermaid
sequenceDiagram
participant UI as "LicenseUpgrade.cpp"
participant FT as "FileTransfer_crul.cpp"
participant LOG as "upg_geo_filetrans_log.txt"
participant BAT as "License-GD10.bat/License-GD20.bat"
participant DFU as "DfuSeCommand"
participant DEV as "目标设备"
UI->>FT : 设置URL/路径/超时/进度
FT->>FT : GetUrlResConValild() 测试URL可达性(IPv4)
FT-->>UI : 返回下载结果
alt 成功
UI->>BAT : 启动烧写脚本
BAT->>DFU : 生成并烧写 FACTORY/LIC
DFU-->>DEV : 写入固件
UI-->>UI : 显示升级成功
else 失败
FT-->>LOG : 记录错误日志
UI-->>UI : 弹窗提示网络/权限/超时
end
```

图表来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L355-L428)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)

## 详细组件分析

### 组件A：LicenseUpgrade（在线升级流程）
- 功能要点
  - 设备选择与在线状态检查
  - 下载 FACTORY 与 LICENSE 文件（通过 FileTransfer_crul）
  - 触发 DFU 烧写脚本（License-GD10/20.bat）
  - 进度条与百分比显示
- 关键流程
  - 初始化 FileTransfer，设置下载路径、名称、超时与进度回调
  - 拼接下载 URL（theApp.m_strUpgUrl + 设备序列号 + 文件名）
  - 循环下载 FACTORY/LICENSE，失败则清理并返回
  - 下载完成后执行 DFU 烧写脚本，等待进程结束并提示结果

```mermaid
flowchart TD
Start(["进入 GetLicenseFile"]) --> Init["初始化 FileTransfer<br/>设置超时/进度/路径"]
Init --> Loop{"遍历 FACTORY/LICENSE"}
Loop --> |设置URL/名称| SetOpt["SetOption(OPT_URL_ADDRESS/OPT_DOWNLOAD_NAME)"]
SetOpt --> Download["DownloadFile()"]
Download --> Ok{"下载成功?"}
Ok --> |否| Cleanup["清理/删除 FACTORY 并返回失败"]
Ok --> |是| Next["更新进度/显示100%"]
Next --> Loop
Loop --> |完成| Burn["CreateProcess 启动 License-GD10/20.bat"]
Burn --> Wait["WaitForSingleObject 等待进程"]
Wait --> Result{"结果判定"}
Result --> |成功| Done(["升级成功"])
Result --> |超时/失败| Fail(["升级失败"])
```

图表来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)

章节来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)

### 组件B：FileTransfer_crul（HTTP 下载与错误日志）
- 功能要点
  - 初始化 libcurl，版本检查
  - 设置 URL、超时、进度回调、错误缓冲
  - GetUrlResConValild 对 URL 进行 HEAD 测试，强制使用 IPv4 解析，最多重试 3 次
  - DownloadFile 执行实际下载，写入本地文件，记录详细日志
- 错误日志
  - 当 curl_perform 失败时，记录错误信息与 URL
  - 当文件写入失败或字节数不匹配时，记录错误日志

```mermaid
flowchart TD
A["SetOption 配置"] --> B["GetUrlResConValild(URL)"]
B --> C{"curl_perform 成功?"}
C --> |否| E["记录错误日志<br/>返回失败"]
C --> |是| D["DownloadFile() 执行下载"]
D --> F{"CURLE_OK?"}
F --> |否| G["弹窗提示网络环境<br/>记录错误日志"]
F --> |是| H["关闭句柄/返回成功"]
```

图表来源
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L355-L428)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)

章节来源
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L355-L428)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)

### 组件C：离线升级脚本（IAP-GD10.bat 与 License-GD10/20.bat）
- IAP-GD10.bat
  - 生成 APP.dfu 并通过 DfuSeCommand 烧写
  - 删除临时 dfu 文件
- License-GD10/20.bat
  - 先烧写 FACTORY，再烧写 LICENSE
  - 使用 DfuCreateFile 与 DfuSeCommand

```mermaid
sequenceDiagram
participant U as "用户"
participant IAP as "IAP-GD10.bat"
participant DFU as "DfuCreateFile/DfuSeCommand"
participant L10 as "License-GD10.bat"
participant L20 as "License-GD20.bat"
U->>IAP : 双击运行
IAP->>DFU : 生成APP.dfu并烧写
U->>L10 : 双击运行
L10->>DFU : 生成并烧写 FACTORY
U->>L20 : 双击运行
L20->>DFU : 生成并烧写 LICENSE
```

图表来源
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)

章节来源
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)

### 组件D：在线固件升级（checkupdate.cpp）
- 功能要点
  - 准备固件文件，复制到 .\firmware\ 目录
  - 通过设备命令删除 SD 卡上的旧文件
  - 发送新文件到 /SD/ 并校验结果
- 适用场景
  - 在线升级功能板固件，与 License 升级流程互补

章节来源
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)

## 依赖关系分析
- LicenseUpgrade 依赖 FileTransfer_crul 进行 HTTP 下载
- FileTransfer_crul 依赖 libcurl，内部强制 IPv4 解析并带重试
- NetWorkOper 提供网络连接与重连能力，保障在线通信
- 批处理脚本依赖 dfu 工具链完成离线烧写
- 日志文件 upg_geo_filetrans_log.txt 记录 DNS 解析失败等错误

```mermaid
graph LR
LU["LicenseUpgrade.cpp"] --> FTC["FileTransfer_crul.cpp"]
FTC --> CURL["libcurl"]
NWO["NetWorkOper.cpp"] --> LU
LGD10["License-GD10.bat"] --> DFU["DfuSeCommand"]
LGD20["License-GD20.bat"] --> DFU
LOG["upg_geo_filetrans_log.txt"] --> FTC
```

图表来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L62-L125)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)

章节来源
- [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp#L173-L269)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L62-L125)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)

## 性能考量
- IPv4 强制解析与重试：GetUrlResConValild 中使用 IPv4 解析与最多 3 次重试，有助于在网络不稳定时提升成功率。
- 进度回调与超时：DownloadFile 支持进度回调与超时设置，避免长时间阻塞。
- 断点续传（对比实现）：HttpDownload 支持多线程断点续传，适合大文件下载场景。
- 离线烧写：批处理脚本一次性生成并烧写，减少多次交互带来的延迟。

章节来源
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L355-L428)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp#L60-L120)

## 故障排查指南

### 1. 症状：DNS 解析失败（Could not resolve host）
- 现象
  - 日志出现“Could not resolve host: update.geomative.com”
- 根因
  - DNS 解析失败或网络配置异常
  - 可能受代理、防火墙或本地 DNS 服务器影响
- 定位步骤
  - 使用 nslookup 或 ping 测试域名解析
  - 检查系统代理与企业防火墙策略
  - 在 FileTransfer_crul 中强制使用 IPv4 解析，减少 AAAA 记录干扰
- 解决方案
  - 更换 DNS 服务器（如 8.8.8.8 或 114.114.114.114）
  - 配置系统代理或绕过代理访问
  - 使用离线脚本进行升级（IAP-GD10.bat、License-GD10/20.bat）

章节来源
- [upg_geo_filetrans_log.txt](file://LOG/upg_geo_filetrans_log.txt#L1-L3)
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L355-L428)
- [http_client.h](file://h/httpClient/http_client.h#L593-L973)

### 2. 症状：服务器不可达/超时
- 现象
  - DownloadFile 返回失败，弹窗提示检查网络环境
- 根因
  - 网络不稳定、服务器负载高、超时设置过短
- 解决方案
  - 增大超时时间（SetOption(OPT_TIMEOUT)）
  - 使用断点续传（HttpDownload）或重试机制
  - 离线升级（下载到本地后使用批处理脚本）

章节来源
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L151-L281)
- [HttpDownload.cpp](file://cpp/Tools/HttpDownload.cpp#L60-L120)

### 3. 症状：文件下载中断/写入失败
- 现象
  - 写入文件失败或写入字节数不匹配
- 根因
  - 权限不足、磁盘空间不足、文件被占用
- 解决方案
  - 确认 .\tools\ 目录可写且有足够空间
  - 关闭占用文件的程序
  - 重新下载并检查校验

章节来源
- [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp#L284-L310)

### 4. 症状：校验错误/升级失败
- 现象
  - DFU 烧写后设备未识别或功能异常
- 根因
  - 文件损坏、版本不兼容、烧写顺序错误
- 解决方案
  - 重新下载并校验文件
  - 按 FACTORY -> LICENSE 的顺序烧写
  - 使用 checkupdate.cpp 的在线升级流程进行功能板固件升级

章节来源
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)

### 5. 症状：网络连接不稳定
- 现象
  - 连接中断、重连频繁
- 根因
  - 网络波动、代理切换、设备上下线
- 解决方案
  - 使用 NetWorkOper 的自动重连机制
  - 避免在 WiFi 模式下进行大量数据传输
  - 保持稳定的网络环境

章节来源
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L366-L480)

## 结论
- 在线升级依赖稳定的网络与正确的 DNS 解析；FileTransfer_crul 提供了 IPv4 强制解析与重试机制，显著提升成功率。
- 离线升级通过批处理脚本与 DFU 工具链实现，适用于网络受限或不可达场景。
- 日志文件与错误提示是快速定位问题的关键，建议优先查看 upg_geo_filetrans_log.txt 与 FileTransfer_crul 的错误日志。
- 技术支持可结合 NetWorkOper 的重连逻辑与 checkupdate.cpp 的在线升级流程，完成复杂场景下的恢复与验证。

## 附录

### A. 使用 IAP-GD10.bat 进行离线升级
- 步骤
  - 运行 IAP-GD10.bat 生成并烧写 APP.dfu
  - 运行 License-GD10.bat 烧写 FACTORY
  - 运行 License-GD20.bat 烧写 LICENSE
- 验证
  - 观察脚本输出与设备指示灯状态
  - 重启设备并确认功能正常

章节来源
- [IAP-GD10.bat](file://Install/Geomative Studio/tools/IAP-GD10.bat#L1-L16)
- [License-GD10.bat](file://Install/Geomative Studio/tools/License-GD10.bat#L1-L20)
- [License-GD20.bat](file://tools/License-GD20.bat#L1-L20)

### B. 在线升级流程（checkupdate.cpp）
- 步骤
  - 准备固件文件并复制到 .\firmware\ 目录
  - 通过设备命令删除 SD 卡旧文件
  - 发送新文件并校验结果
- 适用范围
  - 功能板固件升级，与 License 升级互补

章节来源
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1336)