OTA UPGRADE

version 1.0

1. Overview¶

This article introduces the process of packaging, unpacking and upgrading in the OTA upgrade of IPC and NVR platforms. Support partition packaging/upgrade, individual file upgrade; support differential upgrade, batch packaging of new and old folders comparison.

For back-end server maintenance, terminal downloading and management of the upgrade package, please refer to the service of other vendors.

2. Partition Packaging¶

2.1. Package Tool¶

The packaging tool only generates the required file headers based on the files currently to be upgraded.

The directory where the bin of the packaging tool is located:

project/image/makefiletools/bin/otapack

Introduction to the command parameters of the otapack tool:

-c --create:

Create an empty upgrade package file header. When it creates the file header, you can use -b or -e to add a script to start or end the upgrade.

-b --begin-script:

Specify a file on the server for the script to be executed before the board is upgraded.

-e --end-scrip:

Specify a file on the server for the script to be executed after the board is upgraded.

-a --append:

Add new header information to the created upgrade package, in which the following parameters must be used to inform the related information of the upgrade.

-s --src-file:

The path of the source file to be updated.

-d --dst-file:

The path of the target file or partition node to be updated.

-t --dst-file-size:

The size of the target file or partition to be updated, unit: byte, expressed in hexadecimal/decimal.

-m --file-mode:

The mode of the file you want to update.

-o --diff-old:

Old files and folders for differentially upgraded.

-n --diff-new:

New file and folder directory for differential upgrade.

--block-update：

The packaged data is a block upgrade of bare data.

--ubi-update：

The packaged data is a volume upgrade of the UBI file system.

--file-update：

The packaged data is a file upgrade.

--file-add:

Add a file with packed data.

--file-delete:

Only update the packaged data header and delete the target file on the board.

--file-update-diff：

The packaged data is the diff data of the differential upgrade.

--dir-update:

Scan the contents in the old and new folders, compare the differences, the increased, and decreased parts, and then package them in batches.

--dir-update-diff:

Scan the contents in the old and new folders, compare the differences, the increased, and decreased parts, and then package them in batches. Pack the difference data of the difference file.

--help：

Print help info.

--debug：

Turn on debugging information.

otaunpack tool command parameter introduction:

-x: Unpack and upgrade compressed files

-r: Unpack and upgrade uncompressed files

-t: Specify a writable folder path for differential upgrade.

2.2. Example Of Packaging Process¶

Create an empty header
```
otapack -c SStarOta.bin
```
If necessary, you can use the -b/-e command to add a script
```
otapack -c SStarOta.bin -b start.sh -e end.sh
```

Update the header data according to the files that need to be packaged

otapack -a SStarOta.bin -s ./images/kernel -d /dev/mtdblock8 -t 0x500000 --block-update

Repeat step 3 to pack all the files
Compress the upgrade package
```
gzip SStarOta.bin
```

2.3. Pack In ALKAID¶

The OTA packaging process has been integrated into the Makefile.

When the program is compiled and packaged, enter the command under the project:

make image-ota

There is an interactive interface, specify the script path to be executed on the board, you can choose whether to add commands:

Start scripts:

End scripts:

List the data when packing the partition:

Make ipl ?(yes/no)

After selection, SStarOta.bin.gz will be generated under project/image/output/images/

The partition will be configured in the partition config file for packaging.

For example：

There are variables in the file spinand.ubifs.p2.partition.config: OTA_IMAGE_LIST, after which add the name of the partition to be packaged, and add xxx$(OTABLK) to the configuration of the partition to configure the target node path that needs to be upgraded.

Only when OTA_IMAGE_LIST adds the partition name, make image-ota will ask whether the partition should be upgraded with ota.

All the logic of the partition packaging script is implemented in image/ota.mk, please refer to it at your own convenience.

2.4. RAW DATA Packaging Without File System¶

The partition upgrade steps are mostly similar. Fill in the corresponding mtdblock with the files that need to be upgraded. The packaging process is the same. The difference is that in the RAW DATA partition packaging, the creation and data filling of the upgrade header must be realized by itself. Here is an example of spinand IPL partition packaging:

