In a production environment it is convenient to plan updates, and have control on when and which device(s) are updated. FoundriesFactory Waves is the feature for this.
This post gathers a suggested sequence of commands to configure the first wave, and to guide for next waves.
The main purpose of a Wave is to plan the fleet update, giving the Factory operator full control on when to allow certain devices to look for a new OTA update available. It also allows the operator to split up the fleet of devices according to the defined update plan.
The wave feature is first presented in the post Release on demand with FoundriesFactory Waves which details the description of a wave and how to configure different approaches to deployment of waves.
The wave feature depends on configuration of device groups, a feature presented in the post FoundriesFactory Device Groups
- device group feature is added on
- wave feature is added on
- production feature is added on
The instructions to create a FoundriesFactory are detailed in the Getting Started page.
When a new FoundriesFactory is created, an email with a link to download the offline keys are sent to the registered email.
Download the offline keys and store them in a secure way. It is a tarball also known as root credentials. They are used for TUF key management.
For this example, the following variables are being exported:
host:~$ export PATH_TO_KEY=/media/secure/offline-creds.tgz host:~$ export FIOCTL_FACTORY=my_factory_name
PATH_TO_KEY is the absolute path to the offline credential tarball file, and
FIOCTL_FACTORY is the FoundriesFactory name.
host:~$ fioctl login
host:~$ fioctl keys rotate-root $PATH_TO_KEY host:~$ fioctl keys rotate-targets $PATH_TO_KEY
Detailed information for key rotation can be found here.
Work with the source code until the targets available are ready to be published to the devices on a production environment. Flash the devices with the desired target.
For help on how to flash the device the details are provided in this document.
Make sure the device is registered as
device:~$ sudo su device:~$ export PRODUCTION=ON device:~$ lmp-device-register -n <device-name>
<device-name> is unique for every device registered.
Register as many devices as needed.
host:~$ fioctl wave init -k $PATH_TO_KEY populate-targets <version> <tag> host:~$ fioctl wave complete populate-targets
<version> is the target version, a number that can be found on the target page for the factory: https://app.foundries.io/factories/factory-name/targets/
<tag> is the production tag that is used for the wave.
Details on the production targets can be found at the OTA Reference Manual.
The targets access the FoundriesFactory through the Device Gateway which is presented in Taking ownership of device gateway PKI.
In this example, there are 3 devices, and they are split into 3 different device groups. However, in a production scenario it is common to cluster the devices by architecture, region, or Internet access.
The main point of clustering the devices in a device group is to coordinate the update on all those devices at once.
For example, create three device groups in an easy to follow order with this example.
host:~$ fioctl config device-group create one "the first set" host:~$ fioctl config device-group create two "the second set" host:~$ fioctl config device-group create three "the third set"
The OTA Reference Manual also details the device configuration.
In this example there are three devices: deviceA, deviceB and deviceC. Each device is part of a device group. Each device group has only one device.
For a real production environment, a device group can comprise several devices, however a device can be configured on only one device group.
host:~$ fioctl device config group deviceA one host:~$ fioctl device config group deviceB two host:~$ fioctl device config group deviceC three
After some time, changes are produced with new features and/or bug fixes. A new target is then created, and the update to the devices can be planned.
It is time for a wave!
At this point, the environment is ready to run a wave to update the registered devices in an organized way.
The command line to create
host:~$ fioctl wave init wave1 <version_> <tag> -k $PATH_TO_KEY
wave1 is created, but no device has yet been updated. See the list of waves so far with the following command:
host:~$ fioctl wave list NAME VERSION TAG STATUS CREATED AT FINISHED AT ---- ------- --- ------ ---------- ----------- wave1 <version_> <tag> active 2021-04-06T14:40:48.855063 populate-targets <version> <tag> complete 2021-04-05T18:33:37.477752 2021-04-05T18:34:06.946635
See the status of the current active wave with the following command
host:~$ fioctl wave status Wave 'wave1' for tag <tag> version <version_> is active Created At: 2021-04-06T14:40:48.855063 Device Groups on Tag '<tag>': 3 Device Groups Rollout: 0 Devices on Tag '<tag>': 3 Devices Updated: 0 Devices Scheduled for Update: 0 Devices Not Scheduled: 3 GROUP TOTAL UPDATED NEED UPDATE ONLINE ROLLOUT AT ----- ----- ------- ----------- ------ ---------- one 1 0 1 1 At Wave Completion three 1 0 1 1 At Wave Completion two 1 0 1 1 At Wave Completion
The next step is to configure the devices of a certain device group to look for an update.
In this example, the first device group to receive a rollout is
host:~$ fioctl wave rollout wave1 one
From this point, the wave continues according to update plan defined previously by the factory operator.
For this example, the sequence is rollout device group two, and then device group three, using the following commands:
host:~$ fioctl wave rollout wave1 two host:~$ fioctl wave rollout wave1 three
However, another option would be rollout all the remaining devices instead:
host:~$ fioctl wave complete wave1
Or maybe, cancel this wave and have no more devices updated with
<version_> is also an option.
host:~$ fioctl wave cancel wave1
The last three possible flows for the wave are only a illustration of how flexible the update path can be. There are other options and configurations described in the OTA Reference Manual.
host:~$ fioctl -f <factory> wave list host:~$ fioctl -f <factory> wave status host:~$ fioctl -f <factory> devices list host:~$ fioctl -f <factory> targets list