Device Management Client 2.2.0 General Availability (GA)

Features

• [Mbed OS] Device Management Client provides support for secure storage through KVstore (Internal Flash).
  • Client has added support for KVstore, and the application default configuration will use KVstore.
  • KVstore provides integrated secure storage and support for using internal flash to store all client data, including certificates (originally ESFS content) and other critical data (originally SOTP content).
• PAL porting support improvements.
  • PAL has been refactored to make porting to new platforms more straightforward and allow porting through separate components.
• Pelion-ready PAL porting test suite.
  • PAL porting test implementation has been fixed.
  • PAL porting test executable directly from application level.
• Pelion-ready end-to-end test suite.
  • Platform-agnostic Pelion end-to-end testing suite using Icetea testing framework has been added.
  • These tests verify device registration, device communication with Device Management (GET, PUT, POST and device notifications), updating firmware and device deregistration.

Fixes

Device Management Client example

• Updated to Mbed OS 5.11.4.
• [Mbed OS] Client 2.2.0 has fixed the internal initialization of ns_hal_init(), which fixes the issue of double initialization of memory when using Mesh network stacks.
  • Removed the application configurations of mbed-client.event-loop-size for most configurations. The application uses the default configuration defined in mbed-client, or from Mbed OS for Mesh network stacks.
  • For Wi-Fi stacks, mbed-client.event-loop-size needs to be 2048.
• [Linux] Updated CMake minimum version to 3.5.
• [pal-platform] Deprecated the fullBuild option in build tools.
• [Mbed OS] By default, application configuration updated to use secure storage implementation through KVstore.
  • K66F now uses internal flash for both storing client credentials and the update image.
  • All other boards have been changed to use LittleFS instead of FAT file system by default. FAT file system is not power-loss resilient and should not be used in embedded devices.
  • Old SOTP-ESFS based storage configuration files are still available in the configs/legacy_storage folder.
  • NUCLEO F411RE board still uses SOTP-ESFS implementation, as non-TRNG boards are not yet supported in new KVStore-based storage.
  • Legacy Wi-Fi configuration wifi_esp8266_v4_legacy.json introduced in the 2.1.1 release has been removed.
• Moved the network init call to main() and added network disconnect call to end of main().
• Removed extern block device reference from platform-common.
• Added TESTS/PAL/test.py script to help run PAL porting tests.
• Added basic Device Management acceptance end-to-end tests that use the Icetea test framework.

Device Management Connect client

• Updated Mbed CoAP to 4.7.4.
  • Mbed CoAP for non-Mbed OS platforms is one patch release ahead of the Mbed OS version (5.11.3) of Mbed CoAP.
• Implemented DTLS fragmentation support for Device Management Client.
  • If your device has constraints with network buffer sizes where the DTLS handshake packets cannot fit into the single MTU, this configuration allow smaller packet size (minimum fragment length of 512 bytes + DTLS headers).
  • This feature is supported from MbedTLS 2.15.1 onwards.
  • To enable support, define mbed-client-pal.pal-max-frag-len = <value> in the mbed_app.json file.
  • Value 0 = disabled, 1 = MBEDTLS_SSL_MAX_FRAG_LEN_512, 2= MBEDTLS_SSL_MAX_FRAG_LEN_1024, 3 = MBEDTLS_SSL_MAX_FRAG_LEN_2048.
  • The value must be twice the defined value of SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE, otherwise your client will give a compilation error with mismatching configuration options.
• [Edge] In Edge mode, the client can process more than one request per resource at a time.
• Fixed message status callback handling when using delayed response with the blockwise option.
  • Application received multiple delivered statuses when using blockwise transfer. This issue has now been resolved.
• [Linux] Updated CMake minimum version to 3.5.
• [Mbed OS] Enabled new configuration option for selecting secure storage mechanism : "mbed-cloud-client.external-sst-support":"<null/1>"
  • "mbed-cloud-client.external-sst-support":null means client continues using SOTP-ESFS based storage implementation.
  • "mbed-cloud-client.external-sst-support":1 means client uses KVStore-based storage implementation. This requires Mbed OS 5.11.4 version and higher.
  • By default, it is set to null so older versions of Device Management Client example are binary compatible with this client version.
  • For Linux, client continues using SOTP-ESFS based storage implementation.
• Added a configuration check for the update profile (ARM_UC_PROFILE_MBED_CLIENT_LITE) to prevent accidental usage of LITE profile with Device Management Client.
• Added the pause and resume functionality. The APIs let you change the network interface without deregistering the client. You can also pause the client, for example, for sleeping (with RAM retention).
• Deprecated client APIs that use std::string, including the whole SimpleM2MResourceString and SimpleM2MResourceInt classes.
  • The existing code using these APIs still compiles and works, but gives compiler warnings.
  • This was changed because the code using C++ Standard Template Library (STL) is causing issues in some environments, where the std:: namespace or STL is not available at all.
  • STL also causes large ROM overhead, and disabling it saves ~15 KB on ROM budget, depending on the compiler toolchain used.
  • To remove the deprecated APIs completely, set MBED_CLOUD_CLIENT_STL_API to 0.
• You can now disable the namespace pollution of code that includes MbedCloudClient.h with using namespace std;. The behavior is left unchanged, but you can disable it by setting MBED_CLOUD_CLIENT_STD_NAMESPACE_POLLUTION to 0.
• Fixed regression on the application not receiving value_updated() callback for a POST message to an Object or Object Instance.
• Fixed stack overflow issue with local memory allocation from stack rather than heap when trying to read values from KCM.
• Changed network errors printing in M2MConnectionHandlerpimpl.cpp to use hexadecimal format for easier comparison with mbed-client-pal/Source/PAL-Impl/Services-API/pal_errors.h.
• Modified event API to use uintptr_t types for passing pointers instead of uint32_t for 64-bit compatibility.

