SWUpdate Guide

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.

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.

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 big image. All single images are packed together with an additional file (sw-description), that contains meta information about each single image.

Attached the sample of image description file suitable for VAR-SOM-MX6 Yocto update. The image consists of two components: new root file system (also includes kernel) and the user-space script that defines the update process.

software =
{
	version = "0.1.0";

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

		images: (
			{
				filename = "var-image-swupdate-var-som-mx6.ext4.gz";
				device = "/dev/update";
				type = "raw";
				compressed = true;
			}
		);

		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.

Setup and build Yocto

Follow steps 1-3 of the Yocto Build Release page.

Supported image

The following image is provided by Variscite for evaluation purpose:

• 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 - The rootfs is configured as read-only by default

This image recipe works on all backends for X11, DirectFB, Frame Buffer and Wayland.

Supported distros

The following distros can be used:

• fslc-x11: Distro for X11 without wayland. This distro include x11 feature and doesn’ has wayland support.
• fslc-framebuffer: Distro for Framebuffer graphical backend. This distro doesn’t include x11 and wayland features.
• fslc-wayland: Distro for Wayland without X11. This distro include wayland feature but doesn’t has x11 support.
• fslc-xwayland: Distro for Wayland with X11. This distro include both wayland and x11 features.

Note: Also standard Poky distros can be used

GStreamer support

FSL community BSP comes with gstreamer-imx, a set of GStreamer1.0 plugins for i.MX platform, which make use of the i.MX multimedia capabilities.
Some of the multimedia plugins do not work well with X11 and Wayland backends.
To get the most from gstreamer-imx, it is recommended to use fslc-framebufer distro with one of the demo images

Build X11 GUI demo image

$ cd ~/var-fslc-yocto
$ MACHINE=var-som-mx6 DISTRO=fslc-x11 . setup-environment build_x11

Optional steps: local.conf customization

launch bitbake:

$ bitbake var-image-swupdate

NOTE: Some of the blitter-based i.MX GStreamer plugins do not work with X11 and Wayland backends. To get the most of the i.MX GPU/VPU acceleration, use the fslc-framebuffer backend.

local.conf customization

Change the downloads directory

Create a /opt/yocto_downloads directory and set its permissions:

$ sudo mkdir /opt/yocto_downloads
$ sudo chmod 777 /opt/yocto_downloads/

Direct downloads to it, by replacing 'DL_DIR ?= "${BSPDIR}/downloads/"' with 'DL_DIR = "/opt/yocto_downloads/"' in conf/local.conf:

$ sed -i 's/DL_DIR ?= "${BSPDIR}\/downloads/DL_DIR = "\/opt\/yocto_downloads/g' conf/local.conf

Add Eclipse debug and Qt creator support to your images

Append the following to the conf/local.conf file in your Yocto build directory, to add Eclipse debug and Qt creator support to your images:

EXTRA_IMAGE_FEATURES = " \
    debug-tweaks \
    tools-debug \
    eclipse-debug \
    "

IMAGE_INSTALL_append = " \
    tcf-agent \
    openssh-sftp-server \
    "

Use systemd instead of SysV init

Append the following to the conf/local.conf file in your Yocto build directory, to use systemd instead of SysV init in your images:

DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""
IMX_DEFAULT_DISTRO_FEATURES_append = " systemd"

Create a read-only root file system

Append the following to the conf/local.conf file in your Yocto build directory, to create a read-only rootfs:

EXTRA_IMAGE_FEATURES += "read-only-rootfs"

Build Results

The resulted images are located in tmp/deploy/images/var-som-mx6.

Image Name	How to use
fsl-image-gui-var-som-mx6.sdcard	This image is for SD card boot. It can be flashed as-is on an SD card that can then be used to boot your system, according to the relevant startup-guide of your product (usually requires to press the boot select button, or toggle a DIP switch). For detailed information refer to the Create a bootable SD card section below.
fsl-image-gui-var-som-mx6.tar.bz2	Tarball with rootfs files. Can be used to create an NFS root file system on the host. See the Yocto Setup TFTP/NFS section for more info. Also used to create our extended SD card. See the Create a bootable SD card section below.
fsl-image-gui-var-som-mx6.ubi	A complete UBI image containing a UBIFS volume, for writing to NAND flash.
uImage	Linux kernel image, same binary for SD card or NAND flash.
u-boot.img-nand	U-Boot built for NAND flash.
u-boot.img-sd	U-Boot built for SD card boot or eMMC boot.
SPL-sd	SPL built for SD card boot or eMMC boot.
SPL-nand	SPL built for NAND flash.

Image Name	Description
fsl-image-gui-var-som-mx6.sdcard	This image is for SD card boot. It can be flashed as-is on an SD card that can then be used to boot your system, according to the relevant startup-guide of your product (usually requires to press the boot select button, or toggle a DIP switch). For detailed information refer to the Create a bootable SD card section below.
fsl-image-gui-var-som-mx6.tar.gz	Tarball with rootfs files. Can be used to create an NFS root file system on the host. See the Yocto Setup TFTP/NFS section for more info. Also used to create our extended SD card. See the Create a bootable SD card section below.
fsl-image-gui-var-som-mx6_128kbpeb.ubi	A complete UBI image containing a UBIFS volume, for writing to NAND flash with 128KiB PEB.
fsl-image-gui-var-som-mx6_256kbpeb.ubi	A complete UBI image containing a UBIFS volume, for writing to NAND flash with 256KiB PEB.
uImage	Linux kernel image, same binary for SD card/eMMC or NAND flash.
SPL-sd	SPL built for SD card boot or eMMC boot.
SPL-nand	SPL built for NAND flash.
u-boot.img-sd	U-Boot built for SD card boot or eMMC boot.
u-boot.img-nand	U-Boot built for NAND flash.

Device Tree Name	SOM type	Carrier Board type	LCD Type	Evaluation Kit name
uImage-imx6q-var-som-cap.dtb	VAR-SOM-MX6_V2 (Quad / Dual)	VAR-MX6CustomBoard	Capacitive touch	VAR-DVK-MX6_V2-PRO VAR-STK-MX6_V2
uImage-imx6q-var-som-res.dtb	VAR-SOM-MX6_V2 (Quad / Dual)	VAR-MX6CustomBoard	Resistive touch	VAR-DVK-MX6_V2-PRO VAR-STK-MX6_V2
uImage-imx6q-var-som-vsc.dtb	VAR-SOM-MX6_V2 (Quad / Dual)	VAR-SOLOCustomBoard	Capacitive LVDS touch	N/A
uImage-imx6dl-var-som-cap.dtb	VAR-SOM-MX6_V2 (DualLite / Solo)	VAR-MX6CustomBoard	Capacitive touch	N/A
uImage-imx6dl-var-som-res.dtb	VAR-SOM-MX6_V2 (DualLite / Solo)	VAR-MX6CustomBoard	Resistive touch	N/A
uImage-imx6dl-var-som-vsc.dtb	VAR-SOM-MX6_V2 (DualLite / Solo)	VAR-SOLOCustomBoard	Capacitive LVDS touch	N/A
uImage-imx6qp-var-som-cap.dtb	VAR-SOM-MX6_V2 (QuadPlus / DualPlus)	VAR-MX6CustomBoard	Capacitive touch	N/A
uImage-imx6qp-var-som-res.dtb	VAR-SOM-MX6_V2 (QuadPlus / DualPlus)	VAR-MX6CustomBoard	Resistive touch	N/A
uImage-imx6qp-var-som-vsc.dtb	VAR-SOM-MX6_V2 (QuadPlus / DualPlus)	VAR-SOLOCustomBoard	Capacitive LVDS touch	N/A
uImage-imx6dl-var-som-solo-cap.dtb	VAR-SOM-SOLO / VAR-SOM-DUAL	VAR-MX6CustomBoard	Capacitive touch	N/A
uImage-imx6dl-var-som-solo-res.dtb	VAR-SOM-SOLO / VAR-SOM-DUAL	VAR-MX6CustomBoard	Resistive touch	N/A
uImage-imx6dl-var-som-solo-vsc.dtb	VAR-SOM-SOLO / VAR-SOM-DUAL	VAR-SOLOCustomBoard	Capacitive LVDS touch	VAR-DVK-SOLO/DUAL VAR-STK-SOLO/DUAL
uImage-imx6q-var-dart.dtb	DART-MX6	VAR-DT6CustomBoard	Capacitive LVDS touch	VAR-DVK-DT6 VAR-STK-DT6