If your Digi Embedded Yocto system is already running, you can update the firmware with a software update package (SWU).
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.
A software update package with the new firmware.
Formatted update partition to hold the SWU package, or else an external media such as microSD card or USB disk.
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.
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.
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:
Obtain the SWU firmware image in one of two ways:
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
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.
The system will be restarted during the update process.
The firmware update process follows these steps:
The device reboots into recovery mode. The kernel and initramfs in the recovery partition are booted instead of the kernel in the linux partition.
The recovery ramdisk init does the following:
Reads U-Boot’s environment recovery_command variable for the software update package file name.
Looks for the software update package in the update partition and in external media.
Executes the swupdate tool to program the firmware into the module.
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 library (firmware update).
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.3 Usage: recovery-reboot [options] [<SWU-package-path>] -u --update-firmware Perform firmware update -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.3 Usage: update-firmware [options] <SWU-package-path> -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