Factory Configurator client

• Integration with Mbed OS 5.11 KVStore module.

Device Management Update client

• [Mbed OS] Enabled a new configuration option for selecting the storage location for the Update client update image.
  • "mbed-cloud-client.update-storage":"<mode>"
  • <mode> can be either ARM_UCP_FLASHIAP for internal flash or ARM_UCP_FLASHIAP_BLOCKDEVICE for external flash.
• Fixed the Update client state machine reboot state logic so that the active firmware details are not re-sent if reboot does not happen.
• Enabled a single HTTP request to be sent instead of multiple fragments during file download. Added a flag to guard the writing of the entire update file to pre-allocate space before the file is downloaded. The flag is disabled by default.
• Fixed traces from printing empty values for asynchronous DNS calls.
• Modified the trace and error macros in the manifest manager to use common macros.
• Fixed the race conditions on critical section code in the atomic-queue module.
• Fixed various compiler warnings.
• Update client calls a new pal_plat_osGetRoT function that reads RoT from KVStore.
• Added the possibility of queueing callbacks with an associated context in the Update client scheduler.
• Implemented an Update client scheduler API to post an error. The scheduler executes the error callback in priority over all the other callbacks in the queue.
• Added a compilation check for CoAP buffer size.
• Added trace messages to HTTP source module for debugging purposes.
• Fixed the Update client trace module when mbed_trace is off.
• Removed the accelerated handling of binary comparisons that relied on unaligned access.
• Fixed overflow in the HTTP request header.
• Sanitized module codes in trace messages. Defined a macro that replaces non-printable characters with a dot character. Wrapped module codes in the new macro wherever traces or debug messages are printed.
• Replaced calls to mbed_tracef with calls to tr_debug/tr_error.
• Added a compile time check for non-zero update storage size.
• Fixed page rounding issue in PAL block device.
• Improved trace messages in HTTP resume engine.
• Fixed the event API callback types to match the changes in Update client.

Platform Adaptation Layer (PAL)

• Introduced PAL Secure Storage (SST) APIs.
  • Added Mbed OS configuration for secure storage using KVStore through this API (PAL SST).
• Added more unit tests and clarified error messages in them to help in-platform porting process.
• Added PAL_UNIT_TESTING_NONSTANDARD_ENTRYPOINT for executing unit tests.
• Added pal_osSetRoT API and related pal_plat_osSetRoT functions for SOTP and KVstore.
• Remove obsolete documentation and unnecessary board-specific configuration.
• Added error handling of MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED.
• Fixed error translation in the Linux implementation of pal_plat_getAddressInfo.
• Refactored the flash simulation over file system code out of the generic flash module.
• Refactored the Linux-specific reboot simulation code.

Known issues

Device Management Client example

• The end-to-end device_update test does not yet support Python3. It will be fixed in the next release.
• End-to-end tests may sometimes fail due to apparent connectivity issues 410 (Gone) or 520 (Bad Gateway). These issues will be fixed in future version of the Python SDK. As a workaroud, you can execute the test again.
• [Mbed OS] Setting entropy externally is not yet supported with KVstore-based storage implementation.
• NUCLEO-F411RE board still uses SOTP-ESFS-based implementation as non-TRNG boards are not yet supported in new KVstore-based storage.
• NUCLEO-F411RE UDP is not supported due to known limitations in the X-Nucleo-IDW01M1 shield (https://github.com/ARMmbed/wifi-x-nucleo-idw01m1#known-limitations).

Mbed OS

We recommend going through Mbed OS release notes for known issues and their latest status.

• mbed dm init may fail with error 401 (Invalid API key), if your account does not have a developer certificate. To resolve this, create a developer certificate for your Device Management account.
  • A coming version of Mbed CLI will improve the error tracing and provide a correct error statement.
• mbed dm update prepare may fail with error 401 (Unauthorized) with Mbed CLI versions 1.9.0 or later. As a workaround, you can run mbed dm init with an explicit server address, for example -S https://api.us-east-1.mbedcloud.com.
• Python3 compilation does not work with Mbed OS 5.11.4 or earlier versions.
  • See issues mbed-cli#836, Mbed OS#8146.

Linux

• Firmware update installation for very large images on Raspberry Pi3B or Pi3B+ may fail with mmc0 timeout failure. This is a generic Raspberry Pi3 issue, see RPI issue #2392.
• Firmware update from one Linux distribution version to another does not work. For example, firmware update from Yocto distribution Morty to Rocko is not currently possible, as there are Linux version-dependent files (device tree) in the BOOT partition. Therefore, you must update within one major version of a distribution.
• glibc versions 2.23 and 2.24 have a bug in thread creation. It can cause random crashes with Linux.
  • If possible, update glibc to version 2.25 (or newer). See sourceware issue 20116 for details.
  • We have implemented a workaround for this issue to decrease its likelihood. This issue may still occur under certain circumstances.
• The Device Management Client application must run as root to have access rights to perform the firmware update.
  • This is not the most secure way to handle this issue, so a more secure implementation will come later.
• Yocto distribution has only been tested in developer certificate mode.

Device Management Client 2.2.0 Third Party IP report

Device Management Client uses some open source third-party IP (TPIP). This table lists the TPIP and sources:

You also get more TPIP with the Mbed OS release itself (for example lwIP and FATFS).