define makeota
@read -p "Make $(1) ?(yes/no)" select;  \
if [ "$${select}" == "yes" -o "$${select}" == "y" ]; then   \
    $(foreach n,$(3),$(PROJ_ROOT)/image/makefiletools/bin/otabinheader -s $(2) -d $(n) -t $(4) -p $(5) -a $(IMAGEDIR)/SStarOta.bin;cat $(2) >> $(IMAGEDIR)/SStarOta.bin;) \
fi;
endef

ipl_spinand_mkota_:
    $(call makeota,$(patsubst %_spinand_mkota_,%,$@),$(IMAGEDIR)/ipl_s.bin,$($(patsubst %_spinand_mkota_,%,$@)$(OTABLK)),$($(patsubst %_spinand_mkota_,%,$@)$(PATSIZE)),0)

2.5. ubifs/ squashfs/ jffs2 Packaging¶

If these partitions are newly created and added to OTA_IMAGE_LIST, there is no need for special processing in ota.mk, and the partition upgrade files will be processed uniformly.

The partition upgrade method of UBIFS is different from the other two formats, so when packaging UBIFS, please use --ubi-update.

2.6. Individual File Packaging¶

The option for individual file packaging is --file-update. Currently, there is no packaging for file update in ALKAID, so you need to add it manually.

2.7. Differential Data Packaging¶

The option for differential data packaging of individual files is --file-update-diff. In addition to ordinary files, raw images such as kernel and uboot, and mirror files of read-only file systems are also applicable, but writable file systems are not.

Differential upgrade needs to rely on other open source bsdiff and bspatch.

The bsdiff tool is used when packaging, and bspatch is used on the board. The bsdiff tool is used when packaging, and bspatch is used on the board. The source code of the two is in project/tools/bsdiff

Compilation:

tar -vxf bzip2-1.0.6.tar.gz

cd bzip2-1.0.6

make

After compilation, you can see the execution files bsdiff and bspatch in the current directory. It is used on PC by default, please change the Makefile to use bspatch on the compiled board. The compiled bsdiff should be placed in the /usr/bin/ path of PC, or the location specified by $PATH. The bspatch on the board should also be placed in the corresponding position.

2.8. Scan New And Old Folders And Pack In Batches¶

There are two types of folder scanning:

Force to update for the scanned files with discrepancies.
Differential upgrade for the scanned files with discrepancies.

--dir-update

For example：

otapack -a ./test-diff.bin -o ./old/ -n ./new/ -d /config --dir-update

--dir-update-diff

For example：

otapack -a ./test-diff.bin -o ./old/ -n ./new/ -d /config --dir-update-diff

3. Partition Upgrade¶

3.1. Upgrade process¶

3.2. Note Before Partition Upgrade¶

Please make sure umount is successful before partition upgrade. umount can be operated in the start scripts. If you need to update a file, make sure that the file is in a readable and writable file system and has write permissions.

Please contact FAE to obtain the otaupack tool.

3.3. Compressed Upgrade Package Update¶

otaupack -x SStarOta.bin.gz

3.4. Uncompressed Upgrade Package Update¶

otaupack -r SStarOta.bin

3.5. Upgrade UI Display¶

When upgrading, you can specify a full-screen background image to paste on the framebuffer. The image supports jpg and png. Draw the progress bar in the framebuffer. After version 0.2, otaunpack supports the progress bar and text UI rotation. Set the -s parameter 0/½/3 to support None/90°/180°/270° rotation.

otaunpack -x SStarOta.bin.gz -p upgrade.jpg

3.6. Differential Upgrade¶

If there is differential upgrade data in the compressed package, you need to specify a temporary writable folder.

Command:

otaupack -x SStarOta.bin.gz -t /tmp

3.7. Upgrade Status Acquisition¶

Use the internal variable OTA_STATUS in the END script to get the status of the upgrade.

If OTA_STATUS is 0, the upgrade is successful, otherwise it is -1.

3.8. SPI-NAND Invalid Block Processing¶

In the program packaged and upgraded using the --block-update command, if the mtdblock node is set, it will not process the invalid block. It is recommended to use nor flash for upgrading. If spinand needs to be upgraded and deal with invalid blocks at the same time, please use --block-update to set the character device node of mtd. After version 0.2, the otapack and otaunpack applications can support the use of mtd-utils to handle invalid blocks during the upgrade. Please log in to busybox Open nand_write and flash_eraseall in