You can update the entire system from a local update package using the included command tools.

Requirements

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

  • A software update package with the new firmware.

Follow these steps to update your system from the command line using an already generated package:

  1. Get the firmware image <software-update-package>.swu:

    1. After building the Yocto firmware, you can find the image file inside the project directory at:

      <project_folder>/tmp/deploy/images/<platform>/<image>-swu-<platform>.swu

    2. You can download Digi provided pre-built image from:

  2. Make sure the update package is accessible locally. See Build a software update package for more information.

    For example, in the update partition:

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

    Or in external media:

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

  3. Use the update-firmware command to trigger 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.

    The system will be restarted during the update process.

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 library (firmware update).

Firmware update process

Once the firmware update process is triggered, it follows these steps:

  1. 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 init reads U-Boot’s environment recovery_command variable for the software update package file name.

  3. The recovery init looks for the software update package in the update partition and in external media.

  4. The recovery init executes the swupdate tool to program the firmware into the module.

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

Wipe the update partition

The main purpose of the update partition is the storage of firmware update files prior to launching a firmware update process on the device. Recovery utils software package includes support to easily wipe the update partition of your device from the command line or from your custom application.

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).

Recovery partition

The recovery partition is similar to the linux partition; both hold the kernel and device tree blobs. But 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 and the update packages generated by Digi Embedded Yocto.

The recovery partition is programmed by default during the getting started process when you program the Yocto firmware. See Step 3 - Program the Yocto firmware.

Recovery utils

Recovery utils is a software package that allows you to configure the recovery commands to later reboot into recovery mode and perform the configured tasks. It provides:

  • librecovery is a 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 configures and reboots into recovery mode.

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

Version: 0.2

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

  -u  --update-firmware          Perform firmware update
  -k  --encryption-key=<key>     Set <key> as file system encryption key.
                                 Empty to generate a random key.
  -w  --wipe-update-partition    Wipe 'update' partition
  -T  --reboot-timeout=<N>       Reboot after N seconds (default 10)
      --help                     Print help and exit

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

  • update-firmware command supports only the firmware update recovery command.

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

Version: 0.2

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

  -k  --encryption-key=<key>     Set <key> as file system encryption key.
                                 Empty to generate a random key.
  -T  --reboot-timeout=<N>       Reboot after N seconds (default 10)
      --help                     Print help and exit

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