Mender MCU client is an open source over-the-air (OTA) library updater for MCU devices. This demonstration project runs on nRF7002-DK hardware using nRF Connect SDK based on Zephyr RTOS.
This project is used with a nRF7002-DK evaluation board. No additional wiring is required.
The project is built using nRF Connect SDK v3.0.2. There is no other dependencies.
To start using Mender, we recommend that you begin with the Getting started section in the Mender documentation.
To start using Zephyr, we recommend that you begin with the Getting started section in the Zephyr documentation.
To start using nRF Connect SDK, we recommend that you begin with the nRF Connect SDK Get started page. It is highly recommended to be familiar with nRF Connect SDK environment and tools to use this example.
Clone the project and retrieve submodules using git submodule update --init --recursive.
Then start nRF Connect SDK environment and open the project.
Create a new build configuration. Select the SDK, the toolchain and the board target nrf7002dk/nrf5340/cpuapp/ns. Keep the other options empty.
The example application should first be configured to set at least:
CONFIG_MENDER_SERVER_TENANT_TOKENto set the Tenant Token of your account on "https://hosted.mender.io" server.CONFIG_EXAMPLE_WIFI_SSIDto set the SSID of the Access Point.CONFIG_EXAMPLE_WIFI_PSKto set the password of the network.
You may want to customize few interesting settings:
CONFIG_MENDER_SERVER_HOSTif using your own Mender server instance. Tenant Token is not required in this case.CONFIG_MENDER_CLIENT_AUTHENTICATION_POLL_INTERVALis the interval to retry authentication on the mender server.CONFIG_MENDER_CLIENT_UPDATE_POLL_INTERVALis the interval to check for new deployments.CONFIG_MENDER_CLIENT_INVENTORY_REFRESH_INTERVALis the interval to publish inventory data.CONFIG_MENDER_CLIENT_CONFIGURE_REFRESH_INTERVALis the interval to refresh device configuration.
Other settings are available in the Kconfig. You can also refer to the mender-mcu-client API and configuration keys.
Particularly, it is possible to activate the Device Troubleshoot add-on that will permit to display the Zephyr console of the device directly on the Mender interface as shown on the following screenshot.
In order to get the Device Troubleshoot add-on working, additional configuration keys must be defined. This can be achieved by adding troubleshoot.conf to the "Extra Kconfig fragments" of the build configuration.
The application relies on mcuboot and requires to build a signed binary file to be flashed on the evaluation board. The binary file generated by the nRF Connect SDK contains TF-M and the application itself.
Build and flash mcuboot, TF-M and the application using Build and Flash buttons of the Actions panel in the nRF Connect SDK environment.
After flashing the application on the nRF7002-DK evaluation board and displaying logs, you should be able to see the following:
*** Booting MCUboot v2.1.0-dev-ae1ee57f3906 ***
*** Using nRF Connect SDK v3.0.2-89ba1294ac9b ***
*** Using Zephyr OS v4.0.99-f791c49f492c ***
[00:00:00.272,430] <inf> mcuboot: Starting bootloader
[00:00:00.279,235] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.289,306] <inf> mcuboot: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.299,285] <inf> mcuboot: Boot source: none
[00:00:00.304,931] <inf> mcuboot: Image index: 0, Swap type: none
[00:00:02.014,434] <inf> mcuboot: Bootloader chainload address offset: 0x10000
[00:00:02.022,033] <inf> mcuboot: Image version: v0.1.0
[00:00:02.027,648] <inf> mcuboot: Jumping to the first image slot
[00:00:00.065,399] <inf> wifi_nrf: Configuring SLEEP CTRL GPIO control register
*** Booting mender-ncs-example v0.1.0-76982ff14a5e ***
*** Using nRF Connect SDK v3.0.2-89ba1294ac9b ***
*** Using Zephyr OS v4.0.99-f791c49f492c ***
[00:00:00.238,098] <inf> wifi_supplicant: wpa_supplicant initialized
Connected
[00:00:17.894,805] <inf> mender_ncs_example: IPv4 address: 192.168.1.123
[00:00:17.904,052] <inf> mender_ncs_example: Lease time: 43200 seconds
[00:00:17.913,177] <inf> mender_ncs_example: Subnet: 255.255.255.0
[00:00:17.921,936] <inf> mender_ncs_example: Router: 192.168.1.1
[00:00:17.931,243] <inf> mender_ncs_example: MAC address of the device 'f4:ce:36:00:1f:dc'
[00:00:17.942,047] <inf> mender_ncs_example: Running project 'mender-ncs-example' version '0.1.0'
[00:00:17.954,864] <inf> mender_ncs_example: Mender client initialized
[00:00:17.964,202] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/storage/generic/psa_its/src/mender-storage.c (165): Device configuration not available (status=-140)
[00:00:17.983,581] <inf> mender_ncs_example: Mender configure add-on registered
[00:00:17.993,499] <inf> mender_ncs_example: Mender inventory add-on registered
[00:00:18.003,387] <inf> mender_ncs_example: Device configuration retrieved
[00:00:18.013,946] <err> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/tls/generic/psa_crypto/src/mender-tls.c (326): Unable to open key (status=-140)
[00:00:18.031,860] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/tls/generic/psa_crypto/src/mender-tls.c (126): Generating authentication keys...
[00:00:18.164,978] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/storage/generic/psa_its/src/mender-storage.c (98): Deployment data not available (status=-140)
[00:00:18.183,746] <inf> mender_ncs_example: Mender client connect network
[00:00:19.998,077] <err> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-api.c (514): [401] Unauthorized: dev auth: unauthorized
[00:00:20.014,770] <inf> mender_ncs_example: Mender client authentication failed
[00:00:20.024,688] <inf> mender_ncs_example: Mender client released network
Which means you now have generated authentication keys on the device. You now have to accept your device on the mender interface. Once it is accepted on the mender interface the following will be displayed:
[00:10:18.013,214] <inf> mender_ncs_example: Mender client connect network
[00:10:19.869,445] <inf> mender_ncs_example: Mender client authenticated
[00:10:19.878,875] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (902): Checking for deployment...
[00:10:21.291,564] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (910): No deployment available
[00:10:21.306,243] <inf> mender_ncs_example: Mender client released network
[00:10:21.315,795] <inf> mender_ncs_example: Mender client connect network
[00:10:22.626,464] <inf> mender_ncs_example: Mender client released network
[00:10:22.636,077] <inf> mender_ncs_example: Mender client connect network
[00:10:23.930,511] <inf> mender_ncs_example: Mender client released network
Congratulation! Your device is connected to the mender server. Device type is mender-nrf7002dk-ncs-example and the current software version is displayed.
First retrieve mender-artifact tool.
Change VERSION file to VERSION_MAJOR=0 and VERSION_MINOR=2, rebuild the firmware using nRF Connect SDK environment.
Then create a new artifact using the following command line:
path/to/mender-artifact write rootfs-image --compression none --device-type mender-nrf7002dk-ncs-example --artifact-name mender-nrf7002dk-ncs-example-v0.2.0 --output-path build/mender-ncs-example/zephyr/mender-nrf7002dk-ncs-example-v0.2.0.mender --file build/mender-ncs-example/zephyr/zephyr.signed.bin
Upload the artifact mender-nrf7002dk-ncs-example-v0.2.0.mender to the mender server and create a new deployment.
The device checks for the new deployment, downloads the artifact and installs it on the external SPI memory. Then it reboots to apply the update:
[00:20:18.013,214] <inf> mender_ncs_example: Mender client connect network
[00:20:18.022,674] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (902): Checking for deployment...
[00:20:19.941,986] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (929): Downloading deployment artifact with id '3f3bdd04-ac3a-4846-ac07-c094c4922e56', artifact name 'mender-nrf7002dk-ncs-example-v0.2.0' and uri 'https://hosted-mender-artifacts.s3.amazonaws.com/6370b06a7f0deaedb279fb6a/35929122-9a0e-47ce-810a-a8b9f75ad279?X-A
[00:20:21.362,182] <inf> mender_ncs_example: Deployment status is 'downloading'
[00:20:24.320,007] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-artifact.c (374): Artifact has valid version
[00:20:24.341,125] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/flash/zephyr/dfu_target/src/mender-flash.c (48): Start flashing artifact 'zephyr.signed.bin' with size 850068
[00:22:00.251,678] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (941): Download done, installing artifact
[00:22:02.325,531] <inf> mender_ncs_example: Deployment status is 'installing'
[00:22:02.336,608] <inf> dfu_target_mcuboot: MCUBoot image-0 upgrade scheduled. Reset device to apply
[00:22:03.861,602] <inf> mender_ncs_example: Deployment status is 'rebooting'
[00:22:03.871,582] <inf> mender_ncs_example: Mender client released network
[00:22:03.881,469] <inf> mender_ncs_example: Restarting system
uart:~$ [00:00:00.251,617] <inf> spi_nor: mx25r6435f@0: 8 MiBy flash
*** Booting MCUboot v2.1.0-dev-ae1ee57f3906 ***
*** Using nRF Connect SDK v3.0.2-89ba1294ac9b ***
*** Using Zephyr OS v4.0.99-f791c49f492c ***
[00:00:00.272,430] <inf> mcuboot: Starting bootloader
[00:00:00.279,235] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.289,306] <inf> mcuboot: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
[00:00:00.299,224] <inf> mcuboot: Boot source: none
[00:00:00.304,870] <inf> mcuboot: Image index: 0, Swap type: test
[00:00:02.578,491] <inf> mcuboot: Starting swap using move algorithm.
[00:01:33.426,300] <inf> mcuboot: Bootloader chainload address offset: 0x10000
[00:01:33.433,868] <inf> mcuboot: Image version: v0.1.0
[00:01:33.439,514] <inf> mcuboot: Jumping to the first image slot
[00:00:00.065,399] <inf> wifi_nrf: Configuring SLEEP CTRL GPIO control register
*** Booting mender-ncs-example v0.2.0-76982ff14a5e ***
*** Using nRF Connect SDK v3.0.2-89ba1294ac9b ***
*** Using Zephyr OS v4.0.99-f791c49f492c ***
[00:00:00.238,067] <inf> wifi_supplicant: wpa_supplicant initialized
Connected
[00:00:15.988,616] <inf> mender_ncs_example: IPv4 address: 192.168.1.123
[00:00:15.997,863] <inf> mender_ncs_example: Lease time: 43200 seconds
[00:00:16.006,988] <inf> mender_ncs_example: Subnet: 255.255.255.0
[00:00:16.015,747] <inf> mender_ncs_example: Router: 192.168.1.1
[00:00:16.025,024] <inf> mender_ncs_example: MAC address of the device 'f4:ce:36:00:1f:dc'
[00:00:16.035,858] <inf> mender_ncs_example: Running project 'mender-ncs-example' version '0.2.0'
[00:00:16.048,645] <inf> mender_ncs_example: Mender client initialized
[00:00:16.057,983] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/storage/generic/psa_its/src/mender-storage.c (165): Device configuration not available (status=-140)
[00:00:16.077,362] <inf> mender_ncs_example: Mender configure add-on registered
[00:00:16.087,280] <inf> mender_ncs_example: Mender inventory add-on registered
[00:00:16.097,137] <inf> mender_ncs_example: Device configuration retrieved
[00:00:16.131,469] <inf> mender_ncs_example: Mender client connect network
[00:00:17.781,738] <inf> mender_ncs_example: Mender client authenticated
[00:00:17.791,229] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/platform/flash/zephyr/dfu_target/src/mender-flash.c (155): Application has been mark valid and rollback canceled
[00:00:19.203,887] <inf> mender_ncs_example: Deployment status is 'success'
[00:00:19.305,480] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (902): Checking for deployment...
[00:00:20.676,208] <inf> mender: CMAKE_SOURCE_DIR/components/mender-mcu-client/core/src/mender-client.c (910): No deployment available
[00:00:20.690,917] <inf> mender_ncs_example: Mender client released network
[00:00:20.700,469] <inf> mender_ncs_example: Mender client connect network
[00:00:21.971,466] <inf> mender_ncs_example: Mender client released network
[00:00:21.981,079] <inf> mender_ncs_example: Mender client connect network
[00:00:23.505,493] <inf> mender_ncs_example: Mender client released network
Congratulation! You have updated the device. Mender server displays the success of the deployment.
In case of failure to connect and authenticate to the server the current example application performs a rollback to the previous release. You can customize the behavior of the example application to add your own checks and perform the rollback in case the tests fail.
As an alternative to the nRF Connect SDK environement using vscode, it is possible to build the application in a command line. Execute the following commands to initialize a west workspace, build and flash the application.
mkdir workspace
cd workspace
west init -m https://github.com/nrfconnect/sdk-nrf.git --mr v3.0.2
west update
west build -b nrf7002dk/nrf5340/cpuapp/ns path/to/mender-ncs-example
west flash
The Device Troubleshoot add-on permits to display the Zephyr Shell on the Mender interface. Autocompletion and colors are available.
The Device Troubleshoot add-on also permits to upload/download files to/from the Mender server and to perform port forwarding. However, due to limited FLASH memory remaining on the nRF5340, these feature are disabled in the current example.
The communication with the server is done using HTTPS. To get it working, the Root CA that is providing the server certificate should be integrated and registered in the application (see tls_credential_add in the src/main.c file). Format of the expected Root CA certificate is DER.
In this example we are using the https://hosted.mender.io server with an Enterprise account. While checking the details of the server certificate in your browser, you will see that is is provided by Amazon Root CA 1. Thus the Amazon Root CA 1 certificate AmazonRootCA1.cer retrieved at https://www.amazontrust.com/repository is integrated in the application.
Using another instance you may need to integrate another Root CA certificate. Also note depending of the certificate properties you may need to activate additional cipher suites in the TF-M configuration. See below considerations when using trial mender instance for example.
The trial mender instance which is available for free at http://hosted.mender.io to test mender feature requires to integrate the Google Trust Services Root R4 certificate together with Amazon Root CA 1 certificate. This is required because the artifacts are saved on a Cloudflare server instead of the Amazon S3 storage. This is achieved using the secondary root certificate support provided by the mender-mcu-client.
CONFIG_MENDER_NET_CA_CERTIFICATE_TAG_PRIMARY=1
CONFIG_MENDER_NET_CA_CERTIFICATE_TAG_SECONDARY=2
However, TF-M profile type 'small' has only symmetric cipher to keep the size of the binary small. Particularly, the support of ECDSA with SHA384 which is required to parse the Google Trust Services Root R4 certificate need to be added to the configuration. This is achieved using the following configurations.
CONFIG_PSA_WANT_ALG_ECDH=y
CONFIG_PSA_WANT_ALG_ECDSA=y
CONFIG_PSA_WANT_ECC_SECP_R1_384=y
Those configurations are also available using the Kconfig fragment trial.conf in the build configuration.
Copyright joelguittet and mender-mcu-client contributors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.