This topic explains how to run a firmware update on a device with a single system layout (not dual boot).

Requirements

To update your system using a SWU package, you need:

  • Partition recovery programmed with the recovery image generated by Digi Embedded Yocto. See Recovery partition.

  • Formatted update partition to hold the SWU package, or else an external media such as microSD card or USB disk. See Wipe the update partition.

  • A software update package with the new firmware.

To update from dey-3.2 version or lower to 4.0-r7 on a single boot layout, you must flash the recovery partition with the latest Yocto release before performing the firmware update.

Recovery partition

The recovery partition is similar to the linux partition; both hold the kernel and device tree blobs. The recovery partition also includes a recovery initramfs with support for updating the system. When instructed to do so, the initramfs performs the update of the firmware using the swupdate tool to program the specified SWU package.

Follow the get started process to have the recovery partition programmed. See Step 3 - Program the Yocto firmware.

Recovery utils

Recovery utils is a software package that provides:

  • librecovery: static library which implements the supported recovery commands. You can statically link your applications against this library to use the recovery feature. For more information, see Recovery library (firmware update).

  • recovery-reboot: command line application that allows you to configure the commands that will be run when booting into recovery mode.

    # recovery-reboot --help
Reboot into recovery mode setting recovery commands.
Copyright(c) Digi International Inc.

Version: 0.4

Usage: recovery-reboot [options] [<SWU-package-path>]

  -u              --update-firmware          Perform firmware update
  -i <image>      --image-set=<image>        Use the specified image-set from sw-description (only together with -u).
  -e <partitions> --encrypt=<partitions>     Encrypt the list of provided partitions.
  -d <partitions> --unencrypt=<partitions>   Un-encrypt the list of provided partitions.
  -k [<key>]      --encryption-key[=<key>]   Set <key> as file system encryption key.
                                             Empty to generate a random key.
  -w              --wipe-update-partition    Wipe 'update' partition
  -T <N>          --reboot-timeout=<N>       Reboot after N seconds (default 10)
  -f              --force                    Force (un)encryption and key change operations.
                  --help                     Print help and exit

<SWU-package-path>    Absolute path to the firmware update package

  • update-firmware: command for updating the firmware.

    # update-firmware --help
Update the firmware using the recovery reboot.
Copyright(c) Digi International Inc.

Version: 0.4

Usage: update-firmware [options] <SWU-package-path>

  -i <image>  --image-set=<image>        Use the specified image-set from sw-description.
  -k [<key>]  --encryption-key[=<key>]   Set <key> as file system encryption key.
                                         Empty to generate a random key.
  -T <N>      --reboot-timeout=<N>       Reboot after N seconds (default 10)
  -f          --force                    Force (un)encryption and key change operations.
              --help                     Print help and exit

<SWU-package-path>    Absolute path to the firmware update package

Wipe the update partition

The main purpose of the update partition is to store firmware update files before you launch a firmware update process on the device The recovery utils software package includes support to wipe the update partition of your device via the command line or your custom application. See Recovery utils for more information.

To wipe the update partition from the command line, execute the following command:

# recovery-reboot --wipe-update-partition

To wipe the update partition from your application, use the API provided by Digi. See Recovery library (firmware update).

Update the firmware using an SWU package

Follow these steps to update your system from the command line:

  1. Obtain the SWU firmware image in one of two ways:

    1. Generate a software update package (see Build a software update package) and find the image file inside the project directory at:

      <project_folder>/tmp/deploy/images/ccimx8x-sbc-pro/<image>-swu-ccimx8x-sbc-pro.swu

    2. Download Digi provided pre-built SWU from:

  2. Make sure the update package is accessible in one of the following places:

    • The update partition:

      # ls -l /mnt/update/
-rw-r--r--    1 root     root     731810304 Jan 26 18:15 <image>-swu-<platform>.swu

    • External media, such as USB disk or microSD card:

      # ls -l /run/media/sda1
-rw-r--r--    1 root     disk     731810304 Jan 26 18:15 <image>-swu-<platform>.swu
# ls -l /run/media/mmcblk1p1
-rw-r--r--    1 root     disk     731810304 Jan 26 18:15 <image>-swu-<platform>.swu

  3. Run the update-firmware command, passing the path to the SWU file as parameter. This triggers the firmware update process via the recovery boot mode:

    # update-firmware /mnt/update/<image>-swu-<platform>.swu

The recovery commands have been properly configured and the system will reboot into recovery mode in 10 seconds (^C to cancel).

...

    You can configure the reboot timeout (10s by default) with option -T of the update-firmware command. See Recovery utils for more information.

    The system will be restarted during the update process.

The firmware update process follows these steps:

  1. The device reboots into recovery mode. The kernel and initramfs in the recovery partition are booted instead of the kernel in the linux partition.

  2. The recovery ramdisk init does the following:

    1. Reads U-Boot’s environment recovery_command variable for the software update package file name.

    2. Looks for the software update package in the update partition and in external media.

    3. Executes the swupdate tool to program the firmware into the module.

  3. The device reboots and the firmware update is complete.

Update with a new encryption key

If you need to set a new file system encryption key (see Digi TrustFence for Yocto), use the --encryption-key option:

  • The update-firmware tool uses a base64-encoded string of a 32-byte binary key:

    # update-firmware --encryption-key=YjNz1psJsO3PsxIcdQwCjW7MA0Y5IryT38UCddViJNM= /mnt/update/<image>-swu-<platform>.swu

  • Or it can generate a random key if one is not provided:

    # update-firmware --encryption-key /mnt/update/<image>-swu-<platform>.swu

You can also install an update package from your custom application using the Firmware update API provided by Digi. See Recovery utils and Recovery library (firmware update).