跳转至
项目
版本
全文检索

2131E FOTA升级包制作工具 用户指南

概述

本指南介绍 FotaTool 图形界面与命令行的使用方法，帮助模块集成商和终端部署人员为 Hi2131 设备制作固件差分升级包，并通过串口完成近端升级与结果校验。

准备

安装 FotaTool

FotaTool 支持 Win10 及以上版本。建议将工具安装在非 C 盘；安装在 C 盘时，工具可能没有权限访问生成的中间文件。若系统只有 C 盘，安装完成后需以管理员权限运行。

FotaTool 安装包随 SDK 提供，位于仓库的 /tools/cat1.tar.gz。当前归档内的安装程序为 cat1/FOTA/FotaTool_V3.0.29.exe。解压后运行安装程序；安装成功后，可以在开始菜单中找到该工具。FotaTool工具的安装步骤如下：

  1. 打开FotaTool安装程序“FotaTool_V3.0.29.exe”。如图1所示，弹出FotaTool安装程序欢迎界面，单击“Next”按钮。

    图 1 FotaTool安装欢迎界面

    **图 1** FotaTool安装欢迎界面

  2. 弹出FotaTool安装路径选择界面，如图2所示，选择好安装路径后，勾选红框提示，单击“Next”按钮。

    图 2 FotaTool安装路径选择界面

    **图 2** FotaTool安装路径选择界面

  3. 弹出FotaTool菜单文件夹选择界面，如图3所示。用户可以自定义修改文件夹名或使用默认文件夹名，然后单击“Next”按钮。

    图 3 FotaTool安装菜单文件夹选择界面

    **图 3** FotaTool安装菜单文件夹选择界面

  4. 弹出FotaTool额外任务选择界面，如图4所示。选择是否创建桌面图标，并单击“Next”按钮。

    图 4 FotaTool额外任务选择界面

    **图 4** FotaTool额外任务选择界面

  5. 弹出FotaTool准备安装界面，如图5所示，单击“Install”按钮进行安装。

    图 5 FotaTool安装界面

    **图 5** FotaTool安装界面

  6. 弹出FotaTool正在安装界面，请等待直至安装完成。

  7. 弹出FotaTool安装完成界面，如图6所示，单击“Finish”按钮退出安装。

    图 6 FotaTool安装完成界面

    **图 6** FotaTool安装完成界面

升级包制作前确认

执行升级包制作前，请确认以下条件：

  • 当前在 UE 上必须有可正常运行的固件程序，才能应用 FOTA 升级包进行升级。
  • 旧固件包与 UE 当前运行的固件程序一致，新固件包是目标版本；两个输入文件均为 .fwpkg 格式。
  • 固件编译、目标选择和固件包获取请参见开发环境快速入门，建议优先使用一站式 CLI 开发环境。
  • FOTA 升级包基于当前运行的固件和目标固件通过差分算法生成；多个 UE 当前运行的固件版本不同时，需要分别使用与各自当前版本对应的旧固件包制作升级包。
  • 选择的签名方式与 UE 当前固件中镜像的签名方式一致。
  • 通过串口验证时，UE 当前固件支持通过 AT 命令接收 FOTA 升级包。
  • 涉及文件和目录路径的操作不支持中文路径，相关处理见路径和权限问题。
  • 用于串口近端升级的升级包不能超过设备支持的最大规格：2M Flash 为 350KB，4M Flash 为 1200KB；超限后的处理方法见串口近端升级失败。

签名密钥准备

  • FotaTool工具签名所用的签名配置文件和密钥文件存放在FotaTool工具的安装目录下。例如：“C:\Program Files (x86)\FotaTool\CASignTool_4GCat1\”。
  • 签名配置文件为：acpu_3rd_sign_ecc.cfg，对应ECC签名。用户可以修改这个文件，但文件名不允许修改。
  • FotaTool工具安装后默认没有包含签名密钥文件，需要用户自行添加。签名密钥文件采用pem格式。
  • 用户生成签名密钥文件后，需要拷贝至FotaTool工具的安装目录下（例如：“C:\Program Files (x86)\FotaTool\CASignTool_4GCat1\”），并修改对应算法的cfg文件，在cfg文件中指定签名密钥文件的路径和文件名。（cfg文件中相对路径的“./”是指“FotaTool.exe”的当前路径，工具中自带的cfg文件中的路径文件是示例，具体路径和文件名称需要根据安装后的路径和生成的文件名来确定。）
  • FOTA升级包签名使用的密钥为了防止泄漏，强烈建议只有相关安全专员能访问使用。

