Mistake on this page? Email us

Integration with the Pelion Device Management Portal

Mbed Studio integrates with the Pelion Device Management Portal.

Note: You need a Pelion Device Management account to use the update services. If you do not have an account, request access here.

Overview

Using Mbed Studio, you can connect your Mbed OS IoT devices to the Pelion Device Management Portal. The devices bootstrap with Pelion Device Management and come online. You can then read data from the devices or update your IoT firmware remotely. In order to do this, you need to publish a firmware update image and sign a manifest. From the Portal, you can then roll out an update campaign to your selected devices and see when the updates have been applied. All your devices must have been connected to Pelion before rolling out the campaign.

Creating a program you can update

To be able to receive updates, a program must have:

  • A connect certificate to access a Pelion Device Management account. When you run the program on a device, the bootstrap server will use this connect certificate to authenticate your program with your Pelion Device Management account.
  • An update certificate to verify that incoming updates come from a trusted source.
  • A bootloader to verify and install update images.
  • The Device Management Client library (mbed-cloud-client.lib), normally imported as part of the example program (mbed-cloud-client-example).

You need:

  • A private key so you can sign the firmware update manifest file.
  • A manifest file, which defines the update, including the location of the new firmware image and the type of device the update applies to. The manifest file is signed with the private key to assure the device that the image is from a trusted source and has not been tampered with.

Warning: For development use cases only, you can use Mbed Studio to generate the certificates ("developer" connect and update certificates) and the manifest file. For production use cases, it is highly recommended to use offline tools to generate and store these certificates securely.

Creating an update image

Once the initial, updatable program is on the device, the device is considered updatable. This means the device can receive over-the-air updates. Subsequent image updates do not include the certificates, keys and bootloader of the original program; they contain only the program code. These updates can be sent to the device or devices using Pelion Device Management.

Connect workflow

The connect workflow consists in creating a connect certificate to give your program access to your Pelion Device Management account.

  1. In Mbed Studio, ensure the program is set as active. To make the program active, right-click the program name in the files pane and select Set Active Program.
  2. In the Pelion Device Management pane, open the Connect drop-down and click Create. If you already have one or several connect certificates, they will be displayed. If the API key to connect to your Pelion Device Management account is not found, you will be prompted to enter it manually in Mbed Studio. You can create a new API key from the Pelion Device Management Portal. If the API key is found, the message "Pelion API key found." is displayed. You can click Edit to update the key.
  3. Enter a name for the connect certificate and click OK.
  4. Click + to add the connect certificate to your program. A check mark appears to the right of the certificate.
  5. From the files pane, click Run program to build and run your program.

When you run the program on your device, the bootstrap server uses the connect certificate to authenticate your program with your Pelion Device Management account. This file is your "developer" connect certificate and is identical to the file you can download from the Portal.

Warning: The developer connect certificate file contains multiple certificates and a private key. It is not suitable for production and you must keep it safe so as not to expose the private key. We recommend adding it to your .gitignore (for Git repositories) or .hgignore (for Mercurial repositories) file.

From the Portal, you can check and manage the certificate that has just been created. Go to the Device identity menu and click Certificates. Click the certificate to display the certificate details.

Update workflow

The update workflow consists in applying an update certificate to your project to be able to do firmware updates remotely. Then you need to publish a firmware update image and sign a manifest.

Applying an update certificate:

  1. In the Pelion Device Management pane, open the Update drop-down and click Apply Update Certificate. The update certificate is added to your project and the corresponding private key is generated. The private key is used for manifest signing. In the files pane, you can see two new files have been created: update_certificate.pem (public key) and update_key.key (private key). The update_default_resources.c file has also been modified with the information needed to check the validity of future firmware updates.
  2. From the files pane, click Run program to build and run your program.

This builds your program and uploads it to your Pelion Device Management account so you can use it as a firmware update. This image does not include the bootloader. This stage also creates a manifest for the update, and will use your private key (update_key.key) file to sign the manifest.

Warning: The update certificate and key are not suitable for production use cases.

Publishing the firmware update image and manifest to Pelion:

  1. From the Pelion Device Management pane, click Publish To Pelion.
  2. Provide a name and a description for your platform in the Firmware details fields, then click Sign & Upload Firmware Update.
  3. Click the Open Pelion Device Management link to open the Portal.

From the Portal, you can now start deploying the newly uploaded firmware update to your device or devices. Go to the Firmware update menu and select Update campaigns. Click on + NEW CAMPAIGN and select New update campaign wizard. Type a campaign name and a description. Then, select the manifest which Mbed Studio has created and uploaded for you from the list and click Next. Select the device or devices you wish to deploy the firmware update to from the list and click Next. Your device or devices should be listed if the connect workflow was successful. Review the update campaign details and click Finish whenever you are ready. The campaign is now created and can be started anytime by clicking Start.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.