Updating Pelion Edge Snap
This section explains how to:
- Generate a firmware update package that can be pushed down to a device through a firmware update campaign.
- Initiate a firmware update campaign.
Generate a firmware update package
A firmware update package is a tar.gz file containing at minimum a version file called platform-version.md5
and two optional bash scripts, called post-refresh.sh
and pre-refresh.sh
. The tarball may also optionally contain a file called map-version.json
containing a json dictionary used to map MD5 values to a readable version string.
platform-version.md5
must contain a single text string representing the combined versions of the software running on the device that is managed through this firmware update mechanism. To obtain a platform version MD5 hash, run the pelion-edge.platform-version
utility on the gateway that contains all of the desired snap versions.
Example:
pelion-edge.platform-version > platform-version.md5
The pre-refresh.sh
/post-refresh.sh
script implements customer logic to run before and after snap refresh
.
This example assumes a firmware update tar.gz with the following contents:
$ tar -tzf firmware-update.tar.gz
./
./pre-refresh.sh
./post-refresh.sh
./platform-version.md5
./map-version.json
Below is the sequence of events that occur during a Pelion Edge firmware update campaign on the gateway:
-
Edge Core downloads and receives the payload and verifies it on the gateway.
-
Edge Core stops.
-
Edge Core firmware update scripts unpack the FOTA payload.
-
If
pre-refresh.sh
exists in the FOTA payload, the gateway runspre-refresh.sh
. -
If
pre-refresh.sh
fails, Edge Core restarts and reports an error during the campaign. Else, the update continues. -
If
map-version.json
exists, its contents replace the existing hash to version map on the gateway. -
Edge Core firmware update scripts execute
snap refresh
and wait up to 5 minutes (configurable by runningsnap set pelion-edge edge-core.refresh-timeout=<max_seconds>
) for the operation to complete. If the operation fails or times out, Edge Core restarts and reports an error during the campaign. -
If
post-refresh.sh
exists in the FOTA payload, the gateway runspost-refresh.sh
. -
If
post-refresh.sh
fails, Edge Core restarts and reports an error during the campaign. Else, the update continues. -
Edge Core starts.
-
Edge Core firmware update scripts call
pelion-edge.platform-version
to compare the firmware MD5 hash to the MD5 hash in the FOTA payload:- If the values match, Edge Core reports success to the pelion update campaign manager cloud service.
- If the values don't match, Edge Core reports failure. You can find the update campaign status in the Pelion Device Management Portal.
-
Edge Core uses the hash to version map to translate the platform-version hash into a readable version string.
Edge Core sets a LWM2M resource with this string. Edge Core reports an empty string if no mapping exists for the hash.
To create a firmware update tar.gz package:
-
Create a folder to hold the contents of the firmware update package. In this example, that folder is called
update/
. -
Add a file called
update/platform-version.md5
to contain the platform version MD5 hash. -
(Optional) Add a
pre-refresh.sh
orpost-refresh.sh
file. See the sequence of events during a campaign above for more information.Note: Verify that both scripts have executable permissions.
-
(Optional) Add any files that
pre-refresh.sh
orpost-refresh.sh
need or reference. -
(Optional) Add
map-version.json
.The
map-version.json
contains a map for the hash inplatform-version.md5
. It may also contain mappings for other hashes.Example
map-version.json
:{ "abcdef01234567890000" : "v1.10.1" , "1234567890abcdef0000" : "v1.11.0" }
-
Create the firmware update tar.gz package from the contents of the
update/
folder:tar -czf firmware-update.tar.gz -C update/ .
Initiate a firmware update campaign
Device Management pushes your firmware update package down to a defined set of devices, which unpack the firmware update package and apply the updates within it.
You can initiate a firmware update campaign targeting any registered device from Device Management Portal.
Note: You can also initiate a firmware update campaign using the APIs, as explained in the Pelion Device Management online documentation.
To initiate a firmware update campaign:
-
Upload the firmware update tar.gz package to Pelion Device Management:
-
Log in to Device Management Portal.
-
From the left navigation pane, select Firmware Update > Images.
-
Click the + Upload Image button.
-
Follow the instructions on the screen to upload the tar.gz file.
After you upload the file, Device Management Portal displays a URL from which devices can download the tar.gz file.
-
-
Create a firmware update manifest:
-
Gather the update certificate, private key and
manifest_tool.json
file created bymanifest-tool init
in the quick start, which includes.update-certificates/default.der
,.update-certificates/default.key.pem
and.manifest_tool.json
. Copy these files to the directory where you are preparing the firmware update for use in the following step. -
Use the manifest-tool utility to create a manifest file for your firmware update tar.gz package:
manifest-tool create -u <firmware.url> -p <firmware-update.tar.gz> -o manifest
Notes:
- The manifest-tool utility requires the files certificate and
manifest_tool.json
copied in the previous step. <firmware.url>
is the URL of the firmware update tar.gz package, as shown in Device Management Portal. Devices use this URL to download the firmware update image.<firmware-update.tar.gz>
is the firmware update package tar.gz file. The manifest-tool utility calculates a hash from the firmware update tar.gz. -.manifest_tool.json
must be in the current directory. -.update-certificates/
folder must be in the current directory.
- The manifest-tool utility requires the files certificate and
-
-
Upload the firmware update manifest to Device Management:
- From the left navigation pane, select Firmware Update > Manifests.
- Click the + Upload Manifest button.
- Follow the instructions on the screen to upload the manifest file.
-
Create a device filter to select a set of registered devices that should receive the firmware update package:
-
From the left navigation pane, select Device directory > Devices.
-
In the grey bar above the list of devices, click the arrow next to Filters.
-
Choose an attribute and operator, and give a value, such as Device ID.
- To combine multiple attributes in one filter, click Add another.
- To use a raw string instead, click Advanced view.
-
Click Save.
This opens the Filter name popup window.
-
Give your filter a name.
-
Click Save filter.
-
-
Create the campaign:
- From the left navigation pane, select Firmware Update > Update campaigns.
- Click the + New Campaign button.
- Populate the Name and Description (optional) fields.
- From the Manifest dropdown list, select the manifest file uploaded earlier.
- From the Filter dropdown list, select the filter that targets the devices you need to update.
- Click Finish to start the campaign.