Command-line tutorial for the Device Management Client example with Zephyr OS

This is a Device Management Client example, written using Device Management Client 4.13.0 and Zephyr OS 2.7.3.

Supported boards

Supported boards have:

• At least 1 MiB total storage:
  • 512 KiB for application, bootloader and credential storage.
  • 512 KiB for firmware update.
• 256 KiB RAM.
• These Zephyr APIs implemented:
  • POSIX Network API.
  • Flash map.

You can use this tutorial with the example application mbed-cloud-client-example and the following boards:

For third party example applications and boards, use the following tutorials:

Prerequisites

To work with the Device Management Client example application, you need:

• A Zephyr OS supported board with a network connection and enough flash and RAM.

• Serial or debugger connection to your device for accessing the log.

• Zephyr's command-line tool, West.

• A toolchain matching your development board.

• An Izuma Cloud account, if you do not have an account - contact us.

• Device Management's command-line manifest-tool version 2.4.1 or later for firmware updates.

  Note: If your host system Python version is 3.6, use manifest-tool version 2.4.1, use version 2.5.0 (or newer) for more up-to-date system. You can specify version via: pip install manifest-tool==2.4.1.

Configuring Device Management Client

1. Initialize a new Zephyr workspace using the manifest from mbed-cloud-client-example:

   west init -m https://github.com/PelionIoT/mbed-cloud-client-example zephyr-workspace
   cd zephyr-workspace
   west update
   

   This creates the following workspace on your computer:

   zephyr-workspace
   ├── bootloader
   ├── modules
   │   └── lib
   │       └── izuma-dm (middleware library)
   ├── izuma-dm-example (example application)
   │   ├── pal-platform
   │   │   └── SDK
   │   │       └── ZephyrOS (Zephyr project)
   │   │           └── boards (example overlays)
   │   └── west.yml (West manifest)
   ├── tools
   └── zephyr
   

2. Download a developer certificate from Device Management Portal.

3. Copy the mbed_cloud_dev_credentials.c file to the izuma-dm-example directory in your workspace.

4. Get an access key for your Device Management account.

5. Create update-related configuration and credentials in a new, empty directory using the manifest-tool:

   mkdir manifest
   cd manifest
   manifest-dev-tool init --access-key <Device Management access key>
   

   This directory now contains a private key suitable for authorizing firmware updates for devices provisioned with the public key and configuration stored in the file update_default_resources.c.

6. Copy the update_default_resources.c file from the manifest directory to the pelion-dm-example directory.

Note: When you create a firmware update image for a deployed device, you must use the same update-related configuration and credentials (update private key, public key certificate, update_default_resources.c and configuration files) you used in the original device firmware image.

We highly recommend creating a Python virtual env for Zephyr SDK. Do install also the Zephyr python requirements.

python3 -m venv venv
source venv/bin/activate
pip install -r zephyr/scripts/requirements.txt

Compiling and flashing Device Management Client

Using the Freedom-K64F board as an example:

1. Build the MCUboot bootloader using the memory overlay file frdm_k64f.overlay by executing this command from the top-level zephyr-workspace directory:

   west build -b frdm_k64f -d build/mcuboot -s bootloader/mcuboot/boot/zephyr -- \
   -DDTC_OVERLAY_FILE="$PWD/izuma-dm-example/pal-platform/SDK/ZephyrOS/boards/frdm_k64f.overlay" \
   -DCONFIG_MCUBOOT_CLEANUP_ARM_CORE=y
   

   Note: See the flash layout section for more about overlay files.

2. Build and sign the example application:

   west build -b frdm_k64f -d build/dmc -s izuma-dm-example -- \
   -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"
   

   root-rsa-2048.pem is the default MCUboot private key used for testing and development.

Flashing the binary to the device

To flash the bootloader and application to the device:

west flash -d build/mcuboot
west flash -d build/dmc

Connecting and performing a firmware update on your device

Checking the device connection and obtaining the device ID

Obtain the Device ID either from device console logs or from Device Management Portal.

When the client has successfully connected, the terminal shows:

Client registered
Endpoint Name: <Endpoint name>
Device ID: <Device ID>

To verify the connection with Device Management Portal:

1. Log in to Device Management Portal for your region:

   • United States.

2. Select Device directory from the menu on the left.

   When the Devices page lists the device as registered, the device is connected and available.

The device is now ready for firmware update. For development devices, the endpoint name and device ID are identical.

Updating the firmware

To update the firmware on the device, copy the file zephyr.signed.bin from the build folder build/dmc/zephyr to the manifest directory created earlier, which contains your update credentials. To start a firmware update campaign, run:

