Documentation

Mistake on this page? Email us
Docs › Updating device firmware › Updating with snapcraft

Updating with snapcraft

On microcontrollers and some Linux devices, Izuma Device Management firmware-over-the-air (FOTA) updates are performed using A/B flash partitions. However, Izuma Edge with snapcraft performs FOTA updates using Ubuntu Core's update mechanism, snapd.

Typically on Ubuntu Core with snapd, snapd automatically performs updates on a semiregular schedule when snapd refreshes snaps through the Snap Store. Izuma's FOTA protocol for snap controls when "snap refresh" is performed by using the snapd-control interface provided by snapd.

Izuma's FOTA protocol for snap:

  • Verifies that after snap refresh is finished, the snap names and versions are as expected.
  • Maps the snap names/versions to an overall human readable version.
  • Customizes the update process through the pre-refresh.sh and post-refresh.sh scripts.

In essence, Izuma's FOTA protocol for snap gives you total control over the normal Ubuntu Core update mechanism, including all of Izuma Edge because it's distributed as a snap. The FOTA firmware tarball in this case is a few scripts and hashes that instruct and verify the download of the actual updates through the Snap Store.

Caveat: To use the snapd-control interface, Canonical requires the snap package maintainer to upload to a Brand Store instead of the public Snap Store.

Note: The FOTA protocol between the cloud and the device is flexible enough to fit almost any update paradigm. The currently implemented method in snap-pelion-edge uses snapd-control with a Brand Store by default. It could be modified instead to deliver the actual snaps in the firmware tarball instead of downloading them from the Snap Store.

This section explains how to:

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 Izuma Edge firmware update campaign on the gateway:

  1. Edge Core downloads and receives the payload and verifies it on the gateway.

  2. Edge Core stops.

  3. Edge Core firmware update scripts unpack the FOTA payload.

  4. If pre-refresh.sh exists in the FOTA payload, the gateway runs pre-refresh.sh.

  5. If pre-refresh.sh fails, Edge Core restarts and reports an error during the campaign. Else, the update continues.

  6. If map-version.json exists, its contents replace the existing hash to version map on the gateway.

  7. Edge Core firmware update scripts execute snap refresh and wait up to 5 minutes (configurable by running snap 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.

  8. If post-refresh.sh exists in the FOTA payload, the gateway runs post-refresh.sh.

  9. If post-refresh.sh fails, Edge Core restarts and reports an error during the campaign. Else, the update continues.

  10. Edge Core starts.

  11. 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 Izuma update campaign manager cloud service.
    • If the values don't match, Edge Core reports failure. You can find the update campaign status in the Izuma Device Management Portal.

  12. 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:

  1. Create a folder to hold the contents of the firmware update package. In this example, that folder is called update/.

  2. Add a file called update/platform-version.md5 to contain the platform version MD5 hash.

  3. (Optional) Add a pre-refresh.sh or post-refresh.sh file. See the sequence of events during a campaign above for more information.

    Note: Verify that both scripts have executable permissions.

  4. (Optional) Add any files that pre-refresh.sh or post-refresh.sh need or reference.

  5. (Optional) Add map-version.json.

    The map-version.json contains a map for the hash in platform-version.md5. It may also contain mappings for other hashes.

    Example map-version.json:

    { "abcdef01234567890000" : "v1.10.1" , "1234567890abcdef0000" : "v1.11.0" }

  6. 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 Izuma Device Management online documentation.

To initiate a firmware update campaign:

  1. Upload the firmware update tar.gz package to Izuma Device Management:

    1. Log in to Device Management Portal.

    2. From the left navigation pane, select Firmware Update > Images.

    3. Click the + Upload Image button.

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

  2. Create a firmware update manifest:

    1. Gather the update certificate, private key and manifest_tool.json file created by manifest-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.

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

  3. Upload the firmware update manifest to Device Management:

    1. From the left navigation pane, select Firmware Update > Manifests.
    2. Click the + Upload Manifest button.
    3. Follow the instructions on the screen to upload the manifest file.

  4. Create a device filter to select a set of registered devices that should receive the firmware update package:

    1. From the left navigation pane, select Device directory > Devices.

    2. In the grey bar above the list of devices, click the arrow next to Filters.

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

    4. Click Save.

      This opens the Filter name popup window.

    5. Give your filter a name.

    6. Click Save filter.

  5. Create the campaign:

    1. From the left navigation pane, select Firmware Update > Update campaigns.
    2. Click the + New Campaign button.
    3. Populate the Name and Description (optional) fields.
    4. From the Manifest dropdown list, select the manifest file uploaded earlier.
    5. From the Filter dropdown list, select the filter that targets the devices you need to update.
    6. Click Finish to start the campaign.
Previous