SWUpdate Guide: Difference between revisions

From Variscite Wiki
Line 51: Line 51:


== Update image format ==
== Update image format ==
The main concept is that the manufacturer delivers a single .swu image. The .swu image may contain different images and files, and a mandatory sw-description file which contains meta information about the image.<br>
The main concept is that the manufacturer delivers a single .swu image.<br>
The .swu image may contain multiple images and files. In addition, it must contain a sw-description file with meta information about the image.<br>
[[File:Image_format.png]]
[[File:Image_format.png]]



Revision as of 13:36, 28 September 2017

SWUpdate

SWUpdate Introduction

One of the challenges in nowadays embedded systems is field update of the embedded software (e.g. Linux) in the safe and efficient way whether via OTA or removable device. This article presents SWUpdate approach for the embedded system software update that supports local and remote updates, multiple update strategies and it can be well integrated in the Yocto build system by adding the meta-swupdate layer. The SWUpdater is licensed under GPL Version 2.0+ and was developed by Stefano Babic from U-Boot community. The most notable feature are:

  • Install on embedded media (eMMC, NAND, SD)
  • Allow delivery single image for multiple devices
  • Multiple interfaces for getting software
    • local storage
    • integrated web server
    • integrated REST client connector to hawkBit
    • remote server download
  • Software delivered as images, gzipped tarball, etc.
  • Allow custom handlers for installing FPGA firmware, microcontroller firmware via custom protocols.
  • Power-Off safe

There are two typical update strategies supported by SWUpdate

  • Double copy with fall-back
  • Single copy – running as standalone image

Double copy with fall-back

If there is enough space on the storage to save two copies of the whole software, it is possible to guarantee that there is always a working copy even if the software update is interrupted or a power off occurs.

Each copy must contain the kernel, the root file system, and each further component that can be updated. It is required a mechanism to identify which version is running.

SWUpdate should be inserted in the application software, and the application software will trigger it when an update is required. The duty of SWUpdate is to update the stand-by copy, leaving the running copy of the software untouched.

A synergy with the boot loader is often necessary, because the boot loader must decide which copy should be started. Again, it must be possible to switch between the two copies. After a reboot, the boot loader decides which copy should run.
Double copy layout.png
Summary:

  • Requires twice as much space than single copy
  • Guarantees there’s always a working copy!
  • Bootloader is in charge of booting proper image

Single copy – running as standalone image

The software upgrade application consists of kernel (maybe reduced dropping not required drivers) and a small root file system, with the application and its libraries. The whole size is much less than a single copy of the system software (2.5MB-8 MB).The system can be put in “upgrade” mode, simply signaling to the boot loader that the upgrading software must be started (either by using boot loader environment or GPIO).

The boot loader starts “SWUpdate”, booting the SWUpdate kernel and the initrd image as root file system. Because it runs in RAM, it is possible to upgrade the whole storage. Differently as in the double-copy strategy, the systems must reboot to put itself in update mode.

This concept consumes less space in storage as having two copies, but it does not guarantee a fall-back without updating again the software. However, it can be guaranteed that the system goes automatically in upgrade mode when the productivity software is not found or corrupted, as well as when the upgrade process is interrupted for some reason.
Single copy layout.png
Summary:

  • Stand alone image consists of kernel / dt + initrd
  • Much smaller than entire system
  • Bootloader in charge of loading standalone image
  • System must reboot to enter update process

Update image format

The main concept is that the manufacturer delivers a single .swu image.
The .swu image may contain multiple images and files. In addition, it must contain a sw-description file with meta information about the image.
Image format.png

The following is a sample sw-description file used by our var-image-swu recipe.
This sample image consists of two components:
- A root file system (including the kernel)
- A bash script that runs before (called with preinst parameter) and after (called with postinst parameter) the installation of the root file system.

software =
{
	version = "0.1.0";

	var-som-mx6 = {
		hardware-compatibility: [ "1.0" ];

		files: (
			{
				filename = "var-image-swupdate-var-som-mx6.tar.gz";
				type = "archive";
				compressed = true;
				device = "/dev/update";
				filesystem = "ext4";
				path = "/";
			}
		);

		scripts: (
			{
				filename = "update.sh";
				type = "shellscript";
			}
		);
	};
}

Update methods

  • You can always schedule update from removable storage by running
swupdate -i <file name.swu> 

By editing auto-mount sequence you can trigger the update process each time the removable device is inserted.

  • OTA update is available via http protocol .

It is possible to configure software update agent to include embedded web-server (CONFIG_MONGOOSE). To allow the OTA update via web-server the following command should be executed:

swpdate -w "-document_root ./www"

Then you can then connect to the target with:

http://<target_ip>:8080

And upload the .swu file.
Swupdate-www.png

Yocto Integration

Variscite provides an example only for the double-copy approach, where the rootfs is on eMMC.

Double-copy approach

Before you begin, get familiar with Varicite guide for building Yocto Build Release. The following will focus on customizing Variscite evaluation image to support SWUpdate functionality.

The most notable changes are:

  • var-image-swupdate: This image is based on fsl-image-gui, the default Variscite demo image with a GUI without any QT content, with the following differences:
    • swupdate and swupdate-www pacakages are included
    • The kernel image and device trees are added to the /boot directory of the rootfs (by including the kernel-image and kernel-devicetree packages)
    • The rootfs is created only as a tar.gz archive (IMAGE_FSTYPES = "tar.gz")

See the recommended internal storage layout for double-copy approach:
Swupdate layout.png

Create SWUpdate-ready Image

$ cd ~/var-fslc-yocto
$ MACHINE=var-som-mx6 DISTRO=fslc-x11 . setup-environment build_x11
$ bitbake fsl-image-gui      (for the recovery SD card)
$ bitbake var-image-swupdate (for the rootfs to be installed on the eMMC)
  • Create SWUpdater-ready SD card
$ sudo MACHINE=var-som-mx6 ../sources/meta-variscite-fslc/scripts/var_mk_yocto_sdcard/var-create-yocto-sdcard.sh -r tmp/deploy/images/var-som-mx6/var-image-swupdate-var-som-mx6 /dev/sdX
(Replace /dev/sdX with your actual device)
var-create-yocto-sdcard.sh script creates the double-copy compatible layout as shown above
  • Boot the board using the created SD card. See more info here.
  • Install demo image to the local storage. Either use the installation icons on the desktop, or use the install_yocto.sh script manually, with the "-u" parameter.

Generate Field Update file

  • Make your changes in ~/var-fslc-yocto
  • Edit the sw-description file
  • Generate .swu file:
$ bitbake var-image-swu

Test SWUpdate

  • Get the target's IP address using ifconfig
  • Open a web browser on the host and connect to the swupdate web server on the target by entering the following in the address bar:
TARGETS_IP_ADDRESS:8080
  • On the web page, click "Browse..." and open the .swu image at tmp/deploy/images/var-som-mx6/var-image-swu*