FOTA-AB升级手册
1. 概述
本文介绍FOTA AB升级相关的OTA镜像生成以及如何在OCC上进行操作的一些使用说明。
2. OTA镜像制作
2.1 初始固件
初始固件是烧录到板子上的固件，经过编译之后会在solutions/generated目录下生成images.zip文件。可以通过JTAG或者其他方式烧录到板子上。
2.2 OTA镜像打包
OTA升级通常是因为软件有更新了才会进行升级，这里我们可以通过简单添加一些打印的代码来制作新的固件版本。然后再重新对工程进行make，make完成之后会在相同的路径生成images.zip文件。我们把images.zip文件进行解压，例如会有如下文件：
-rw-r--r-- 1 linsht users 61812 Dec 31 1979 boot.bin
-rw-r--r-- 1 linsht users 8192 Dec 31 1979 bootinfo.bin
-rw-r--r-- 1 linsht users 24068 Dec 31 1979 bootmini.bin
-rw-r--r-- 1 linsht users 1336 Dec 31 1979 config.yaml
-rw-r--r-- 1 linsht users 8192 Dec 31 1979 imtb
-rw-r--r-- 1 linsht users 1581 Dec 31 1979 partition.toml
-rw-r--r-- 1 linsht users 1581 Dec 31 1979 partition_8M.toml
-rw-r--r-- 1 linsht users 673580 Dec 31 1979 prim
其中的prim文件便是需要升级的分区镜像，需要通过product工具进行打包(product工具可以通过安装yoctools工具获得。如何安装yoctools，请参考这里)。可以使用以下命令生成fota.raw，再上传至OCC。
2.2.1 打包单个分区镜像
mtb_version: 4
chip: bl606
flash:
base_address: 0 # 存储基地址，比如FLASH的基地址
run_base_address: 0x54000000 # base address of Storage
sector: 4096 # Bytes
size: 0x800000 # $(sector count) * sector
partitions:
- { name: boot, address: 0x011000, size: 0x020000, file: boot.bin }
- { name: imtb, address: 0x031000, size: 0x002000 }
- { name: prima, address: 0x034000, load_addr: 0x54020000, size: 0x360000, file: prim, verify: true }
- { name: primb, address: 0x394000, load_addr: 0x54020000, size: 0x360000, verify: true }
- { name: kv, address: 0x6F4000, size: 0x002000 }
- { name: envab, address: 0x7F8000, size: 0x003000 } # for ab switch, size must be 2*sector+1024B at least
非安全方案，不需要使用私钥进行签名：
product pack -i prim -o fota.raw -hv 2
安全方案，需要增加签名，可以使用以下命令：
product pack -i prim -o fota.raw -hv 2 -spk keystore/key.pem -dt SHA1 -st RSA1024
以上命令里面的prim参数对应的是config.yaml中的分区名字,但是要把分区名字最后的a/b字符去掉，比如这里的AB分区分别是prima/primb，所以使用product生成fota.raw的时候使用prim这个名字。
2.2.2 打包多个分区镜像
mtb_version: 4
chip: bl606
flash:
base_address: 0 # 存储基地址，比如FLASH的基地址
run_base_address: 0x54000000 # base address of Storage
sector: 4096 # Bytes
size: 0x800000 # $(sector count) * sector
partitions:
- { name: boot, address: 0x011000, size: 0x020000, file: boot.bin }
- { name: imtb, address: 0x031000, size: 0x002000 }
- { name: prima, address: 0x034000, load_addr: 0x54020000, size: 0x360000, file: prim, verify: true }
- { name: primb, address: 0x394000, load_addr: 0x54020000, size: 0x360000, verify: true }
- { name: firma, address: 0x6F4000, size: 0x002000, verify: true }
- { name: firmb, address: 0x6F6000, size: 0x002000, verify: true }
- { name: kv, address: 0x6F8000, size: 0x002000 }
- { name: envab, address: 0x7F8000, size: 0x003000 } # for ab switch, size must be 2*sector+1024B at least
非安全方案，不需要使用私钥进行签名：
product pack -i prim firm -o fota.raw -hv 2
安全方案，需要增加签名，可以使用以下命令：
product pack -i prim firm -o fota.raw -hv 2 -spk keystore/key.pem -dt SHA1 -st RSA1024
以上命令里面的prim和firm参数对应的是config.yaml中的分区名字,但是要把分区名字最后的a/b字符去掉，比如这里的AB分区分别是prima/primb、firma/firmb，所以使用product生成fota.raw的时候使用prim和firm这个名字。
注意： 输出文件需要以.raw结尾(否则OCC不识别)。每个文件名即为分区名，设备在解析fota.raw文件时将以每个文件名作为分区进行匹配。
2.2.3 keystore文件内容
keystore目录下的公私钥生成请参考以下命令：
RSA公私钥生成
- PEM私钥格式文件
openssl genrsa -out key.pem 1024
- PEM公钥格式文件
openssl rsa -in key.pem -pubout -out pubkey.pem
3. OCC操作
3.1 上传固件
OCC上只需要上传经过本地处理的fota.raw文件。
3.1.1 添加产品
- 在芯片开放社区上创建产品，在控制台->产品服务->添加产品，填写产品信息并提交。
- 提交完成后页面中生成产品列表，在新建产品的右侧点击编辑按钮，可进入产品的详细配置界面。
3.1.2 初始固件的添加及发布
- 点击
编辑，进入产品详细配置界面中，在FOTA->添加固件 。
弹出添加新版本的窗口。
这里的基础版本直接使用第2.2章节生成的fota.raw文件即可。
注意：由于AB升级的方式需要有个初始的版本号，因此规定fota的基础版本的版本号必须设置为1.0.0
- 点击上一步骤提交的待发布固件版本名称，并点击
发布，等待服务器处理十几秒即完成版本发布。
发布成功之后发布状态会改变。
3.1.3 新固件的添加及发布
- 进入产品详细配置界面中，在FOTA->添加固件 ，进入添加升级版本设置。
- 添加新版本页面中填写名称以及版本号、上传第2.2章节生成的
fota.raw文件并提交。
- 点击上一步骤提交的待发布固件名称，并点击
发布，等待服务器处理十几秒即完成版本发布。
发布成功之后发布状态会改变。
3.2 升级设备管理
3.2.1 生成许可证
OCC 平台会对每一个设备颁发一个许可证，用于设备升级，并需把许可证信息配置到设备中。进入产品详细配置界面，点击许可证->申请许可证，填写申请的许可证信息，再点击生成->下载。
页面中点击下载，开始下载许可证数据。解压后，pieces 目录中以 设备ID 为文件名，保存了每个设备的信息。通过文件名获取设备 ID，后续操作会说明。
3.2.2 添加标签
- 标签是用来区分升级的设备组，一个标签可以包含多个设备，版本升级通过选择不同的标签来确定需要升级的设备。点击【添加标签】，为设备添加标签。
- 选择设备对应的 CID 来创建标签并提交。
3.2.3 设置升级策略
- 通过点击升级版本对应操作栏下的升级策略，设置版本之间的升级策略。
- 勾选对应标签并确认
提交即可。
至此，上传固件至 OCC 平台的操作与 OCC 的相关配置操作完成。
4. 设备操作
4.1 配置初始参数
设备烧录初始固件之后，需要配置device_id、model参数才能进行升级。
| 字段 | 说明 |
|---|---|
| device_id | 平头哥CID |
| model | 即3.1.1章节中产品型号中填写的字符串 |
以上参数只需要在第一次配置即可。配置完成之后设备需要重启。如果这些参数都配置正确，那么设备就会检测到新版本的固件，并开始升级。 比如：
kv set device_id cefe313104400000b8a43da523d9a66e
kv set model fota
4.2 回滚机制
如果升级的镜像有问题，无法正常启动，那么会触发回滚机制。也就是说如果当前是在A分区，那么经过OTA升级之后会把新的镜像下载到B分区，设备复位之后，bootloader会进行判断切换至B分区，如果新下载的B分区固件无法启动大于等于5次，那么就会启动回滚机制，重新使用A分区的固件。
5. 参考文档
FOTA全量和差分相关的升级用户手册，请参考《YoC RTOS 实战：FOTA系统升级》。