快速操作

生成升级包

  1. 启动 FotaTool，分别选择与 UE 当前版本一致的旧固件包和目标版本的新固件包。
  2. 选择与 UE 当前固件一致的签名方式，并设置升级包输出路径和文件名。
  3. 单击“Create FOTA patch”生成升级包。
  4. 按升级包生成结果检查日志和输出文件。

完整界面操作见图形界面生成升级包，命令行调用见命令行生成升级包。

通过串口验证升级包

  1. 选择 UE 的 AT 串口、匹配的波特率和数据块大小，并选择已生成的升级包。
  2. 单击“Send FOTA patch”发送升级包，或使用命令行串口近端升级。
  3. 日志出现“Apply Over”仅表示 UE 已接收完整升级包；继续等待 UE 完成校验、差分更新和重启。
  4. 按串口近端升级结果确认升级结果和新固件版本号。

图形/命令行

界面说明

首次运行FotaTool应用程序，打开后的工具界面如图1所示。成功创建或测试FOTA升级包文件后，用户选择的文件路径会自动保存。即下次打开时，文件路径依然为上次选择的路径。

图 1 FotaTool界面示意图

**图 1** FotaTool界面示意图

表 1 FotaTool界面说明

区域

说明

1

Option：选择芯片类型，更换工具对应的版本并在版本号后面显示。

2

选择old fwpkg文件，并在加载后显示其对应路径及解析文件列表。

3

选择new fwpkg文件，并在加载后显示其对应路径及解析文件列表。

4

日志信息显示（包括生成升级包过程及近端升级过程中的日志信息）。

5

签名方式选择（ecc/none）。

6

是否执行flashboot_otp差分制作。

7

是否执行优化算法，默认不勾选。（勾选后制作差分包时长会增加）

8

选择升级包文件的生成路径和文件名。如果此文件已存在，则在生成升级包文件时将覆盖原文件。

9

生成升级包文件。

10

选择近端升级所需连接的串口端口号。

11

连接串口所需的波特率。

12

选择每次发送的数据块的大小。

13

升级文件存储位置。

0：直接存储在flash中，目前不支持；

1：存储在文件系统中。

14

关闭串口。

15

发送升级包文件，开始近端升级。

16

清空日志栏。

图形界面生成升级包

选择新旧两个固件包

启动FotaTool工具，如图1所示。单击左侧“...”按钮，打开文件加载对话框，选择需要升级的源固件包；同样单击右侧“...”按钮，选择目标固件包。

固件包都是“.fwpkg”格式的文件，FotaTool会对这两个固件包通过差分算法生成升级包文件。

图 1 选择固件包

**图 1** 选择固件包

如图2所示，固件包文件加载后，会显示固件包内包含的镜像文件列表。如果没有显示镜像文件列表或者出现错误信息，请检查固件包文件是否正确。

图 2 固件信息

**图 2** 固件信息

说明： Hi2131采用差分升级。因此生成升级包所用的旧固件包必须与当前在UE上运行的固件程序一致才能使用生成的升级包进行升级。

选择签名方式

如图1所示，用户需要选择签名方式（ECC/none）。可选项包括ECC、none，分别表示采用ECC算法签名和不签名。

图 1 界面设置

**图 1** 界面设置

说明： 用户在此选择的签名方式必须与当前在UE上运行的固件中镜像的签名方式一致。

生成升级包

如图1所示，选择FOTA升级包文件的路径和名称。

图 1 选择升级包文件

**图 1** 选择升级包文件

单击启用状态的“Create FOTA patch”按钮，将开始生成升级包文件。

图形界面串口近端升级

成功生成FOTA升级包之后，用户可以通过串口，将FOTA升级包发送到UE并完成FOTA近端升级，此操作可验证生成的差分包是否正确。

如图1所示，用户需要选择如下参数：

  • 与UE连接的串口端口号（FOTA近端升级通过AT串口实现）。
  • 需要使用的波特率：115200是常见的默认值，UE可能支持不同的波特率，用户需要根据实际情况配置，配置UART/LP_UART使用的波特率保持一致即可。
  • 发送升级包时使用的数据块大小（每一次发送的分包大小，单位：Byte，支持的数值为：32、64、128、256、512）。

