Customizing Over The Air Updates

By default, Secure Over The Air update (SOTA), operates as a daemon process (ref:ref-aktualizr-lite) which periodically checks for updates. If an update is available, it will automatically download, and install it to a device that is following the update tag.

This is not always the desired operation. There are a couple ways to control this operation:

  1. Callbacks
  2. Custom Update Agent

Callbacks

Aktualizr-lite provides the ability to run an executable at the following OTA operations:

  • Before checking in — check-for-update-pre return: none
  • After checking in — check-for-update-post return: OK or FAILED: reason
  • Before a download — download-pre return: none
  • After a download — download-post return: OK or FAILED: reason
  • Before an install — install-pre return: none
  • After an install — install-post return: NEEDS_COMPLETION, OK, or FAILED: reason
  • After a reboot — install-final-pre return: none

A simple recipe is in aktualizr-callback and a sample script is in callback-handler.

Custom Update Agents

This section shows how to create a custom update agent—“SOTA client”—for your platform. Aktualizr-Lite is a general purpose SOTA client that fits many needs. However, some cases require more control over the update agent than aktualizr-lite and the “hooks” system can provide. In these cases, a custom SOTA client can be written in C++ using the aktualizr-lite API.

Using the Custom SOTA Client Example

The example SOTA client in aktualizr-lite is a great place to start experimenting. The meta-lmp layer includes a recipe that runs this example as the default SOTA client. Later, this can serve as an example to copy/paste into a Factory specific recipe.

Users can build this custom client into their LmP image with a small addition to meta-subscriber-overrides.git:

git clone -b devel https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
cd meta-subscriber-overrides
echo 'SOTA_CLIENT = "custom-sota-client"' >> conf/machine/include/lmp-factory-custom.inc

Forking the custom SOTA Client

Producing a factory-specific SOTA client can be done by:

  1. Creating a Git repository for your custom code. Copying the examples/custom-client-cxx directory is a good place to start.
  2. Copying the custom-sota-client recipe from meta-lmp into meta-subscriber-overrides/recipes-sota.
  3. Changing the custom-sota-client_git.bb Git references (SRC_URI, BRANCH, SRCREV) to point at your new sources.
Custom SOTA Client Work Modes

By default, the example SOTA client works as a daemon updating a device to the latest version once it becomes available. In addition to the default daemon mode, users can run it as a CLI utility and perform specific steps of the update process separately.

/build-custom/custom-sota-client --help
Usage:
    custom-sota-client [cmd] [options]
Supported commands: check install run pull daemon
Default command is "daemon"
  • check - updates the device’s TUF repo with the latest Factory’s TUF metadata or with the TUF metadata specified in the offline update bundle, and checks if there is a newer than currently installed Target.
  • pull - pulls the delta between the currently installed and the specified one.
  • install - installs the previously pulled Target; yields an error if the specified Target has not been pulled before.
  • run - finalizes the installed Target; confirms an update after reboot on a new rootfs version and/or starts the updated apps.