manifest-dev-tool update-v1 \
--payload-path zephyr.signed.bin \
--device-id <Device ID> \
--wait-for-completion

This command:

1. Uploads the new firmware to Device Management.
2. Creates and signs a manifest file describing the firmware.
3. Creates and starts a firmware update campaign for the given device ID, using the manifest.
4. Waits for the campaign to finish and reports the result.

During the update flow, the client tracing log shows:

Firmware download requested
Authorization granted
Downloading: 1 %
...
Downloading: 100 %
Download completed
Firmware install requested
Authorization granted

After this, the device reboots automatically and registers to Device Management.

Note: Device Management Client for Zephyr OS currently only supports firmware update features from version 4.7. Please refer to the version 4.7 documentation when using firmware update.

User applications

To add Device Management Client to an existing project, add this repository and module to the West manifest:

remotes:
  - name: PelionIoT
    url-base: https://github.com/PelionIoT
projects:
  - name: izuma-dm
    repo-path: mbed-cloud-client
    remote: PelionIoT
    revision: master
    path: modules/lib/izuma-dm

Flash layout

Zephyr OS abstracts internal and external storage devices into isolated, labeled partitions. Each starts at address 0x0 regardless of the real, underlying storage medium.

The bootloader, MCUboot, is stored in the partition labeled mcuboot. The active application is executed from image_0, and the candidate firmware is stored in image_1. Izuma Device Management Client uses the partition pelion_storage to store configuration and credentials. If pelion_storage doesn't exist, Izuma Device Management Client uses the storage partition instead, if Zephyr isn't already using it (CONFIG_SETTINGS=n).

Depending on the architecture, you can put "image_0" and "image_1" on external storage. For better security, keep pelion_storage in internal storage.

For more information about Zephyr's storage partitions, see the Zephyr Project documentation.

As a reference, we've provided a partition overlay for the target frdm_k64f in the pelion-dm-example/pal-platform/SDK/ZephyrOS/boards directory, using this flash layout:

+--------------------------+
|                          |
|         TDBStore         | <-+ "izuma_storage"
|                          |
+--------------------------+
|                          |
|      MCUboot scratch     | <-+ "image_scratch"
|                          |
+--------------------------+
|                          |
|                          |
|Firmware candidate storage| <-+ "image_1"
|                          |
|                          |
+--------------------------+
|                          |
|                          |
|        Active app        | <-+ "image_0"
|                          |
|                          |
+--------------------------+
|                          |
|      Zephyr storage      | <-+ "storage"
|                          |
+--------------------------+
|                          |
|        Bootloader        | <-+ "mcuboot"
|                          |
+--------------------------+

Bootloader

Zephyr OS uses MCUboot as a bootloader.

The example application installs new firmware as "permanent" by default. To use MCUboot's rollback feature, use Kconfig to set CONFIG_IZUMA_UPDATE_PERMANENT=n and Zephyr's DFU commands for interacting with MCUboot.

Note: The build instructions use the default developer keys in MCUboot. For production devices, use secure credentials instead.

Platform Abstraction Layer (PAL)

The PAL implementation uses these Zephyr subsystems in the implementation:

• RTOS:

  • Threads are statically allocated using K_THREAD_STACK_ARRAY_DEFINE with the maximum number of threads and stack sizes set with the compile definitions PAL_THREADS_MAX_COUNT and PAL_STACKS_MAX_SIZE, respectively.
  • Timers use kernel work queues for scheduling timeouts and invoking callbacks.

• Network:

  • Sockets are implemented using Zephyr's POSIX API and are statically allocated with the compile definition PAL_SOCKET_MAX setting the maximum number of sockets.
  • PAL DNS API version 0 is implemented using POSIX getaddrinfo.
  • PAL DNS API version 3 is implemented using DNS Resolve.
  • Asynchronous callbacks are signaled through kernel work queues.

• Storage:

  • Device Management Client's FlashIAP API is mapped through Zephyr's FlashMap API.
  • Device Management Client instantiates multiple FlashIAP drivers to map between Izuma's absolute addresses and Zephyr's partions.

Advanced Kconfig options

To activate the Kconfig, you need to be in the izuma-dm-example folder and run:

west build -t menuconfig --board=frdm_k64f

You can find the configuration options in the Kconfig menu under modules -> izuma-dm. Alternatively, you can pass configuration options on the command-line or set them permanently in the projects configuration file.

Once you have done your changes, remember to S save the configuration. Delete the build folder and rebuild.

Mbed TLS options

Platform Abstraction Layer options