图 1 参数选择

**图 1** 参数选择

如果升级包文件存在，且选择了正确的串口号，用户可通过单击“Send FOTA patch ”按钮，启动FOTA近端（串口）升级。

如图2所示，界面下方显示升级进度。

图 2 升级进度

**图 2** 升级进度

命令行生成升级包

FOTA工具支持命令行方式调用生成升级包文件。步骤如下：

  1. 在FotaTool.exe的路径下打开命令行窗口。

  2. 输入参数，然后回车开始执行。示例如下，具体参数如表1所示。

    示例：

    FotaTool.exe 1 1 0 D:\file\v1.fwpkg D:\file\v2.fwpkg D:\file\v1_v2.bin 4GCat1 -console

    或者

    FotaTool.exe 1 1 0 D:\file\v1.fwpkg D:\file\v2.fwpkg D:\file\v1_v2.bin 4GCat1

各位置参数的含义和取值见升级包生成命令参数。

命令行串口近端升级

FOTA工具支持命令行方式通过串口，将FOTA升级包发送到UE并完成FOTA近端升级，此操作可验证生成的差分包是否正确。步骤如下：

  1. 在FotaTool.exe的路径下打开命令行窗口。

  2. 输入参数，然后回车开始执行。示例如下，具体参数如表1所示。

    示例：

    FotaTool.exe 5 9600 512 D:\file\v1_v2.bin -console

    或者

    FotaTool.exe 5 9600 512 D:\file\v1_v2.bin

各位置参数的含义和取值见串口近端升级命令参数。

结果校验

升级包生成结果

升级包文件生成成功后，在信息栏中会生成如图1所示的打印信息。

图 1 升级包文件生成成功示意图

**图 1** 升级包文件生成成功示意图

命令行方式的执行结果如图2所示。

图 2 命令行生成升级包

**图 2** 命令行生成升级包

串口近端升级结果

当升级包全部发送完成后，日志信息中会出现“Apply Over”，但这并不代表FOTA升级包升级成功，而是代表UE已经接收到FOTA升级包。

随后，UE会重启，并开始对FOTA升级包进行验证以及通过差分算法对固件进行更新的操作。完成后，UE会再次重启，FotaTool会自动发送AT命令来查询升级结果和新固件版本号，并在日志信息栏显示。

说明： UE收到升级包，并开始验证和更新操作后，需要一段时间用来完成整个固件的更新，更新过程中不受任何AT命令响应（时间大概1～2分钟左右，时间长短与升级包大小有关）。

命令行串口近端升级的执行结果如图1所示。

图 1 升级完成

**图 1** 升级完成

结果判定

  • 生成升级包时，信息栏应显示升级包文件生成成功的信息，并在指定路径得到升级包文件。
  • 串口发送阶段出现“Apply Over”只表示升级包接收完成，不表示固件已经升级成功。
  • UE 完成升级后会再次重启；FotaTool 随后查询升级结果和新固件版本号，并在日志信息栏显示。以该查询结果和版本号作为近端升级结果的最终判断依据。

参数

FotaToolCfg.ini

打开安装路径下的配置文件“FotaToolCfg.ini”，文件内容如下：

[filePath]
IsCustomMode=1
IsCsType=1
IsCheckACore=1
[fotaHeader]
MSID=0x00000000
MSID_Mask=0x00000000

上述配置项的具体含义如表1所示。

表 1 配置项说明

配置项

默认值

说明

IsCustomMode

1

工具使用模式（用户模式和研发模式）。用户无需修改，保持默认值即可。

IsCsType

1

-

IsCheckACore

1

A核文件系统分区大小做比较。

0：不做比较；

1：做比较。

其余值会默认为1，做比较。

MSID

0x00000000

MSID（Market Segment ID，市场区域ID）与MSID_Mask同时起作用，MSID（升级文件里）&MSID_Mask的值必须与应用核镜像中的MSID（OTP）&MSID_Mask的值相同。

MSID_Mask

0x00000000

市场区域ID掩码。MSID与MSID_Mask同时起作用，MSID（升级文件里）&MSID_Mask的值必须与应用核镜像中的MSID（OTP）&MSID_Mask的值相同。

