A/B update scheme

The D7 Platform uses an A/B update scheme, so that if a software update fails, the device automatically reverts to the previous image.

When applying a software update, the rootfs is written to one of the two partitions, for instance to partition A. A subsequent software update will write the rootfs to partition B, and then the next update will write to parition A again.

When booting up after a software update, if the validation fails, the device will revert to the previous partition. More information on that in the Software update validation section below.

For more information on the partitioning scheme of the D7, please see Partitions on the D7 Platform.

Software update validation

After a software update is applied, the system will attempt to validate the stability of the update.

An update is considered stable if within the first three boot attempts, at least one attempt is successful.
A boot attempt is considered successful if all the critical services are successful within a 60 second window.
- If one of the critical services fails within the first 60 seconds, a reboot is triggered.
- Note: All the networking services (ethernet, firewall, etc.) are considered non-critical and allowed to fail. If you wish to mark one of your own services as non-critical, please see (Optional) Marking a service as non-critical.
If the update is validated in the first three boot attempts, the validation ends and the current partition is considered stable.
Otherwise, at the fourth reboot, the device will automatically revert to the previous partition, as described in the A/B update scheme section.

Warning: After rolling back from an unstable update, the booted image is not validated again to avoid an endless cycle of switching partitions.

Software update logs

The logs for software updates are stored in /appdata/sys/swupdate/swupdate.log.

This partition is persistent across software updates, so the logs for a failed update can be inspected.

Reflashing the board, however, does overwrite the /appdata partition.

swugen

The swugen tool creates software updates that can be used on the device. It can produce images based on either the development or the release base image. See Differences between release and development images for a detailed description of the differences between the two.

swugen can accept two types of input:

Directory input: When provided with a directory, swugen automatically creates a standardized update package structure for applications that use systemd services. It processes directories containing executables, systemd services, and custom configuration files, automatically handling systemd service dependencies and creating proper symlinks.
Archive input: When provided with an archive (.tar.bz2, .tar.gz, .tar.xz, .tar.zst, .zip), swugen uses the archive without modification to the structure.

Usage

swugen -i <source> -k <keypath> -o <swu-output> [--release | --development] [--update | --recovery]

Arguments:

-i <source> - Input source (directory or archive)
-k <keypath> - Path to your private key to sign the manifest (for the moment that is just a test key and it must not be used in production)
-o <swu-output> - Output path for the .swu file
--final-path - Print the formatted swu output file path only

Modes:

-r, --release - Generate a release update (default)
-d, --development - Generate a development image

Image types:

--update - Generate an update image (default)
--recovery - Generate a recovery image

Recovery images generated by swugen can be used to create a recovery USB stick using the procedure described here.

Note: swugen will append to the output swu file the SDK version information, ensuring the SDK version used for creating the swu file is easily identifiable.

As an example, assuming the SDK version is 3.0.0 and the build number is 500, if you provide -o file.swu as an argument to swugen, it will produce file-3.0.0+500.swu. The SDK version format is {sdk-version}+{sdk-build-number}.

Project structure

An example folder structure to be used as input for swugen is as follows:

target-install/
├── bin/
│   └── qml-analog-app
├── qml-analog-app.service
├── user.rules
└── user6.rules

For special files, ufw rules and systemd service unit files, they must be placed in the top-level directory. All other files may be structured as you wish.

Note: Unit files and ufw rules files will be moved according to the Standardized Update Package Structure. To be safe, all paths should be absolute paths that relate to the project install location which is /app.

Running swugen -i target-install -k keys/default-key -o my-app.swu will automatically generate the standardized package structure and create the .swu file.

Standardized Update Package Structure

When using directory input, swugen generates a standardized update package structure:

update_package.tar
├── [your application folder structure]
└── sys
    └── etc
        ├── systemd
        │   └── system
        │       ├── [your service files]
        │       └── [target].wants/
        │           └── [symbolic links based on `wantedby`]
        └── ufw
            ├── user.rules
            └── user6.rules

Examples

Directory processing (replaces the old appgen workflow):

swugen -i /path/to/app_folder -k keys/default-key -o my-app.swu

Archive processing:

swugen -i app_package.tar -k keys/default-key -o my-app.swu

Recovery image:

swugen -i /app/folder -k keys/default-key -o recovery.swu --recovery

Partition Handling

When applied, the update will extract the contents of the update layout into the /app partition, recreating the folder structure exactly.

Note that the /app partition is formatted when applying a software update, along with the other partitions in the current step of the A/B scheme. As such, it should not be used to store persistent data.

Applications must write persistent data to the /appdata partition. See Partitions on the D7 Platform.

Table of Contents