Mistake on this page? Email us

Integration with Pelion Device Management

The Arm Pelion IoT platform connects devices to the cloud for easy management. The Pelion Device Management (PDM) services manage the device's connection and resource management, as well as remote firmware updates.

The PDM integration in Mbed Studio configures your program with the certificates, IDs and other credentials it needs to connect to PDM. It can also perform a firmware update with a single click. This makes it easy to test your program's PDM functionality: verify your program can connect to your PDM account, send the correct resources and correctly apply a new firmware update.

Note: You need a Pelion Device Management account to use its services. If you do not have an account, request access from your Mbed account portal.

Overview

To be able to connect to PDM and receive updates, a program (the first image installed on a device) 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 API key to access Pelion Device Management services.
  • An update certificate to verify that incoming updates come from a trusted source.
  • A bootloader to verify and install update images.
  • The Pelion Device Management Client library (mbed-cloud-client.lib), normally imported as part of the example program mbed-os-example-pelion.

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, use offline tools to generate and store these certificates securely.

Once the initial, updatable program is on the device, the device itself is considered updatable - it can receive over-the-air updates. These updates can be sent to the device (or multiple devices) using Pelion Device Management (all your devices must be connected to Pelion Device Management before rolling out the campaign.)

To update a device, you need:

  • A new firmware image. This image does not include the certificates, keys and bootloader of the original program; it contains only the program code.
  • 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 a private key to assure the device that the image is from a trusted source and has not been tampered with.
  • A private key so you can sign the firmware update manifest file.

From Mbed Studio, you can then roll out an update campaign for your image, using the manifest, to your selected devices. Mbed Studio monitors the devices and shows applied updates.

Connect your device to Pelion Device Management

To create a connect certificate and give your program access to your Pelion Device Management account:

  1. Create a new program from the mbed-os-example-pelion example.

    Make sure the program is set as active.

  2. If you don't have a Pelion Device Management API key, create one:

    1. Go to the Pelion Device Management view.

    2. Click Open Pelion Device Management.

    Your web browser opens the Pelion Device Management portal.

    1. Log in to your Pelion Device Management account.

    2. Go to Access management > API keys.

    3. Click + New API key and follow the instruction on the screen.

    1. Copy the API key to the clipboard.

  3. Add your API key to Mbed Studio:

    1. In the Pelion Device Management view, click the API cogwheel:

    1. Paste your API key:

  4. If you don't have a connect certificate, create one:

    1. In the Pelion Device Management portal, go to Device identity > Certificates.

    2. Click + New Certificate > Create a developer certificate and follow the instructions to create a developer certificate.

    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, so that it's not pushed to your source control repositories.

  5. To add your certificate to your program, in the Mbed Studio Pelion Device Management view, click Configure.

    Mbed Studio uses your API key to display all your available certificate. Select the one you want to add to the program.

  6. To be able to update your program, leave the Enable remote firmware update checkbox selected. This will add an update certificate and key to the program.

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

  7. Click Done.

    Mbed Studio updates the file mbed_cloud_dev_credentials.c in your program with your developer certificate information.

    The program can now connect to your Pelion Device Management account.

  8. Set up your program to connect the internet, Wi-Fi or Ethernet:

    • For Wi-Fi: In your program's mbed_app.json file, set up your Wi-Fi credentials: enter a value for nsapi.default-wifi-ssid (replace SSID) and nsapi.default-wifi-password (replace PASSWORD). Make sure you leave the quote marks and escape characters, for example "\"<newname>\"", and "\"<password>\"".

    • For Ethernet: Connect your board with a cable; no program setup is required.
  9. Build and run the program to connect your device. When your device goes online, you can see it in the Pelion Device Management portal.

Update workflow

Once you've flashed the initial program to your device (over USB), you can start using Pelion Device Management to remotely update new versions of the program.

To update your device:

  1. Make changes to your program.

  2. In the Pelion Device Management view, click Push to device. Mbed Studio:

    1. Builds the program as a new image, which does not include the bootloader (that was only needed for the initial program).

    2. Creates a manifest for the update, signed with your private key.

    3. Uploads the image and manifest to Pelion Device Management and updates all connected devices that match the class ID and vendor ID listed in the manifest.

    Mbed Studio reports the number of successfully updated devices.

    Note: The vendor and class IDs are randomly generated on your machine as part of the PDM configuration process, so it is highly unlikely that the update will target anyone else's device. You can also set these manually

You can see your update image, manifest and campaign in the Firmware update menu of the Pelion Device Management portal.

Troubleshooting

Using a new update certificate fails

If you need to change your program's update certificate, or if you're using the same development board to test more than one applications (each application should have its own update certificate), you will need to erase your board's storage; the certificate is not erased in the normal process of reflashing a board. You can do this by:

  • Sending r: Focus on the Serial Monitor view and press R.
  • For an external SD card, connect the card to your computer and format it as instructed by the manufacturer.
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.