说明： 用户修改配置文件后，需要重启FotaTool才能生效。

图形界面关键参数与限制

图形界面各区域的位置和用途见界面说明。配置时重点确认：

  • 签名方式支持 ecc 和 none，并应与 UE 当前固件一致。
  • flashboot_otp 差分制作和优化算法可分别启用；优化算法默认不勾选，启用后差分包制作时间会增加。
  • 输出文件已存在时，生成操作会覆盖原文件。
  • 串口近端升级需要配置串口号、波特率、数据块大小和升级文件存储位置；存储位置 0 当前不支持，1 表示存储在文件系统中。

升级包生成命令参数

表 1 命令行参数说明

参数位置

参数格式

参数说明

1

FotaTool.exe

工具的执行文件的相对路径或者绝对路径。

2

1

选择的签名方式，默认值为1。

0：ecc；

1：none。

3

1

是否执行flashboot_otp差分制作，默认值为1。

0：不执行；

1：执行。

4

0

是否执行优化算法，默认值为0。

0：不执行；

1：执行。

5

v1.fwpkg

制作升级包的旧镜像文件（*.fwpkg）的相对路径或者绝对路径。

6

v2.fwpkg

制作升级包的新镜像文件（*.fwpkg）的相对路径或者绝对路径。

7

v1_v2.bin

生成的升级包（*.bin）的相对路径或者绝对路径。

8

4GCat1

工具版本的选择。

9

-console （可选参数）

使用标准输入输出，为重定向做准备。

串口近端升级命令参数

表 1 命令行参数说明

参数位置

参数格式

参数说明

1

FotaTool.exe

工具的执行文件的相对路径或者绝对路径。

2

5

与UE连接的串口端口号（FOTA近端升级通过AT串口实现）。

3

9600

需要使用的波特率：9600是常见的默认值，UE可能支持不同的波特率，用户需要根据实际情况配置，配置UART/LP_UART使用的波特率保持一致即可。

4

512

发送升级包时使用的数据块大小（每一次发送的分包大小，单位：Byte，支持的数值为：32、64、128、256、512）。

5

D:\file\v1_v2.bin

升级包文件的绝对路径或者相对路径。

6

-console （可选参数）

使用标准输入输出，为重定向做准备。

问题处理

路径和权限问题

  • 涉及路径的操作不支持中文路径。
  • FotaTool 建议安装在非 C 盘；安装在 C 盘时，中间文件可能因权限不足而无法访问。系统只有 C 盘时，请以管理员权限运行。

固件包、配置和签名检查

  • 固件包加载后未显示镜像文件列表或出现错误信息时，检查 .fwpkg 文件是否正确。
  • 旧固件包必须与 UE 当前运行的固件一致；当前版本不同的 UE 需要分别制作升级包。
  • 签名方式必须与 UE 当前固件中镜像的签名方式一致。
  • 修改 FotaToolCfg.ini 后需要重启 FotaTool，配置才会生效。

串口近端升级失败

如果升级过程中报告错误，则可能的原因和应对措施如表1所示。

表 1 错误原因和应对措施

可能原因

应对措施

串口端口选择错误，未选择AT使用的端口。

选择正确的串口端口。

串口端口被输入AT命令的串口工具占用。

关闭其他串口工具对该端口的占用。

UE中当前的固件程序不支持通过AT命令接收FOTA升级包。

使用空中升级的方式升级。

UE要求的数据发送速率与FotaTool设置的发送速率不匹配。

使用与UE匹配的AT命令端口速率。

升级包的大小超过可支持的最大规格，为350KB（2M Flash) 或 1200KB（4M Flash）。

尽量减小升级包大小。可通过以下两种方式进行：

  • 将多个特性的更新分成两次升级，减少每次升级修改的代码量。
  • 如果此次升级包含多个核镜像的升级，考虑分多次升级进行。例如先升级协议核，再升级应用核。这种情况需要保证不同核之间的修改没有相互依赖，保证单次升级后UE正常运行，不影响后续的升级功能。

说明： 升级后的固件必须能够正常运行，才能再次继续升级。因此强烈建议用户在进行UE的固件升级之前，进行彻底的测试和验证，确保升级后UE的行为符合预期。