SWUpdate Guide: Difference between revisions

From Variscite Wiki
No edit summary
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<!-- Set release according to "release" parameter in URL and use PYRO_V1.0_VAR-SOM-MX6 as default
<!-- Set release according to "release" parameter in URL and use PYRO_V1.0_VAR-SOM-MX6 as default
--> {{#vardefine:RELEASE_PARAM|{{#urlget:release}}}} <!--
--> {{INIT_RELEASE_PARAM|RELEASE_PYRO_V1.0_VAR-SOM-MX6}}<!--
--> {{#lst:Yocto_Platform_Customization|{{#var:RELEASE_PARAM|RELEASE_PYRO_V1.0_VAR-SOM-MX6}}}} <!--
--> {{#lst:Yocto_Platform_Customization|{{#var:RELEASE_PARAM}}}} <!--
--> {{#lst:B2QT_Platform_Customization|{{#var:RELEASE_PARAM}}}} <!--
--> {{COMMON_YOCTO_VARS}} <!-- Include common yocto variables
--> {{PageHeader|SWUpdate}} {{DocImage|category1={{#var:HARDWARE_NAME}}|category2=Yocto}} __toc__
--> {{PageHeader|SWUpdate}} {{DocImage|category1={{#var:HARDWARE_NAME}}|category2=Yocto}} __toc__
= SWUpdate Introduction =
= SWUpdate Introduction =


Line 29: Line 32:
This Introduction was taken from the SWUpdate README.md at: [https://github.com/sbabic/swupdate https://github.com/sbabic/swupdate]<br>
This Introduction was taken from the SWUpdate README.md at: [https://github.com/sbabic/swupdate https://github.com/sbabic/swupdate]<br>
<br>
<br>
Example of using the meta-swupdate layer with Variscite i.MX boards is provided in the meta-variscite-fslc layer.<br>
Example of using the meta-swupdate layer with Variscite i.MX boards is provided in the {{#var:META_VARISCITE_SDK}} layer.<br>
This example uses the double-copy approach, using two rootfs partitions on eMMC.<br>
This example uses the double-copy approach, using two rootfs partitions on eMMC.<br>


Line 83: Line 86:
OTA update is available via http protocol:
OTA update is available via http protocol:
It is possible to configure the software update agent to include embedded web-server (CONFIG_MONGOOSE). To start SWUpdate with the embedded web-server:
It is possible to configure the software update agent to include embedded web-server (CONFIG_MONGOOSE). To start SWUpdate with the embedded web-server:
  swpdate -w "--document-root ./www"
  swupdate -w "--document-root ./www"


The default port of the Web-server is 8080. You can then connect to the target with:
The default port of the Web-server is 8080. You can then connect to the target with:
Line 89: Line 92:


And upload the .swu file.<br>
And upload the .swu file.<br>
{{#ifeq: {{#var:YOCTO_NAME}} | Sumo |
{{#ifeq: {{#var:YOCTO_NAME}} | Pyro |
[[File:Swupdate-www_sumo2.png|600px]]
[[File:Swupdate-www.png|600px]]
|
|
{{#ifeq: {{#var:YOCTO_NAME}} | Rocko |
[[File:Swupdate-www.png|600px]]
[[File:Swupdate-www.png|600px]]
}}
|
 
<br>The start page:<br>
[[File:Swupdate-www_sumo2.png|700px]]<br>
And after a successful update:<br>
[[File:Swupdate-www_sumo.png|700px]]
}}}}
<br><br>
To see all of the command line parameters of swupdate:
To see all of the command line parameters of swupdate:
  swupdate -h
  swupdate -h
Line 103: Line 112:
== Recipes ==
== Recipes ==


Before you begin, get familiar with the Varicite {{Varlink2|Yocto Build Release|{{#var:RELEASE_LINK}}}} guide.<br>
Before you begin, get familiar with the Varicite {{Varlink2|{{#var:GUIDE_NAME}} Build Release|{{#var:RELEASE_LINK}}}} guide.<br>
<br>
<br>
Variscite provides the following two image recipes:
Variscite provides the following two image recipes:


* '''var-image-swupdate''' - Based on fsl-image-gui (the default Variscite demo image with a GUI without any QT content) with the following differences:
* '''var-image-swupdate''' - 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
** 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), instead of using a BOOT partition
** The kernel image and device trees are added to the /boot directory of the rootfs (by including the kernel-image and kernel-devicetree packages), instead of using a BOOT partition
Line 148: Line 157:
  }
  }
<br>
<br>
And the following is the aforementioned update.sh bash script: [https://raw.githubusercontent.com/varigit/meta-variscite-fslc/{{#var:YOCTO_BRANCH}}/recipes-support/swupdate/var-image-swu/update.sh update.sh]<br>
And the following is the aforementioned update.sh bash script: [https://raw.githubusercontent.com/varigit/{{#var:META_VARISCITE_REPO}}/{{#var:META_VARISCITE_BRANCH}}/{{#ifexpr: {{#var:YOCTO_VERSION}} > 2.5|dynamic-layers|recipes-support}}/swupdate/var-image-swu/update.sh update.sh]<br>
This script is being used in order to detect the root device and the U-Boot env. type and location (eMMC vs NAND flash) at runtime.<br>
This script is being used in order to detect the root device and the U-Boot env. type and location (eMMC vs NAND flash) at runtime.<br>


== Create a SWUpdate-ready Image ==
== Create a SWUpdate-ready Image ==
* Follow steps 1-3 of the {{Varlink2|Yocto Build Release|{{#var:RELEASE_LINK}}}} page.
* Follow steps 1-3 of the {{Varlink2|{{#var:GUIDE_NAME}} Build Release|{{#var:RELEASE_LINK}}}} page.
* Build a recovery SD card and the var-image-swupdate image as the recovery image
* Build a recovery SD card and the var-image-swupdate image as the recovery image
$ cd {{#var:BUILD_FOLDER}}
{{#lst:Yocto_Platform_Customization|YOCTO_ENV_SETUP_X}}
$ MACHINE={{#var:MACHINE_NAME}} DISTRO={{#var:BUILD_DISTRO}} {{#var:BUILD_SCRIPT}} {{#var:BUILD_FOLDER_X11}}


  $ bitbake fsl-image-gui      (for the recovery SD card)
  $ bitbake fsl-image-gui      (for the recovery SD card)
Line 161: Line 169:


* Create the "SWUpdate recovery SD card"  
* Create the "SWUpdate recovery SD card"  
  $ sudo MACHINE={{#var:MACHINE_NAME}} ../sources/meta-variscite-fslc/scripts/var_mk_yocto_sdcard/var-create-yocto-sdcard.sh -r tmp/deploy/images/{{#var:MACHINE_NAME}}/var-image-swupdate-{{#var:MACHINE_NAME}} /dev/sdX
  $ sudo MACHINE={{#var:MACHINE_NAME}} ../sources/{{#var:META_VARISCITE_SDK}}/scripts/var_mk_yocto_sdcard/var-create-yocto-sdcard.sh -r tmp/deploy/images/{{#var:MACHINE_NAME}}/var-image-swupdate-{{#var:MACHINE_NAME}} /dev/sdX
  (Replace /dev/sdX with your actual device)
  (Replace /dev/sdX with your actual device)
* Boot the board using the created SD card. See more info {{Varlink|Yocto Build Release#Boot_the_board_with_a_bootable_SD_card|{{#var:RELEASE_LINK}}|here}}.
* Boot the board using the created SD card. See more info {{Varlink|{{#var:GUIDE_NAME}} Build Release#Boot_the_board_with_a_bootable_SD_card|{{#var:RELEASE_LINK}}|here}}.
* Install the demo image to the eMMC. Either use the installation icons on the desktop (which will be updated with the "-u" parameter by the var-create-yocto-sdcard.sh script, when the recovery image used is var-image-swupdate), or use the install_yocto.sh script manually, with the "-u" parameter.
* Install the demo image to the eMMC{{#ifeq: {{#var:SOC_SERIES}} | imx8 |&nbsp;using|. Either use the installation icons on the desktop (which will be updated with the "-u" parameter by the var-create-yocto-sdcard.sh script, when the recovery image used is var-image-swupdate), or use}} the install_yocto.sh script {{#ifeq: {{#var:SOC_SERIES}} | imx8||manually,}} with the "-u" parameter.
{{Note|When called with the "-u" parameter, the install_yocto.sh script creates the double-copy compatible layout as shown above}}
{{Note|When called with the "-u" parameter, the install_yocto.sh script creates the double-copy compatible layout as shown above}}


Line 178: Line 186:
  <nowiki>http://<target_ip>:8080</nowiki>
  <nowiki>http://<target_ip>:8080</nowiki>
* On the web page, click "Browse..." and open the .swu image which is located at tmp/deploy/images/{{#var:MACHINE_NAME}}/var-image-swu-{{#var:MACHINE_NAME}}.swu
* On the web page, click "Browse..." and open the .swu image which is located at tmp/deploy/images/{{#var:MACHINE_NAME}}/var-image-swu-{{#var:MACHINE_NAME}}.swu
{{#ifexpr: {{#var:YOCTO_VERSION}} >= 3.1|
== known issues  ==
Due to a known issue in libarchive
https://github.com/libarchive/libarchive/issues/587
swupdate may fail decompressing the rootfs.tar.gz if any filename include UTF8 chars.
To let libarchive work without problems, a valid UTF8 locale for LC_CTYPE is required, however the default value is just "C".
From the command line, you can workaround this behavior by running
LC_CTYPE="en_US.utf8" swupdate -H {{#var:MACHINE_NAME}}:1.0 -i <filename.swu>
For the systemd service, in the file
/lib/systemd/system/swupdate.service
you can add the property
Environment=LC_CTYPE="en_US.utf8"
For the sysVinit service, in the file
/etc/init.d/swupdate
you can change the line
exec $DAEMON -v -H ${hardware}:1.0 -f /etc/swupdate.cfg $SWUPDATE_EXTRA_ARGS -u "$EXTRA_ARGS" -w "" -p 'reboot' &
to
exec env LC_CTYPE="en_US.utf8" $DAEMON -v -H ${hardware}:1.0 -f /etc/swupdate.cfg $SWUPDATE_EXTRA_ARGS -u "$EXTRA_ARGS" -w "" -p 'reboot' &
|}}

Revision as of 16:12, 18 January 2023

Warning: This page is designed to be used with a 'release' URL parameter.

This page is using the default release RELEASE_PYRO_V1.0_VAR-SOM-MX6.
To view this page for a specific Variscite SoM and software release, please follow these steps:

  1. Visit variwiki.com
  2. Select your SoM
  3. Select the software release


SWUpdate

SWUpdate Introduction

SWUpdate is a Linux Update agent with the goal to provide an efficient and safe way to update an embedded system.
SWUpdate 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.

It supports the common media on embedded devices such as as NAND flashes, UBI volumes, SD / eMMC, and can be easily extended to introduce project specific update procedures.
Pre- and postinstall scripts are supported, and a LUA interpreter helps to customize the update process.
An update package is described by the sw-description file, using the libconfig syntax or JSON. It is even possible to use Lua with a custom syntax.

Here is a short list of the main features:

  • Install on embedded media (eMMC, SD, NAND flash)
  • 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
  • Hardware / Software compatibility.


SWUpdate is developed by Stefano Babic from DENX, and is licensed under GPL Version 2.0+
You can check SWUpdate's online documentation at: http://sbabic.github.io/swupdate
This Introduction was taken from the SWUpdate README.md at: https://github.com/sbabic/swupdate

Example of using the meta-swupdate layer with Variscite i.MX boards is provided in the meta-variscite-fslc layer.
This example uses the double-copy approach, using two rootfs partitions on eMMC.

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

See the following link for info about the sw-description file syntax: https://sbabic.github.io/swupdate/sw-description.html

Update methods

Update via console

To start SWUpdate expecting the image from a file:

swupdate -H var-som-mx6:1.0 -i <filename.swu>

The -H option and its parameter is actually optional. The command can be simplified to

swupdate -i <filename.swu>

as long as a file named

/etc/hwrevision

is present in the rootfs and it's populated with the following content

var-som-mx6 1.0

Please note that no multiple instances of swupdate can be running simultaneously: if the roofs contains the service to start the swupdate web-server, the server must be stopped before running swupdate from command line

/etc/init.d/swupdate stop

You can schedule an auto update from a removable storage by editing the automount sequence, making it trigger the update command above, each time a removable device is inserted.

Update via http

OTA update is available via http protocol: It is possible to configure the software update agent to include embedded web-server (CONFIG_MONGOOSE). To start SWUpdate with the embedded web-server:

swupdate -w "--document-root ./www"

The default port of the Web-server is 8080. You can then connect to the target with:

http://<target_ip>:8080

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

To see all of the command line parameters of swupdate:

swupdate -h

Yocto Integration

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

Recipes

Before you begin, get familiar with the Varicite Yocto Build Release guide.

Variscite provides the following two image recipes:

  • var-image-swupdate - 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), instead of using a BOOT partition
    • 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

  • var-image-swu - This recipe creates an .swu update image using the var-image-swupdate image


The following is the sw-description file used by the Variscite sample update image recipe (var-image-swu).
This sample image consists of two components:
- A root file system (including the kernel), which is created by the var-image-swupdate recipe
- A bash script that runs before (called with preinst argument) and after (called with postinst argument) 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";
			}
		);
	};
}


And the following is the aforementioned update.sh bash script: update.sh
This script is being used in order to detect the root device and the U-Boot env. type and location (eMMC vs NAND flash) at runtime.

Create a SWUpdate-ready Image

  • Follow steps 1-3 of the Yocto Build Release page.
  • Build a recovery SD card and the var-image-swupdate image as the recovery 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 the "SWUpdate recovery 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)
  • Boot the board using the created SD card. See more info here.
  • Install the demo image to the eMMC. Either use the installation icons on the desktop (which will be updated with the "-u" parameter by the var-create-yocto-sdcard.sh script, when the recovery image used is var-image-swupdate), or use the install_yocto.sh script manually, with the "-u" parameter.
When called with the "-u" parameter, the install_yocto.sh script creates the double-copy compatible layout as shown above

Generate a Field Update file (.swu image)

  • 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:
http://<target_ip>:8080
  • On the web page, click "Browse..." and open the .swu image which is located at tmp/deploy/images/var-som-mx6/var-image-swu-var-som-mx6.swu