mbed-cloud-client-example 4.12.0

.mbedignore

@@ -2,3 +2,5 @@ __*/*
 pal-platform/*
 storage-selector/littlefs/*
 delta-tool/*
+venv/*
+utils/*

CHANGELOG.md

@@ -1,8 +1,14 @@
 # Changelog for Pelion Device Management Client example application
 
+## Release 4.12.0 (01.03.2022)
+
+- Updated to Mbed OS 6.15.1.
+- [Linux] Add a new `define_lwm2m_compliant.txt` that enables communication with a LwM2M compliant service / interoperability (IoP) testing.
+- [Mbed OS] Add a new `mbed_app_lwm2m_compliant.json` that enables communication with a LwM2M compliant service / interoperability (IOP) testing with FRDM K64F device.
+
 ## Release 4.11.2 (01.12.2021)
 
-Updated to Mbed OS 6.15.0.
+- Updated to Mbed OS 6.15.0.
 
 ## Release 4.11.1 (11.10.2021)
 

README.md

@@ -1,4 +1,179 @@
-The full documentation for this example is [available on our documentation site](https://www.pelion.com/docs/device-management/current/connecting/device-management-client-tutorials.html).
+# Device Management Client reference application for connectivity
 
-You can report concerns about the documentation or this SW as issues to [this GitHub repository](https://github.com/PelionIoT/mbed-cloud-client-example/issues).
+The [`mbed-cloud-client-example`](https://github.com/PelionIoT/mbed-cloud-client-example) is a reference application that uses [Pelion Device Management Client library](https://github.com/PelionIoT/mbed-cloud-client) and demonstrates how to build a connectivity application.
+
+## Device Management Client connection tutorial  
+
+This tutorial builds and flashes a Device Management Client application using either Linux (running on a PC) or Mbed OS.   
+The application can then connect to a standard OMA Lightweight M2M server.  
+The application uses developer mode that relies on a developer certificate, which you add to your software binary to allow test devices to connect to the server.  
+In the production, you should use the factory flow.
+
+### Linux
+
+#### Requirements
+
+This requires a Linux PC (64-bit Ubuntu/XUbuntu OS desktop environment).
+See also the [Mbed CLI instructions](https://os.mbed.com/docs/mbed-os/latest/tools/developing-mbed-cli.html).
+
+#### Connecting the device
+
+1. Open a terminal, and clone the example repository to a convenient location on your development environment:
+
+   ```
+   git clone https://github.com/PelionIoT/mbed-cloud-client-example
+   cd mbed-cloud-client-example
+   ```
+
+   <span class="notes">**Note:** If you want to speed up `mbed deploy`, you can remove components that are unnecessary for Linux, such as `mbed-os.lib` and the `drivers/` folder.</span>
+
+2. Deploy the example repository:
+
+   ```
+   mbed deploy
+   ```
+
+3. [Create a developer certificate](#create-developer-cert).   
+
+4. Copy the `mbed_cloud_dev_credentials.c` file to the root folder of the example.
+
+5. Deploy Linux dependencies:
+
+   ```
+   python pal-platform/pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls generate
+   cd __x86_x64_NativeLinux_mbedtls
+   ```
+   **Note: python2 is needed for the above command**
+
+6. Generate `cmake` files based on your configuration and build profile (**Release** or **Debug**):
+
+   - For the **Release** profile:
+     ```
+     cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_lwm2m_compliant.txt
+     ```
+   
+   - For the **Debug** profile:   
+     ```
+     cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_lwm2m_compliant.txt
+     ```
+   - If you want your application to bypass the Bootstrap server and work directly with LwM2M server, please add `DISABLE_BOOTSTRAP` cmake flag:
+     ```
+     cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DDISABLE_BOOTSTRAP=ON -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_lwm2m_compliant.txt
+     ```
+
+7. Compile the application:
+
+   ```
+   make mbedCloudClientExample.elf
+   ```
+   
+8. The build creates binaries under `mbed-cloud-client-example/__x86_x64_NativeLinux_mbedtls`. In both cases, there are subdirectories `Debug` and `Release` respectively created for the two profiles.
+
+9. Run the application (at the respective path, see above):
+
+   ```
+   ./mbedCloudClientExample.elf
+   ```
+
+   You should see a message when the device connects to LwM2M server:
+
+   ```
+   Client registered
+   Endpoint Name: <YOUR_ENDPOINT_NAME>
+   Device Id: <YOUR_ENDPOINT_NAME>
+   ```
+10. If you want to run the application with a clean storage, you can remove the `pal` folder that is created in the location where you run your application. 
+
+
+### Mbed OS
+
+#### Prerequisites
+
+To work with the Device Management Client example application, you need:
+
+* A supported board with a network connection and an SD card attached. Currently FRDM K64F and NUCLEO F429ZI boards are supported.
+* [Serial connection](https://os.mbed.com/docs/latest/tutorials/serial-comm.html) to your device with open terminal connection (baud rate 115200, 8N1).
+* [Arm Mbed CLI](https://os.mbed.com/docs/mbed-os/latest/tools/index.html) installed. See [installation instructions](https://os.mbed.com/docs/latest/tools/installation-and-setup.html).
+  * Make sure that all the Python components are in par with the `pip` package [requirements.txt](https://github.com/PelionIoT/mbed-os/blob/master/requirements.txt) list from Mbed OS.
+* Updated [DAPLink](https://github.com/ARMmbed/DAPLink/releases) software (version 250 or later), if your board uses DAPLink.
+
+#### Connecting the device
+
+1. Clone the embedded application's GitHub repository to your local computer and navigate to the new folder:
+
+    ```
+    mbed import https://github.com/PelionIoT/mbed-cloud-client-example
+    cd mbed-cloud-client-example
+    ```
+
+2. Configure Mbed CLI to use your board:
+
+    ```
+    mbed target <MCU>
+    mbed toolchain GCC_ARM
+    ```
+
+3. [Create a developer certificate](#create-developer-cert).
+
+4. Copy the `mbed_cloud_dev_credentials.c` file to the root folder of the example application.
+
+5. Configure the example application:
+   1. If you want your application to bypass the Bootstrap server and work directly with LwM2M server,
+      please set the `disable-bootstrap-feature` feature to `true` in [mbed_app_lwm2m_compliant.json](https://github.com/PelionIoT/mbed-cloud-client-example/blob/master/mbed_app_lwm2m_compliant.json#L21).      
+   
+      ```
+      mbed-client.disable-bootstrap-feature: true
+      ```
+      
+   2. Currently, the application will always start with a clean storage. 
+      If you want to avoid this, remove the `RESET_STORAGE` from the `"target.macros_add"` line in the `mbed_app_lwm2m_compliant.json`:
+   
+      ```
+      "target.macros_add" : ["LWM2M_COMPLIANT","DISABLE_SERVER_CERT_VERIFY"],
+      ```
+            
+7. Compile the example application:
+
+   ```
+   mbed compile --app-config mbed_app_lwm2m_compliant.json
+   ```
+   For more information about Mbed CLI parameters, please see the [Mbed OS documentation site](https://os.mbed.com/docs/mbed-os/latest/build-tools/mbed-cli-1.html).
+
+8. Flash the binary to the device
+   1. Connect the device to your computer over USB. It's listed as a mass storage device.   
+   2. Drag and drop `mbed-cloud-client-example.bin` to the device, or alternatively add the `-f` flag to the build command (if your device is connected to the build machine). This flashes the binary to the device. You should see the LED blink rapidly; wait for it to stop.
+
+9. Press the **Reset** button to restart the device and reset the terminal.
+10. When the client has successfully connected, the terminal shows:
+
+    ```
+    Client registered
+    Endpoint Name: <YOUR_ENDPOINT_NAME>
+    Device ID: <YOUR_ENDPOINT_NAME>
+    ```
+
+<h3 id="create-developer-cert">Create a developer certificate</h3>
+
+1. Download the server CA certificate from the LwM2M service you want to connect to and copy it to the scripts' folder:
+
+   ```
+   cp <SERVER_CA_CERT_FILE> utils/server_ca_cert.der
+   ```
+
+2. Run the python script `cert_convert.py` to generate a `mbed_cloud_dev_credentials.c` file.
+
+   ```
+   cd utils
+   python cert_convert.py --endpoint <YOUR_ENDPOINT_NAME> --uri <The URI of the bootstrap or Device management service> --use-ca
+   ```
+
+   The script will do the following steps:
+   1. Generate a root CA key and certificate on the first time the script is running. All CA outputs are stored in `CA` folder.
+   1. Generate a private key and a certificate signed by this CA.
+   1. Convert the private key, certificate and the server certificate to a C file.
+   1. All non CA outputs are stored in a folder named `YOUR_ENDPOINT_NAME`.
+
+
+
+    
 

define_lwm2m_compliant.txt

@@ -0,0 +1,70 @@
+cmake_policy(SET CMP0005 OLD)  # definitions escaped explicitly (default)
+cmake_policy(SET CMP0011 OLD)  # policy flow old way (default)
+
+if (NOT (${OS_BRAND} MATCHES "Linux"))
+    message(FATAL_ERROR "define.txt to be used only with Linux builds.")
+endif()
+
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../)
+
+add_definitions(-DMBED_CLOUD_CLIENT_USER_CONFIG_FILE="\\"mbed_cloud_client_user_config.h"\\")
+add_definitions(-DPAL_USER_DEFINED_CONFIGURATION="\\"sotp_fs_config_linux_lwm2m_compliant.h"\\")
+add_definitions(-DTARGET_LIKE_POSIX)
+add_definitions(-DPAL_DTLS_PEER_MIN_TIMEOUT=5000)
+
+#  More ciphers
+add_definitions(-DPAL_MAX_ALLOWED_CIPHER_SUITES=4)
+
+# enable fota
+add_definitions(-DMBED_CLOUD_CLIENT_FOTA_ENABLE=1)
+add_definitions(-DMBED_CLOUD_CLIENT_FOTA_LINUX_SINGLE_MAIN_FILE=1)
+
+# Set to 1 to enable tracing
+add_definitions(-DMBED_CONF_MBED_TRACE_ENABLE=0)
+
+add_definitions(-DMBED_CONF_APP_DEVELOPER_MODE=1)
+
+add_definitions(-DPLATFORM_ENABLE_BUTTON=1)
+add_definitions(-DPLATFORM_ENABLE_LED=1)
+
+add_definitions(-DMBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT)
+add_definitions(-DLWM2M_COMPLIANT)
+add_definitions(-DDISABLE_SERVER_CERT_VERIFY)
+
+add_definitions(-DFOTA_DEFAULT_APP_IFS=1)
+add_definitions(-DTARGET_LIKE_LINUX=1)
+add_definitions(-DFOTA_CUSTOM_PLATFORM=1)
+add_definitions(-DMBED_CLOUD_CLIENT_FOTA_SUB_COMPONENT_SUPPORT=1)
+
+if(RESET_STORAGE)
+    add_definitions(-DRESET_STORAGE)
+endif(RESET_STORAGE)
+
+SET(PAL_TLS_BSP_DIR ${NEW_CMAKE_SOURCE_DIR}/mbed-cloud-client/mbed-client-pal/Configs/${TLS_LIBRARY})
+
+if (${TLS_LIBRARY} MATCHES mbedTLS)
+    add_definitions(-DMBEDTLS_CONFIG_FILE="\\"${PAL_TLS_BSP_DIR}/mbedTLSConfig_Linux_LWM2M_Compliant.h"\\")
+endif()
+
+if(PAL_SIMULATOR_FILE_SYSTEM_OVER_RAM)
+    message(WARNING "You are using simulation of File System over RAM")
+    add_definitions(-DPAL_SIMULATOR_FILE_SYSTEM_OVER_RAM=${PAL_SIMULATOR_FILE_SYSTEM_OVER_RAM})
+endif(PAL_SIMULATOR_FILE_SYSTEM_OVER_RAM)
+
+# This definition controls application automatic reboot if network errors exceed certain limit.
+# Disabled when set to 0.
+add_definitions(-DMAX_ERROR_COUNT=0)
+
+if(ENABLE_DEVICE_SENTRY)
+    add_definitions(-DMBED_CONF_MBED_CLOUD_CLIENT_ENABLE_DEVICE_SENTRY)
+    message("Enable Device Sentry feature")
+    add_definitions(-DMBED_CONF_APP_ENABLE_DS_CUSTOM_METRICS_EXAMPLE)
+    message("Enable Device Sentry example application")
+endif(ENABLE_DEVICE_SENTRY)
+
+# Enable FOTA Update
+option(FOTA_ENABLE "Enable FOTA client module" ON)
+
+if(DISABLE_BOOTSTRAP)
+   add_definitions(-DMBED_CONF_MBED_CLIENT_DISABLE_BOOTSTRAP_FEATURE)
+endif()

mbed-cloud-client.lib

@@ -1 +1 @@
-https://github.com/PelionIoT/mbed-cloud-client/#08d12fb1878c795a7a05770beee485e054bf23b0
+https://github.com/PelionIoT/mbed-cloud-client/#54282bc27ed9c404524e15a0de93dc9a59516f79

mbed-os.lib

@@ -1 +1 @@
-https://github.com/ARMmbed/mbed-os/#4cfbea43cabe86bc3ed7a5287cd464be7a218938
+https://github.com/ARMmbed/mbed-os/#2eb06e76208588afc6cb7580a8dd64c5429a10ce

mbed_app_lwm2m_compliant.json

@@ -0,0 +1,93 @@
+{    
+    "target_overrides": {
+        "*": {
+            "target.features_add"                       : ["BOOTLOADER", "STORAGE"],
+            "target.c_lib"                              : "std",
+            "platform.stdio-baud-rate"                  : 115200,
+            "platform.stdio-convert-newlines"           : true,
+            "platform.stdio-buffered-serial"            : true,
+            "platform.stdio-flush-at-exit"              : true,
+            "rtos.main-thread-stack-size"               : 5120,
+            "events.shared-stacksize"                   : 2048,
+            "events.shared-eventsize"                   : 2048,
+            "update-client.storage-locations"           : 1,
+            "mbed-trace.enable"                         : 0,
+            "nsapi.default-wifi-security"               : "WPA_WPA2",
+            "nsapi.default-wifi-ssid"                   : "\"SSID\"",
+            "nsapi.default-wifi-password"               : "\"Password\"",
+            "target.macros_add"                         : ["LWM2M_COMPLIANT","DISABLE_SERVER_CERT_VERIFY","RESET_STORAGE"],
+            "client_app.pal-user-defined-configuration" : "\"pal_config_MbedOS_LWM2M_Compliant.h\"",
+            "lwip.mem-size"                             : 18432,
+            "mbed-client.disable-bootstrap-feature"     : null,
+            "mbed-client.max-certificate-size"          : 2048
+        },
+        "K64F": {
+            "target.network-default-interface-type"     : "ETHERNET",
+            "target.bootloader_img"                     : "tools/mbed-bootloader-k64f-block_device-kvstore-v4.1.0.bin",		
+            "target.header_offset"                      : "0xa000",
+            "target.app_offset"                         : "0xa400",
+            "target.components_add"                     : ["SD"],
+            "update-client.bootloader-details"          : "0x00007188",
+            "update-client.application-details"         : "(40*1024)",
+            "update-client.storage-address"             : "(1024*1024*64)",
+            "update-client.storage-size"                : "((MBED_ROM_START + MBED_ROM_SIZE - APPLICATION_ADDR) * MBED_CONF_UPDATE_CLIENT_STORAGE_LOCATIONS)",
+            "mbed-cloud-client.update-storage"          : "ARM_UCP_FLASHIAP_BLOCKDEVICE",
+            "storage_filesystem.internal_base_address"  : "(32*1024)",
+            "storage_filesystem.rbp_internal_size"      : "(8*1024)",
+            "storage_filesystem.external_base_address"  : "(0x0)",
+            "storage_filesystem.external_size"          : "(1024*1024*64)",
+            "storage.storage_type"                      : "FILESYSTEM",
+            "storage_filesystem.filesystem"             : "LITTLE",
+            "storage_filesystem.blockdevice"            : "SD"
+        },
+        "NUCLEO_F429ZI": {
+            "target.network-default-interface-type"     : "ETHERNET",
+            "target.bootloader_img"                     : "tools/mbed-bootloader-nucleo_f429zi-internal_flash-no_rot-v4.1.0.bin",
+            "target.header_offset"                      : "0x8000",
+            "target.app_offset"                         : "0x8400",
+            "target.restrict_size"                      : "0xF7C00",
+            "update-client.bootloader-details"          : "0x080078CC",
+            "update-client.application-details"         : "(MBED_ROM_START + MBED_BOOTLOADER_SIZE)",
+            "update-client.storage-address"             : "(MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_BASE_ADDRESS+MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)",
+            "update-client.storage-size"                : "(1024*1024-MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)",
+            "update-client.storage-page"                : 1,
+            "mbed-cloud-client.update-storage"          : "ARM_UCP_FLASHIAP",
+            "storage_tdb_internal.internal_base_address": "(MBED_ROM_START+1024*1024)",
+            "storage_tdb_internal.internal_size"        : "(128*1024)",
+            "storage.storage_type"                      : "TDB_INTERNAL"
+        }
+    },
+    "config": {
+        "developer-mode": {
+            "help"      : "Enable Developer mode to skip Factory enrollment",
+            "options"   : [null, 1],
+            "value"     : 1
+        },
+        "button-pinname": {
+            "help"      : "PinName for button.",
+            "value"     : "BUTTON1"
+        },
+        "led-pinname"   : {
+            "help"      : "PinName for led, which is attached to led blink resource.",
+            "value"     : "LED1"
+        },
+        "bootloader-size": {
+            "help"      : "Helper macro to enable calculation of rom regions. target.header_offset and target.app_offset still needs to be calculated manually, though.",
+            "value"     : "(32*1024)",
+            "macro_name": "MBED_BOOTLOADER_SIZE"
+        },
+        "mbed-trace-max-level": {
+            "help"      : "Max trace level. Must be one of the following: [TRACE_LEVEL_DEBUG, TRACE_LEVEL_INFO, TRACE_LEVEL_WARN, TRACE_LEVEL_ERROR, TRACE_LEVEL_CMD]",
+            "macro_name": "MBED_TRACE_MAX_LEVEL",
+            "value"     : "TRACE_LEVEL_DEBUG"
+        },
+        "mbed-cloud-client-update-buffer-size": {
+            "value"     : null
+        },
+        "enable-ds-custom-metrics-example": {
+            "help"      : "Enable Device Sentry custom metrics example applicaton",
+            "options"   : [null, 1],
+            "value"     : null
+        }
+    }
+}

mbed_cloud_client_user_config.h

@@ -24,7 +24,12 @@
 #define MBED_CLOUD_CLIENT_ENDPOINT_TYPE "default"
 #endif
 
-#define MBED_CLOUD_CLIENT_LIFETIME                  86400
+#define MBED_CLOUD_CLIENT_LIFETIME                  (3*60)
+
+#ifdef LWM2M_COMPLIANT
+#define MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP
+#define MBED_CONF_MBED_CLIENT_MAX_CERTIFICATE_SIZE   2048
+#endif
 
 #if !defined(MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP) && !defined(MBED_CLOUD_CLIENT_TRANSPORT_MODE_TCP) && !defined(MBED_CLOUD_CLIENT_TRANSPORT_MODE_UDP_QUEUE)
 #define MBED_CLOUD_CLIENT_TRANSPORT_MODE_TCP