1. X-CUBE-MATTER
1.1. What is X-CUBE-MATTER?
1.1.1. General description
The X-CUBE-MATTER expansion package provides software components for various STM32 microcontroller development platforms based on Arm® cores. A development platform consists of hardware, either a single board or a combination of two boards. The choice of platform depends on the target network access technology (Thread, Ethernet, Wi-Fi) and the type of Matter device (Matter end device, Matter bridge). Binaries are provided for quick demos.
Key Features:
- Preintegrated Matter SDK: The X-CUBE-MATTER package includes the Matter SDK preintegrated on STM32 microcontrollers. The Matter SDK middleware uses FreeRTOS™, mbedTLS infrastructure, and OpenThread stack. It serves as a reference implementation for demonstration and prototyping a Matter end-device on a reference development platform. Supported STM32 platforms are detailed in the associated wiki article.
- CSA Certification Ready: The package is ready for CSA certification with the default "dimmable light device type" and uses the MATTER OTA protocol to support firmware updates. Other device types are provided as prototypes for evaluation purposes.
- Embedded Hardware Blocks: The STM32 SoC includes most hardware blocks such as Flash, crypto engine, RNG, and RTC. Connectivity technologies like Thread, Bluetooth® LE, Wi-Fi, and Ethernet are supported, either embedded in a standalone SoC or a chipset. Detailed information on supported technologies is available in the wiki article.
Security and Storage:
- Device Credentials and Keys: The project stores device credentials and keys in the STM32 embedded flash memory or an external flash memory, for which X-CUBE-MATTER provides a driver. It offers infrastructures from partners to provision a DAC private key into STM32 secure storage internal flash and provides a related driver for operational networks. Once provisioned, security-sensitive data and operations remain in a secure partition, isolated from the user application.
- Secure Boot Process: The secure boot process acts as a Root of Trust for the application before launching it. It ensures secure firmware updates once a new image is downloaded by the user application..
X-CUBE-MATTER is available for free download from [1] website.
1.1.2. X-CUBE-MATTER versions
The X-CUBE-MATTER versions contain software components and features that are continuously evolving. Refer to the release note included in the package for more details.
1.1.3. Software architecture
1.1.3.1. Overall bloc diagram
1.1.3.2. Components description
The X-CUBE-MATTER software components consist of:
- Core Matter SDK Stack: From connectedhomeip.
- Files Generated by ZAPTool: And tools provided by connectedhomeip.
- FreeRTOS™, mbedTLS, and LwIP: Integrated into the package.
- Adaptation Layers: Either based on components from connectedhomeip but adapted, or modified by ST to run on the STM32 infrastructure.
Software Partitioning The OpenThread stack, Bluetooth® LE stack, and IP stack can be located on the application MCU in the case of a chipset solution or on a dedicated wireless stack coprocessor. The software partitioning for each target platform is detailed in the associated wiki article. Application Examples The delivered application examples as part of the project come with compiled binaries for an out-of-the-box experience. Source codes are provided and can be compiled with supported IDEs. The project can be modified and regenerated using STM32CubeIDE. Release Note For features supported in this version of X-CUBE-MATTER (Matter SDK version, supported applications, and their list of features), refer to the release note included in the package. Low Power Framework When embedded, the low power framework is implemented in the utilities component.
1.1.4. Folders structure
The X-CUBE-MATTER is compliant with STM32CubeFW folders that are drivers, middleware, projects, and utilities, as illustrated in the figure below.
- Drivers folder
The Drivers folder contains the HAL drivers, the board-specific drivers for each supported board or hardware platform (including the onboard components), and the CMSIS vendor-independent hardware abstraction layer. These are STM32Cube firmware components.
- Middlewares folder
The Middleware folder contains two main subfolders:
- - ST subfolder which contains security components used by SBSFU and the STM32_WPAN (Bluetooth® Low Energy, Thread) middleware components for STM32WB platform, and STM32WBA_WPAN component for STM32WBA platform.
- - Third-party subfolder which contains the connectedhomeip source code including the STM platform specific code, the code generated with ZAP Tool common to all cluters (zzz_generated\app-common\zap-generated). Each device/app subfolder contain the code generated with ZAP Tool (devices\Thread\<app>\zap-generated) for a given device type. This subfolder contains also the FreeRTOS™ and mbedtls components common to all platforms and the mcuboot component used by OEMiROT_Boot on STM32WBA6 platform.
- Projects folder
The following figures represent different views of the X-CUBE_MATTER project that respectively show where applications and utilities needed to develop and prototype are located:
- - For STM32WBA65-DK1 platform:
- the binary of the Matter application stored in the X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\<App>\Binaries subfolder of each application without OEMiROT, for an out-of-the-box quick demonstration,
- the binary of the TrustZone application are in the X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\Binary subfolder of each application with OEMiROT, Those binary are not delivered in the package but obtained after build process.
- the ROT_Provisioning subfolder containing OEMiROT features: output binaries and generated images in OEMiROT/Binary, OEMiROT configuration files in OEMiROT/Config, keys for firmware image authentication and encryption in OEMiROT/Keys, image configuration files in OEMiROT/Images, and device provisioning (firmware programming) scripts for OEMiROT TrustZone applications
- the embedded application (STM_Provisioning) provided for device DAC and Private Key provisioning demonstration and that can be customized by Third-Party for secure provisioning during manufacturing.
- - For STM32WB5MM-DK platform:
- the binaries (under X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries subfolder) used to program the M0 core of STM32WB5x based platforms,
- the key used to decrypt the .sfb binary file received from the OTA provider during the software upgrade procedure. It is located in the...\2_Images_SECoreBin\Binary folder
- the binary of the Matter application stored in the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\”App”\Binaries subfolder of each application and to be used to program the M4 core,
- the binaries of the Matter application with SBSFU (SBSFU_"App"-SBSFU.bin and "App"-SBSFU.sfb) in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Window-App-SBSFU\Binary subfolder of each application and to be used to program the M4 core are generated after build process,
- the embedded application (STM_Provisioning) provided for device provisioning demonstration and that can be customized by Third-Party for secure provisioning during manufactoring.
- Utilities folder
The .zip file in the APK subfolder contains the CHIPTool application used as commissioner and controller in STM or RPi ecosystems. This CHIPTool could be also as OTA provider for device firmware upgrade. It has been generated using source code from CSA GitHub. It is provided for convenience. Be aware that it does not run on every Android platform as it has been built for Arm64 CPU based devices and Android 8 or later is required.
The OTA_Tools subfolder contains scripts provided in X-CUBE-MATTER for OTA firmware update over Matter. The subfolder chip within OTA_Tools contains functions coming from connectedhomeip\src\controller\python\chip\tlv and used by these scripts.
The DataFactory subfolder contains a programming PC tool used to manage factory data for device test or provisioning and a readme file explaning how to use the tool. For more details on this tool, refer to the dedicated wiki article Matter device factory data provisioning Matter device factory data provisioning.
1.2. Matter end devices (ED)
1.2.1. Customize the ED project
This demonstration uses applications delivered with X-CUBE-MATTER, but the user can do any needed customization (for example: modification of Bluetooth® LE discriminator) and recompile the project. For how to modify discriminator, refer to the section BLE discriminator modification
Follow the following steps:
Step 1: Select the network interface technology (Thread®, Wi-Fi®)
Step 2: Select an ED platform supporting the chosen network interface technology
- ED platforms supporting Thread
- ED platform supporting Wi-Fi
Step 3: Get the X-CUBE-MATTER
Step 4: Customize the application and regenerate binary using STM32CubeIDE. From X-CUBE-MATTER v1.1.1, application customization can be also done using STM32CubeMx. The .ioc and .extSettings files are provided in each Matter application folder (X-CUBE-MATTER\Projects\<STM32 platform>\Applications\Matter\<App>). Currently, only STM32WB55 supports STM32CubeMX.
Step 5: Program firmware (the generated one for the application and the delivered ones for a coprocessor core) into the platform cores as indicated in End devices How To
Step 6: From now, the device can be commissioned in Matter Fabric and ecosystems presented in Test and demonstrate.
1.2.2. Develop your own application
This section explains how to start developing your Matter device by generating cluster source files in the ZAP tool. One subsection is dedicated to installing the necessary tools. Then, integration into ST's X-CUBE-MATTER package is shown.
ZCL advanced platform (ZAP) is a code generation engine and user interface for applications and libraries based on a Zigbee Cluster Library, one of the specifications developed by CSA. On top of this, CSA provides a set of scripts and templates that modify this tool so that it can be used with the Matter standard instead of the original Zigbee one. See the X-CUBE-MATTER release notes for the correct ZAP tool version to be used.
1.2.2.1. Windows system setup for ZAP (one-time)
Before proceeding to work on a project, several tools need to be installed. These include the STM32CubeIDE to work with and compile the project, and the additional X-CUBE-MATTER package that is dedicated to Matter and contains examples and some ST-specific implementation.
These steps, as shown, have been tested on a Windows system. For Linux / MacOS, they are similar, apart from the version of ZAP tool, which is platform-dependant. The Linux version uses a Pyhton library called fcntl instead of PORTALOCKER in step Environment configuration and does not require modifications.
Install Python
Install the latest version of Python 3.x. Python should be added to the system PATH.
Install Git
Another command-line interface can be used. For Git Bash, download and install from the Git website.
Download the connectedhomeip repository and the ZAP tool
- Create a folder [ConnectedHomeIP] where to store the connectedhomeip repository, for example “C:\chip-matter-tools”
- Download the repository from connectedhomeip with tag 1.4.0.0 and extract the content into the created folder [ConnectedHomeIP].
- The ZAP tool can be found here. The specific release needs to be compatible with the files included in the X-CUBE-MATTER package - v2024.08.14-nightly has been tested. Newer / older versions might generate source code which would not be possible to compile. Extract to a sub-folder of [ConnectedHomeIP] that could be named for instance “zap-win-x64”.
Environment configuration
Run Git Bash or another command-line interface as administrator. Make sure to update the Python pip component with the command:
python.exe -m pip install --upgrade pip
Then install all the necessary packages using pip:
pip install portalocker click lark jinja2 stringcase coloredlogs
One of the ZAP files needs to be modified to work on Windows (as one of the originally used packages, fcntl, is not available on Windows). Open connectedhomeip\scripts\tools\zap\generate.py and modify the following lines:
- line 19 (original vs modified):
import fcntl
import portalocker
- line 337 (original vs modified):
fcntl.lockf(self.lock_file, fcntl.LOCK_EX)
portalocker.lockf(self.lock_file, portalocker.LOCK_EX)
- line 343 (original vs modified):
fcntl.lockf(self.lock_file, fcntl.LOCK_UN)
portalocker.lockf(self.lock_file, portalocker.LOCK_UN)
It is advised to create a separate folder for files generated by ZAP, for example, C:\chip-matter-tools\zap_gen_files.
1.2.2.2. Starting project
After you generate the configuration files for your Matter device, you need to integrate them into a project. Currently, only Thread technology is supported in the examples. You can start from one of the examples available in the X-CUBE-MATTER package and modify the files similarly to how it is shown here. The projects can also be copied in place (into the same directory); this way, you can keep the original project and modify a copied version.
Basic functionality can be achieved based on the lighting-app project. You can also use the project Lighting-App-SBSFU if you want update-over-the-air capability ("#define OTA_SUPPORT" needs to be set to 1). In all cases, the steps are very similar to what is described here.
1.2.2.3. Generate files in ZAP
In this section, we show how to set your device's clusters and export the basic code in ZAP. When integrated into a project, this code dictates how the device is seen by the Matter network. It also defines all of its basic functionality, which is specified by the standard. Run Git Bash or another command-line interface. Export the ZAP path to the environment with:
export ZAP_INSTALL_PATH=C:/chip-matter-tools/zap-win-x64
This need to be done at every Bash launch. Change to Matter directory, for example,
cd ../../C:/chip-matter-tools folder/connectedhomeip
and launch ZAP from here, starting from one of the example projects:
./scripts/tools/zap/run_zaptool.sh examples/light-switch-app/light-switch-common/light-switch-app.zap
Modify the project in the GUI according to your device needs and specifications:
- Select a device/endpoint from the device library specification.
- See which clusters are mandatory/optional for a given endpoint and enable them.
- For each cluster, there are also mandatory and optional attributes and commands. For example, long press for a generic switch.
Save as a new file, for example, to C:\chip-matter-tools\zap_gen_files\my_light\light.zap. Then, click on the Generate button to produce source files. These files consist of generic ZAP templates for the device. Close the GUI, but keep the Bash open.
1.2.2.4. Matter code generation
Apart from the source files generated in the previous section, you also need to generate Matter-specific .c files. These files are used to expose Matter callbacks from each cluster to other clusters and to the user application, thus enabling communication between them.
In the Bash command line, convert the .zap file into a .matter one using the following:
python ./scripts/tools/zap/generate.py ../zap_gen_files/my_light/light.zap -o ../zap_gen_files/my_light/
and generate the two files containing callback definitions:
python ./scripts/codegen.py --generator cpp-app --output-dir ../zap_gen_files/my_light/ ../zap_gen_files/my_light/light.matter
1.2.2.5. Integrate code into STM32CubeIDE
Here, we add the generated cluster code and definitions from the previous section into a new X-CUBE-MATTER project.
In File explorer, navigate to the folder X-CUBE-MATTER\middlewares\Third_Party\connectedhomeip\devices\. Copy the selected 'template' folder (one of the existing '...-app' folders) in here and rename it to my_light-app. Copy part of the files generated in the previous step into my_light-app\zap-generated:
- access.h
- callback-stub.cpp
- cluster-init-callback.cpp
- endpoint_config.h
- gen_config.h
- IMClusterCommandHandler.cpp
- PluginApplicationCallbacks.h
Next, go to X-CUBE-MATTER\Projects\<STM32 platform>\Applications\Matter\. Copy-paste the selected 'template' folder (one of the existing '...-App' folders) in this location and rename it to my_light-app. Copy the file generated in the previous step into my_light-app\Codegen\app:
- PluginApplicationCallbacks.h
Keep open the target folders in file explorer for now. Open the project in STM32CubeIDE, rename it to my_light-app, and keep 'update references'.
Open Middlewares\connectedhomeip\devices\Lighting-app\zap-generated\, delete the existing files (which unlinks them from the project). Next, rename the 'Lighting-app' folder (under 'devices') to 'my_light-app'. Drag-and-drop the following files. Choose 'Link to files' and 'Create link locations relative to PROJECT_LOC'.
- access.h
- callback-stub.cpp
- cluster-init-callback.cpp
- endpoint_config.h
- gen_config.h
- IMClusterCommandHandler.cpp
- PluginApplicationCallbacks.h
Open the structure Middlewares\Third_Party\connectedhomeip\src\app\clusters\ in STM32CubeIDE and the folder X-CUBE-MATTER\Middlewares\Third_Party\connectedhomeip\src\app\clusters\ in the file explorer. Also, open the file PluginApplicationCallbacks.h that was copied before. For each callback in the .h file, check if the corresponding folder is included in STM32CubeIDE. If the needed subfolder is not present, follow these steps:
- Find the folder. For example, MatterBasicInformationPluginServerInitCallback corresponds to the basic-information subfolder.
- Drag and drop the folder from the file explorer into the Middlewares\Third_Party\connectedhomeip\src\app\clusters\ folder in STM32CubeIDE.
- Choose 'Link to files' and 'Create link locations relative to PROJECT_LOC'.
If there is a cluster subfolder that is not specified in PluginApplicationCallbacks.h, you can delete the cluster subfolder.
In the project properties (Alt+Enter), open C\C++ Build\Settings\MCU G++ Compiler\Include paths and modify (near the end of the list) Middlewares\Third_Party\connectedhomeip\devices\Lighting-app to Middlewares\Third_Party\connectedhomeip\devices\my_light-app.
1.2.2.6. Code modifications
Several device parameters (for example, name, serial number) can be changed as explained in How to customize your application. Functionality based on the target platform (second user button, LEDs, etc.) can also be added.
Application-specific functions should be modified to reflect the needs of your device. For this purpose, you can create new Manager.cpp and Manager.h files based on the LightingManager.cpp and LightingManager.h files. Then you need to update references to these files and functions in files like AppTask.cpp and ZclCallbacks.cpp. AppTask.cpp provides interaction between individual application components. ZclCallbacks.cpp serves as an interface between the Matter stack and your application. Callbacks defined here call the functions in the Manager.cpp file.
1.2.2.7. Program the application
After modifying the source files, you can generate the project in STM32CubeIDE. Then, program firmware (the generated one for the application and the delivered one for the coprocessor core) into the platform's cores as indicated in End devices How To. From now, the device can be commissioned in the chosen Matter Fabric ecosystems presented in Test and demonstrate.
1.2.3. End device hardware platforms
1.2.3.1. Platforms supporting Thread technology
1.2.3.1.1. STM32 platforms used as Matter device
- STM32WBA65I-DK1 Discovery kit[1]
The USB cable (USB Type-A or USB Type-C® male to USB Type-C® male) from the PC is used to power and interact with the STM32.
Hardware configuration: Jumper JP4 on pins [1-2] to use the USB STLINK as the 5V power source (this is the default configuration).
- STM32WB5MM-DK Discovery kit[2]
The USB cable (USB Type-A male to USB Type-B male) from the PC is used to power and interact with the STM32.
Hardware configuration: Jumper JP2 on pins [1-2] to use the USB STLINK as the 5V power source (this is the default configuration).
1.2.3.1.2. STM32 platforms used as RCP
- NUCLEO-WBA55CG Nucleo board[3]
The USB cable (USB Type-A or USB Type-C® to USB Type-C® cable) from the PC is used to power and interact with the STM32.
Hardware configuration: Jumper JP1 on pins [1-2] to use the USB STLINK as the 5V power source (this is the default configuration).
- NUCLEO-WB55RG Nucleo board[4]
The USB cable (USB Type-A male to USB Type-B male) from the PC is used to power and interact with the STM32.
Hardware configuration: Jumper JP1 on pins [7-8] to use the USB STLINK as the 5V power source (this is the default configuration).
1.2.3.2. Platforms supporting Wi-Fi technology
Coming soon.
1.2.4. End devices How To
This section covers both STM32 platforms used as Matter devices and those used as RCP.
1.2.4.1. How to program firmware on an STM32WBAx platform
1.2.4.1.1. How to program firmware on an STM32WBA6
The STM32WBA65I-DK1 platform is based on OEMiROT for secure boot and secure firmware updates. In X-CUBE-MATTER V1.4.0 OEMiROT project example is delivered only for the Lighting-App application. All the code running on the STM32WBA6-based end device is delivered as source code and binaries for embedded application examples. If you want to use your own application, use STM32CubeIDE to build it for STM32WBA65RI. There are two types of binaries delivered in X-CUBE-MATTER for the STM32WBA65I-DK1 platform out-of-the-box demonstration:
- Binaries without TrustZone for all embedded applications. These examples do not support OTA firmware updates,
- Binaries with TrustZone for Lighting-App application. This example supports OTA firmware updates.
1.2.4.1.1.1. How to program the firmware without TrustZone on STM32WBA65I-DK1
Use STM32CubeProgrammer to program the binary without TrustZone available in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\<App>\Binaries folder at the start address: 0x0800 0000, <App> being the chosen application (Lighting-App, Window-App or Generic-Switch-App)
1.2.4.1.1.2. How to program the firmware with TrustZone on STM32WBA65I-DK1
PC scripts used to program the device are delivered in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning\OEMiROT folder
- Binaries with TrustZone in X-CUBE-MATTER
The following binaries for secure and non-secure application parts are generated in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\Binary folder as illustrated in the Projects folder structure section of this article:
- - oemirot_tz_ns_app.bin, oemirot_tz_ns_app_enc_sign.bin and oemirot_tz_ns_app_init_sign.bin for the non-secure part (Matter application)
- - oemirot_tz_s_app.bin, oemirot_tz_s_app_enc_sign.bin and oemirot_tz_s_app_init_sign.bin for the secure part (secure boot secure firmware update)
The binaries oemirot_tz_x_app.bin, oemirot_tz_x_app_init_sign.bin and oemirot_tz_x_app_enc_sign.bin are respectively the clear binary used to generate the two other signed ones, the signed and padded version for first boot, and the signed and non-padded version for software update (OTA).
- PC scripts used to program TrustZone binaries
In X-CUBE-MATTER V1.4.0, two Linux scripts (regression.sh and provisioning.sh) delivered in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning\OEMiROT folder, are used to program the firmware on the device. On a Windows system that does not support .sh scripts natively, a third-party application such as Git BASH, WSL, MinGW, Cygwin or any other proper one, need to be used to launch the scripts.
- - regression.sh script
- This script performs the full regression of the device. It prepares the device by setting the relevant values of options bytes such as the write protection byte and activate the TrustZone. It must always be executed before the provisioning.sh (for example, to program a new image).
- The following figures show the start of the regression script (from the Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT folder) and its successful execution.
- STEP 1: Launch STM32_CubeProgrammer, set the ST-LINK "Mode" to "Hot plug" and connect to the STM32 board
- STEP 2: Verify the following "Options Bytes" values. If they are not correct, update them and click “Apply”.
- - provisioning.sh
- This script performs the actual device programming process. It writes the secure and non-secure firmware at the right place in the internal flash memory.
1.2.4.1.2. How to program the NUCLEO-WBA55CG as RCP
To program the NUCLEO-WBA55CG platform, generate the RCP binary (not included in any X-CUBE-MATTER delivery) using STM32CubeWBA, and use STM32CubeProgrammer to program the Arm® Cortex®-M33 CPU at the start address: 0x0800 0000. For the RCP binary generation:
- Download the STM32CubeWBA firmware from st.com.
- Go to the Thread_RCP directory (STM32Cube_FW_WBA_V.../Projects/NUCLEO-WBA55CG/Applications/Thread/Thread_RCP).
- Choose your preferred code generation platform (for example, STM32CubeIDE) and use it to generate the Thread_RCP binary.
1.2.4.2. How to program firmware on an STM32WB5x platform
The STM32WB combines an Arm Cortex®-M4 for the application, plus a 2.4 GHz radio subsystem and an Arm Cortex®-M0+ processor running the firmware upgrade service (FUS) and the wireless stack (Bluetooth® Low Energy - Thread for Matter application).
Programming the STM32WB5x involves updating the FUS if needed and programming the two CPU cores (M0+ first, then M4).
If the M0 is reprogrammed after the M4 is programmed, M4 must be reprogrammed again. Refer to the sections dedicated to the programming of those cores: How to program the M0+ and How to program the M4.
Before starting FUS, M0, and M4, check if the STLINK firmware version is the latest and upgrade if needed using STM32CubeProgrammer[5].
In the Matter context:
- NUCLEO-WB55RG or NUCLEO-WBA55CG is used as a radio coprocessor (RCP) that could be combined with an STM32MP1 to form an OTBR.
- STM32WB5MM-DK is used as a Matter end device.
1.2.4.2.1. How to program the M0+ core
All the code running on Arm Cortex®-M0+ is delivered as an encrypted binary, and it is necessary to upgrade the wireless stack before developing a project on the application side.
The STM32WB is preloaded with root security system firmware (firmware update service FUS) necessary to authenticate the selected wireless stack (binary encrypted format) loaded by the customer on st.com. If the out-of-the-box embedded version of the FUS is not the latest one, the FUS must be updated.
The firmware upgrade service (FUS) and Bluetooth® Low Energy-Thread wireless stack can be updated using STM32CubeProgrammer software[5]. More information about the FUS can be found on the dedicated Firmware Upgrade Services wiki article. Alternatively, it can also be found within the firmware upgrade service for STM32WB series application note AN5185: FUS for STM32WB.
1.2.4.2.1.1 How to update the FUS
The FUS (firmware upgrade services) is firmware that runs on STM32WB the Cortex®-M0+ and offers the following features:
- Install, upgrade, or delete STM32WB Cortex®-M0+ wireless stack
- FUS self-upgrade
- Customer authentication key management
- User key management
- Communication with Cortex®-M4 (user code or bootloader)
The steps described below are needed to update the FUS of NUCLEO-WB55RG and STM32WB5MM-DK Discovery platforms.
Open the release notes for STM32WB_Copro_Wireless_Binaries included in the downloaded X-CUBE-MATTER delivery: …\STM32WB-Matter-BLE-Thread\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\Release_Notes.html.
Open the STM32CubeProgrammer[5] version indicated by the release notes.
Connect physically your development platform to the PC running STM32CubeProgrammer.
Connect your platform using STM32CubeProgrammer[5].
Start FUS
When connected, go to the firmware upgrade services interface, and start the FUS, by clicking on the associated button.
Once the FUS has started correctly, the following logs should be visible on the CubeProgrammer logs interface.
Read FUS
Once the FUS is started read its value by clicking the Read FUS infos button
Update firmware upgrade service binary
The latest version of the FUS can be found in STM32CubeWB MCU package[6].
Start addresses and versions are given as an example. Check the release notes to find the latest FUS version and the FUS start address.
If the FUS version of your platform is different to the version specified in the release notes, proceed to the FUS update by following the steps below:
- If the platform FUS version is 0.5.3, use the dedicated binary:
STM32Cube_FW_WB_V[...]\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_FUS_fw_for_fus_0_5_3.bin
.
- If the platform FUS version is different to 0.5.3, then use the other binary: STM32Cube_FW_WB_V[...]\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_FUS_fw.bin
. Complete the file path with the correct file and add the start address (see release notes). Click on Firmware Upgrade.
A popup appears to confirm that the upgrade is correct.
Check new FUS version
Check the new FUS version by clicking on the Read FUS info button.
1.2.4.2.1.2 How to update the coprocessor wireless stack (BLE-Thread or Thread RCP)
The Bluetooth® LE-Thread Stack (stm32wb5x_BLE_Thread_light_dynamic_fw.bin) for STM32WB5MM-DK, or the Thread stack for NUCLEO-WB55, can be updated in the same way as the FUS.
First, check the start address of the stack in the release notes within the X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x folder, for X-CUBE-MATTER version 1.0.X From X-CUBE-MATTER version 1.1.0 refer to STM32CubeWB for the start address of the stack
Note that the addresses in the pictures below are given for illustration but they can be different for different versions of software, so refer as indicated to the release note for actual addresses values.
Select the type of stack to be loaded :
- For NUCLEO-WB55 platform acting as an RCP the M0 stack to be used is generated from STM32CubeWB.
- For STM32WB5MM-DK Discovery platform acting as Matter End Device, the M0 stack to be used is: ...\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_BLE_Thread_light_dynamic_fw.bin.
Check the First install checkbox if it is the first time you are installing the stack on your platform.
After having programmed the M0 and before programming the M4, ensure that the wireless stack is started by clicking on theStart Wireless Stack button.
1.2.4.2.2. How to program the M4 core
- Programming M4 on end device STM32WB5MM-DK
All the code running on the Arm Cortex®-M4 on end device is delivered as source code and binaries for embedded application examples. If you want to use your own application, use STM32CubeIDE to build it for M4. Use STM32CubeProgrammer to flash M4 with application at the start address: 0x0800 0000.
- Programming M4 on NUCLEO-WB55RG as RCP
For RCP only the binary (Thread_RCP.bin) is delivered. Use STM32CubeProgrammer to program M4 with the delivered binary at the start address: 0x0800 0000.
1.2.4.3. How to customize your application
1.2.4.3.1. Bluetooth® LE discriminator modification
Modifying the Bluetooth® LE discriminator allows avoiding conflict when provisioning multiple end devices configured with the same discriminator. The procedure is the following:
- Modify the below parameters in the firmware:
- In ...\X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\XXX-App\Core\Inc\CHIPProjectConfig.h for STM32WBA65I-DK1, or ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App\Matter\Inc\CHIPProjectConfig.h for STM32WB5MM-DK, where XXX-App is the Matter application (for example Lighting-App):
- Modify the value of the #define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR: for example, replace the default value 0xF00 (3840 in decimal) by 0xA00 (2560 in decimal):
- In ...\X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\XXX-App\Core\Inc\CHIPProjectConfig.h for STM32WBA65I-DK1, or ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App\Matter\Inc\CHIPProjectConfig.h for STM32WB5MM-DK, where XXX-App is the Matter application (for example Lighting-App):
#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 0xA00
- In ...\X-CUBE-MATTER\Projects\<STM32 platform>\Applications\Matter\XXX-App\STM32_WPAN\App\app_ble.c, where <STM32 platform> is the end device platform (for example, STM32WBA65I-DK1) and XXX-App is the application (for example Lighting-App):
- Update the discriminator value in the a_AdvData table for STM32WBA65I-DK1, or in the manuf_data table for STM32WB55MM-DK (replace "0x00, 0x0F" by "0x00, 0x0A"):
- In ...\X-CUBE-MATTER\Projects\<STM32 platform>\Applications\Matter\XXX-App\STM32_WPAN\App\app_ble.c, where <STM32 platform> is the end device platform (for example, STM32WBA65I-DK1) and XXX-App is the application (for example Lighting-App):
uint8_t a_AdvData[15] = { 0x02, 0x01, 0x06, 0x0B, 0x16, 0xF6, 0xFF, 0x00, 0x00, 0x0A, 0xF1, 0xFF, 0x04, 0x80, 0x00, };
uint8_t manuf_data[15] = { 0x02, 0x01, 0x06, 0x0B, 0x16, 0xF6, 0xFF, 0x00, 0x00, 0x0A, 0xF1, 0xFF, 0x04, 0x80, 0x00, };
- Rebuild the project
- Program the device with the Binary1 and reset the device
- Find the QR code link in the UART LOG and click on to show the new QR code.
Note: Currently, BLE Advertising data have to be updated manually to match with Factory Data (Discriminator, VendorID, ProductID).
1.2.4.3.2. Serial number modification
- In ...\X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\XXX-App\Core\Inc\CHIPProjectConfig.h for STM32WBA65I-DK1, or ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App\Matter\Inc\CHIPProjectConfig.h for STM32WB5MM-DK, where XXX-App is the Matter application (for example Lighting-App):
- Modify the value of the #define CHIP_DEVICE_CONFIG_TEST_SERIAL_NUMBER
- Rebuild the project
- Program the device with the Binary1 and reset the device
1.2.4.4. How to perform remote firmware update (OTA) over Matter
1.2.4.4.1. Firmware update procedure overview
The following figure shows the update procedure from the .ota file preparation to the programming of the end device (ED) with the new firmware.
- First step: Generate the .ota file to be downloaded to the device
- Second step: Upload the .ota file to the OTA Provider
- Third step: The OTA provider announces the availability of new FW to OTA Requestor (ED). The ED download the .ota file using BDX protocol, processes the received .ota by copying on the fly it into the external flash for WB55 and internal flash for WBA6. Once the file is fully copied to flash memory then the OTA requestor triggers the installation of the image(s) into the internal flash using the Secure FW update services.
1.2.4.4.2. Firmware update environment overview
One can distinguish two environments corresponding respectively to a Raspberry Pi and an Android smartphone as OTA Provider.
- Raspberry Pi as OTA Provider
In this case, the OTA Provider and Matter Commissioner/Controller are virtual devices hosted on a Raspberry Pi 4. The OTA Provider is connected to Terminal B, and the Matter Controller, which uses CHIP Tool, is linked to Terminal A. These terminals serve as interfaces for monitoring and controlling the OTA process. The OTBR (Open Thread Border Router) sits at the center, connects the Thread network to “virtual” devices over Local IP-based network. The End device (e.g. STM32WBA65I-DK1 Discovery kit) serves as the OTA Requestor, connected to Terminal C via an STLINK.
- Android smartphone as OTA Provider
In this case, a CHIPTool APK from version 1.3 is installed on the Android smartphone and will be used as OTA Provider and Matter Commissioner/Controller. The smartphone connects directly to the end device during BLE phase of commissioning, then uses the IP network (WiFi/Ethernet router) for device control and firmware update. The End device (e.g. STM32WBA65I-DK1 Discovery kit) serves as the OTA Requestor, connected to a Terminal via an STLINK for log display.
1.2.4.4.3. Raspberry Pi preparation
For Raspberry Pi (including RCP dongle) setup procedure, follow CSA instructions given in the Matter Test-Harness User Manual
Note: How to SSH terminals from Raspberry Pi to PC to run the OTA.
- Make sure PC and Raspberry Pi are on the same network.
- 1. Enable the SSH server on Raspberry Pi
- a. Enter sudo raspi-config in a terminal window
- b. Select Interfacing Options
- c. Navigate to and select SSH
- d. Choose Yes
- e. Select Ok
- f. Choose Finish
- a. Enter sudo raspi-config in a terminal window
- 2. Check the ip address using the following command on Raspberry Pi
ifconfig
- 3. On the PC, open command prompt and use the following command
$ ssh <username>@<ip address>
- 4. Enter your account password when prompted.
You should now see the Raspberry Pi command prompt
1.2.4.4.4. How to generate the .ota file
1.2.4.4.4.1 How to generate the .ota file - STM32WBA6 based devices
STEP 1: New firmware version preparation
Matter over-the-air (OTA) on STM32WBA6 is based on OEMiROT project, which is a TrustZone application composed of:
- - A secure application started after boot process and responsible of the security configuration and the nonsecure application startup
- - A nonsecure application that is the Matter application with minor adaptations for OTA. In X-CUBE-MATTER V1.4.0, the Lighting-App application is used as an example.
To prepare a firmware update, the firmware version needs to be increased for both OEMiROT and Matter.
- - OEMiROT version increase:
- Increment the field Version in the file X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning\OEMiROT\Images\OEMiROT_NS_Code_Image.xml (e.g. replace "<Value>1.0.0</Value>" by "<Value>2.0.0</Value>")
- - Matter version increase:
- Increment the define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\NonSecure\Core\Inc\CHIPProjectConfig.h (e.g. replace #define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION 1 by #define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION 2), and the define X_CUBE_MATTER_VERSION in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\NonSecure\Core\Inc\app_entry.h (e.g. replace #define X_CUBE_MATTER_VERSION "v1.4.0_OEMIROT_v1" by #define X_CUBE_MATTER_VERSION "v1.4.0_OEMIROT_v2")
STEP 2: Binary generation
STM32CubeIDE V1.18.0 is used to generate the TrustZone binaries by building the following two projects in sequence:
- The OEMiROT_Boot project
- The OEMiROT_Appli_TrustZone project made of 2 sub-projects (OEMiROT_AppliTrustZone_NonSecure and OEMiROT_AppliTrustZone_Secure), but one just need to build the non-secure part, then the secure part is automatically built.
For a device based on a STM32WBA, there are two types of binaries: the secure application binary and the non-secure application binary, with for each three variants (a clear one used to generate the two other ones, a signed and padded one used for initial device programing, and a signed not padded one used for OTA).
At the end of the (successful) build process the six binaries (oemirot_tz_ns_app.bin, oemirot_tz_ns_app_enc_sign.bin, oemirot_tz_ns_app_init_sign.bin, oemirot_tz_s_app.bin, oemirot_tz_s_app_enc_sign.bin and oemirot_tz_s_app_init_sign.bin) are generated and put in the X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\Binary folder.
STEP 3: Generate the .ota file
The update of the secure application is not supported in the current version of X-CUBE-MATTER, meaning that only the non-secure part will be updated. Only the signed not padded newly generated binary will be used for this purpose. Two Python scripts (CreateMatterBin.py and ota_image_tool.py) provided in X-CUBE-MATTER\Utilities\OTA_Tools are used .ota file generation:
- - CreateMatterBin.py
- This tool from STMicroelectronics is used in the first step to generate an intermediate binary by assembling a header and one or two binary files. In the current X-CUBE-MATTER version only one binary file (the non-secure application binary) is used.
- To run the python script, follow the below steps:
- Open Command Prompt on the PC.
- Browse to X-CUBE-MATTER\Utilities\OTA_Tools directory.
- Run the below command.
python.exe ./CreateMatterBin.py -bin1 ...\X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT\OEMiROT_Appli_TrustZone\Binary\oemirot_tz_ns_app_enc_sign.bin -o myMatter-fw.bin
Note: Make sure to include full path of the input binary. The output binary will use a default name if -o option is not used.
The output myMatter-fw.bin of this python script (default name if -o option is not used) is input to next tool.
The output file gets stored in (X-CUBE-MATTER\Utilities\OTA_Tools) folder
- - ota_image_tool.py: this tool from CSA is used in a second step to add the matter header and produce the .ota file.
- The output myMatter-fw.bin is used as input for this step to create the .ota file
- To run the python script, follow the below steps:
- Open Command Prompt on the PC
- Browse to X-CUBE-MATTER\Utilities\OTA_Tools directory
- Run the below command
python ./ota_image_tool.py create -v VENDOR_ID -p PRODUCT_ID -vn SOFTWARE_VERSION (newer or higher numerical(int)) -vs SOFTWARE_STRING_VERSION -da sha256 myMatter-fw.bin my-firmware1.ota
1.2.4.4.4.2 How to generate the .ota file - STM32WB55 based devices
STEP 1: Setting up the end device
This step describes the binaries and key to be used to support Matter OTA, and the preparation of the device on which to perform OTA.
For a device based on an STM32WB, there are two types of binaries:
- - One binary for an M0 core (in X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x)
- This is an encrypted binary provided by STMicroelectronics that contains the wireless stack. The key to decrypt it is used by FUS and stored in a secure part of the internal flash.
- - Two binaries available for an M4 core in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App-SBSFU\Binary:
- SBSFU_XXX-App-SBSFU.bin, which is an unencrypted binary. This binary should be flashed for the very first Matter application. Refer to section How to program the M4 core for more information. It contains BLE_ota (aka Bluetooth® Low Energy loader), secure engine, SBSFU, and the first version of the application.
- XXX-App-SBSFU.sfb is a encrypted binary to be programmed through SBSFU in internal flash during the firmware upgrade process. It contains the application (.bin) and its header used by an SBSFU process during M4 installation in internal flash. Before trying to upgrade the M4 application, the encryption/decryption key that has been used to encrypt this binary must be stored in the device. You can find the key in the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\Binary folder. To store the key in the device, use STM32CubeProgrammer.
- For firmware versioning, there are two different levels: Matter stack level and SBSFU level.
- Matter stack level
This firmware must be generated with a software version newer than the version in the firmware to be upgraded. The firmware version is set in the CHIPProjectConfig.h configuration file (#define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION). A corresponding string (#define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING) is also defined in this configuration file and is displayed in the UART log for result verification purposes. - SBSFU level
The firmware version is part of the firmware header generated with the postbuild script in IDE (X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\STM32CubeIDE). It must be set to a value higher or equal to the version of the firmware to be replaced.
- Matter stack level
- For the generation of the binary, the following projects must be built in sequence to create the “SBSFU_XXX-App-SBSFU.bin” with the current version to be loaded and provisioned with a decryption key required by SBSFU, using STM32CubeProgrammer. You can refer to "X-CUBE-MATTER\STM32WB5MM-DK\Applications\Matter\<Application>\Core\Inc\CHIPProjectConfig.h" to check the current software version of the Matter application.
- 1. X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\BLE_Ota\STM32CubeIDE\.project
- The BLE_Ota project implements the firmware download over BLE. It is not really used for OTA over Matter but is needed as it must be integrated into SBSFU and SBSFU_XXX-App-SBSFU.
- 2. X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\STM32CubeIDE\.project
- The 2_Images_SECoreBin project is used to generate the SE (Secure Engine) binary integrated into the SBSFU application.
- 3. X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SBSFU\STM32CubeIDE\.project
- The 2_Images_SBSFU project is used to generate the SBSFU application which manages secure boot and secure firmware upgrade.
- 4. X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App-SBSFU\STM32CubeIDE\.project
- The XXX-App-SBSFU project compilation step is used to generate SBSFU_XXX-App-SBSFU.bin and XXX-App-SBSFU.sfb.
- 1. X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\BLE_Ota\STM32CubeIDE\.project
- The following image illustrates the compilation process described above.
- The below flowchart explains the overall compilation and flashing process on the end device with Matter application.
- The SBSFU_XXX-App-SBSFU.bin file (application: M4) is flashed on the end device with the M0 Stack (X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_BLE_Thread_light_dynamic_fw.bin) and decryption key (X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\Binary\OEM_KEY_COMPANY1_key_AES_CBC.bin) using the STM32CubeProgrammer.
- Program the STM32WB5MM-DK as a Matter device as explained in the section How to program the M4 core of this page but using the binary SBSFU_XXX-App-SBSFU.bin for the M4 core.
- In this context of firmware upgrade, the device must also be provisioned with a decryption key required by SBSFU, using STM32CubeProgrammer.
- Your end device is all set to be updated with the newer software version of the Matter Application using the OTA process.
STEP 2: Generate the .ota file
The below figure explains the process of creating the input file (.sfb) to generate the .ota file.
To create the .sfb file:
- In X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\<Application>\Core\Inc\CHIPProjectConfig.h
- 1. Nowm set Software version and Software version string to a value higher to the version of the firmware to be replaced.
- For example:
- Modify the value of Software Version String:
- Modify the value of Software Version String:
- For example:
#define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING "1.3"
- Modify the value of the Software Version:
- Modify the value of the Software Version:
#define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION 3
- 2. Re-build only the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App-SBSFU\STM32CubeIDE\.project.
- 3. After compilation, you will have the .bin and .sfb file in the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Window-App-SBSFU\Binary folder.
The generated xxx-app-SBSFU.sfb file is the input to generate the .ota file.
The .ota is generated in two steps using respectively the following two tools: The below block diagram shows the in depth two step process to generate the .ota file.
The python scripts are found in (X-CUBE-MATTER\Utilities\OTA_Tools) folder.
- - CreateMatterBin.py
- This tool from STMicroelectronics is used in a first step to concatenate M0 and M4 binaries.
- This step takes .sfb file(xxx.sfb) as input with M0 stack and converts into .bin file
- To run the python script, follow the below steps:
- Open Command Prompt on the PC
- Browse to X-CUBE-MATTER\Utilities\OTA_Tools directory
- Run the below command
python ./CreateMatterBin.py -m4 XXX-App-SBSFU.sfb -m0 stm32wb5x_BLE_Thread_light_dynamic_fw.bin -o myMatterM4M0-fw.bin
For example:
python ./CreateMatterBin.py -m4 ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Window-App-SBSFU\Binary\Window-App-SBSFU.sfb -m0 ...\X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_BLE_Thread_light_dynamic_fw.bin -o myMatterM4M0-fw.bin
Note: (Make sure to include full path for the Application(-m4) XXX-App.sfb and Stack(-m0) stm32wb5x_BLE_Thread_light_dynamic_fw.bin)
OUTPUT: The output of this python script is myMatterM4M0-fw.bin, and this file is input to next tool. The output file gets stored in (X-CUBE-MATTER\Utilities\OTA_Tools) folder
- - ota_image_tool.py: this tool from CSA is used in a second step to add the matter header and produce the .ota file.
- The output myMatterM4M0-fw.bin is used as input for this step to create the .ota file
- To run the python script, follow the below steps:
- Open Command Prompt on the PC
- Browse to X-CUBE-MATTER\Utilities\OTA_Tools directory
- Run the below command
python ./ota_image_tool.py create -v VENDOR_ID -p PRODUCT_ID -vn SOFTWARE_VERSION (newer or higher numerical(int)) -vs SOFTWARE_STRING_VERSION -da sha256 myMatterM4M0-fw.bin my-firmware1_3.ota
For Example:
python ./ota_image_tool.py create -v 0xFFF1 -p 0x8004 -vn 3 -vs "1.3" -da sha256 myMatterM4M0-fw.bin my-firmware1_3.ota
OUTPUT: The output of this python script is my-firmware1_3.ota. The output file gets stored in (X-CUBE-MATTER\Utilities\OTA_Tools) folder.
STMicroelectronics provide two wrappers of the above scripts:
- - ST_ota_image_tool.py that simplifies the ota_image_tool.py usage,
python .\ST_ota_image_tool.py -cc ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App-SBSFU\Core\Inc\CHIPProjectConfig.h my-firmware.bin my-firmware.ota
- - ST_MFT.py (based on a PySimpleGui library) that brings GUI experience over CSA and STMicroelectronics script
python .\ST_MFT.py
The .ota file is composed of two headers and two binaries as illustrated by the following figure:
1.2.4.4.5. Save the .ota file onto the device used as OTA provider
1.2.4.4.5.1. RaspberryPi as OTA provider
Save the .ota file onto the device used as OTA provider
The .ota file needs to be saved onto the RaspberryPi (TH) to run the OTA provider.
You can use the USB key to save the .ota file from the PC to RaspberryPi.
- Copy .ota file on the USB key and Eject from PC
- Insert the USB key onto Raspberry Pi and access the files using the below mount commands:
sudo mkdir /mnt/usb
sudo mount /dev/sda1 /mnt/usb
ls -latr /mnt/usb (You can view the contents of the USB key)
- Now, copy the .ota file from the USB key to apps directory present on Desktop using cp command.
1.2.4.4.5.2. Android smartphone as OTA provider
The .ota file needs to be saved onto the Android phone to run the OTA provider.
Transfer the generated .ota file to the Android phone by any mean (copy, e-mail). You can e.g. use a USB cable to connect the phone to the PC, enable data transfer mode and save the .ota file from the PC to phone.
1.2.4.4.6. OTA file download
1.2.4.4.6.1. RaspberryPi as OTA provider
- 1. Terminal setup: Open two terminals on the RaspberryPi, Terminal A for the controlling the Matter Controller and Terminal B for controlling the OTA provider.
- On the PC, open terminal for the end device debug logging.
- 2.Terminal A: To get the "Thread network dataset", run the below command:
cd ~/chip-certification-tool/scripts/OTBR
sudo ./otbr_start.sh
- This step generates the hex code named “Simple Dataset”, make a note of the same.
- 3. Upload the .ota file to OTA Provider
- Terminal B: To start the OTA provider application and path it OTA file.
cd ~/apps
sudo ./chip-ota-provider-app -f my-firmware1_3.ota
- Keep the OTA provider running and return to Terminal A.
- 4. Switch back to Terminal A: Commission the OTA provider into network over IP using the user-defined node id "1" and the setup PIN code "20202021"
cd apps
sudo ./chip-tool pairing onnetwork 1 20202021
- 5. Write to the OTA provider accesscontrol cluster (node id 1, endpoint 0) the ACL data granting Operate privileges to all nodes in the fabric.
- This command is to prepare the OTA Provider to receive Cluster commands from all nodes of the fabric
sudo ./chip-tool accesscontrol write acl '[{"fabricIndex":1, "privilege":5, "authMode":2, "subjects":[112233], "targets":null},{"fabricIndex":1,"privilege":3,"authMode":2,"subjects":null,"targets":null}]' 1 0
- Start end device (if not yet) in fast advertising mode by resetting the board.
- 6. Commission the end device using the following CHIP Tool command with respectively the following parameters: the node id 3, the "Thread network dataset" previously obtained in STEP 2 , the setup PIN code 20202021, and the discriminator 3840.
sudo ./chip-tool pairing ble-thread 3 hex:"Thread network dataset" 20202021 3840
- Save provider information in NVM on end device.
- 7. Provide the Matter end device/OTA requestor (node id 3, endpoint- 0) with the list of default OTA providers that contains only one element (fabric index 1, node id 1, endpoint 0)
sudo ./chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex":1, "providerNodeID":1,"endpoint":0}]' 3 0
- 8. Send the Announce OTA provider command to the device with the following parameters in the order: provider node id = 1, provider vendor id = 0, announcement reason = 0 for UpdateAvailable, provider endpoint = 0, requestor node = 3, requestor endpoint = 0
sudo ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 3 0
- Once the device receives this announce, it requests the new software image.
- 9. Download and process the .ota file
- Observe the BDX (Bulk Data Exchange) transfer ON Terminal A and End Device Terminal (Terminal C)
- Check that at the end of BDX transfer, the end device restarts correctly with the new firmware
1.2.4.4.6.2. Android smartphone as OTA provider
- 1. Open a terminal on the RaspberryPi and start the otbr.
cd ~/chip-certification-tool/scripts/OTBR
sudo ./otbr_start.sh
- 2. On the PC, open terminal for the end device debug logging.
- 3. On the Android phone, launch the CHIPTool application and commission the end device in the CHIPTool fabric following the procedure described in Demonstrate Lighting-App using CHIPTool APK.
- 4. Once the commissioning successfully completed, save the .ota file to the phone and select the OTA Provider feature from the CHIPTool home screen
- 5. From the OTA Provider main screen, click on the Select Firmware button then find and select the new firmware (saved .ota file) from the phone storag
- 6. The selected firmware name will appear on the screen. You can select and read the "UpdateState" attribute and observe that the current update state at the requestor has value 1 corresponding to state "Idle"
- 7. Click on the button "Start Firmware Update" and observe the procedure progress as shown in the following figure: block numbers from 0 to the last (845 in our case) are displayed on the screen and, at any time, you can read the update status. In the figure, the "Downloading" state (value 4) and the "Applying" state (value 5) are shown. At the end of the procedure, the number of the last block sent remain displayed on the phone screen.
The end and success of the procedure can be observed on the debug log at the PC side, with the indication of the EOF when the last block is sent and the restart of the device with the new firmware version after a successful update. In this demonstration the update has been done from SDK version 1.1 to SDK version 1.3.
At the end of the procedure, the update state will return to "Idle" and this can be observed on the phone by reading the UpdateState attribute.
1.2.4.4.7. OTA execution on the device
1.2.4.4.7.1 OTA over Matter execution on STM32WB65I-DK1
In X-CUBE-MATTER V1.4.0 only internal flash memory is supported for STM32WB65I-DK1 and the downloaded .ota file is directly stored in the internal flash memory.
- STM32WB65I-DK1 2-MBytes internal flash memory mapping
- Firmware update execution on STM32WB65I-DK1
- Upon .ota file downloaded, the OTA application performs the following operation:
- - Extracts and copies the TrustZone binary (oemirot_tz_ns_app_enc_sign.bin) in the internal flash in "Non-Secure Image Secondary Slot" (Area 3)
- - Pads and writes the correct magic number at the end of the slot and reset the device. This reset will start the OEMiROT_Boot which will proceed to the firmware update
1.2.4.4.7.2 OTA over Matter execution on STM32WB5MM-DK
For OTA over Matter on STM32WB5MM-DK, the .sfb file is encapsulated in an .ota file, downloaded and stored first into the external flash, then installed on the internal flash using the SBSFU.
- STM32WB5MM-DK 2-MBytes external flash memory mapping
- Firmware update execution on STM32WB5MM-DK
- Upon .ota file downloaded, the OTA application performs the following operation:
- - Extracts and copies binarie(s) in the external flash (M4 binary in DWL_Slot 1 and/or M0 binary in DWL_Slot 4)
- - Writes the correct value at a defined address in RAM memory (different values are used to update only M4, only M0, or both M0 and M4) and resets the device. This reset will start the SBSFU which will proceed to the firmware update
- - If the M4 update is done successfully, the OTA application updates the external flash Back_Up_Slot with the new M4 binary
- - If the M4 update has failed, the SBSFU re-install the old firmware that is has been backed up into the Back_Up_Slot of the external flash
1.2.4.5. How to configure an STM32 platform Matter device embedding ICDM Cluster
Configuration of ICD for a given application is done in X-CUBE-MATTER in the configuration file ...\X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\XXX-App\Core\Inc\CHIPProjectConfig.h for STM32WBA65I-DK1, or ...\X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App\Matter\Inc\CHIPProjectConfig.h for STM32WB5MM-DK, where XXX-App is the Matter application (e.g. Generic-Switch-App).
For a device type (application) that embeds an ICDM Cluster CHIP_CONFIG_ENABLE_ICD_SERVER must be set to 1 (#define CHIP_CONFIG_ENABLE_ICD_SERVER 1) in CHIPProjectConfig.h. In fact, the current SDK does not allow to set CHIP_CONFIG_ENABLE_ICD_SERVER to 0 for a device that embeds an ICDM cluster as this will result to a compilation error.
When ICD is enabled
- the Sleepy End Device (SED) feature (for Thread based devices) is also enabled: #define CHIP_DEVICE_CONFIG_ENABLE_SED 1
- the different ICD attributes are set using corresponding #define
- - ICD Slow Polling Interval: #define CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL System::Clock::Milliseconds32(<value>)
- - ICD Fast Polling Interval: #define CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL System::Clock::Milliseconds32(<value>)
- - ICD Idle Mode Duration: CHIP_CONFIG_ICD_IDLE_MODE_DURATION_SEC <value>
- - ICD Active Mode Duration: CHIP_CONFIG_ICD_ACTIVE_MODE_DURATION_MS <value>
- - ICD Active Mode Threshold: CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS <value>
In X-CUBE-MATTER version 1.4.0, only Generic-Switch-App is configured as an ICD server with the following settings:
#define CHIP_CONFIG_ENABLE_ICD_SERVER 1
#if (CHIP_CONFIG_ENABLE_ICD_SERVER == 1)
#define CHIP_DEVICE_CONFIG_ENABLE_SED 1
#define CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL System::Clock::Milliseconds32(300000)
#define CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL System::Clock::Milliseconds32(200)
#define CHIP_CONFIG_ICD_IDLE_MODE_DURATION_SEC 450
#define CHIP_CONFIG_ICD_ACTIVE_MODE_DURATION_MS 2000
#define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS 5000
#endif
For Generic-Switch-App configured as ICD server, the button "B2" on STM32WB5MM-DK and joystick "right" on STM32WB65I-DK1 is used as wake-up button and switch button. When the user presses this button, the device enters in Active Mode and generates message if any client subscribed to get the event.
The Test Harness CHIPTool 1.4 can be used as a client to test ICD features on a device configured as ICD server:
- Activate the CHIPTool interactive mode
./chip-tool interactive start
- Register/Unregister to/from the ICD server
./chip-tool icdmanagement register-client 112233 112233 2234567890abcdef <node_id> <endpoint_id>
./chip-tool icdmanagement unregister-client 112233 <node_id> <endpoint_id>
- Read ICD attributes
./chip-tool icdmanagement read active-mode-threshold <node_id> <endpoint_id>
./chip-tool icdmanagement read active-mode-duration <node_id> <endpoint_id>
./chip-tool icdmanagement read idle-mode-duration <node_id> <endpoint_id>
1.2.4.6. Low power: How to measure the power consumption
The setup is composed of:
- a STM32WB55MM-DK discovery kit
- a STLINK-V3PWR with the latest firmware
- a PC on which to display the power data coming from the STLINK-V3PWR
Application must be on an ICD device (for example, Generic Switch) and low power must be enabled ("#define CFG_FULL_LOW_POWER 1” in Applications\Matter\”App”\Core\Inc\app_conf.h).
1.2.4.6.1. Hardware configuration for power measurement
- STM32WB55MM-DK board
- - Rear view
- - Front view
- STLINK-V3PWR
The numbers on the above images refer to board connection steps listed in the next section.
1.2.4.6.2. Steps to connect STLINK-V3PWR to STM32WB55MM-DK board
Ensure that the STM32WB55MM-DK and STLINK-V3PWR are not powered by any power source.
- Download and install STM32CubeMonPwr on the PC.
- On STM32WB55MM-DK, remove the JP1 jumper (top view).
- Use a Dupont wire to connect the OUT terminal of the STLINK-V3PWR to the left pin of JP1 of STM32WB55MM-DK (top view).
- Use a Dupont wire to connect a GND terminal of the STLINK-V3PWR to the GND pin of the CN1 connector of STM32WB55MM-DK (rear view).
- Ensure the two wires, OUT and GND, are not be damaged.
- Ensure the two wires, OUT and GND, are firmly connected at STLINK-V3PWR side.
- Twist the two wires, OUT and GND, to enhance signal quality.
- Use a Dupont wire to connect the +5 V terminal of the STLINK-V3PWR (side) to the VIN pin of the CN2 connector on STM32WB55MM-DK (rear view).
- On JP2 connectors of STM32WB55MM-DK (top), move the jumper to the pins labeled "5 V VIN"
1.2.4.6.3. Measurement execution
- Plug the STLINK-V3PWR to the PC
- Launch STM32CubeMonitor-Power (STM32CubeMonPwr)
- Select your board
- Click on "TAKE CONTROL"
- Configure the acquisition using these parameters:
- Click on "START ACQUISITION"
- Click on "POWER ON" to boot the STM32WB55MM-DK board
- The below figures are waveforms corresponding to different power modes and views. All these waveforms are from generic switch ICD matter application:
- Low power overall waveform with wake up for polling every 5 seconds and maximum current consumption of around 15 mA:
- Low power waveform with power maintenance details between two polling periods and current mean consumption of 3 μA
- Waveform including different power modes: active mode, low power threshold with polling every 200 ms, then deeper low power mode with polling every 5 s.
1.2.4.7. Debug Logging
The STM32 platforms (STM32WBA65I-DK1, STM32WB5MM-DK, NUCLEO-WBA55CG, NUCLEO-WB55RG) embed the ST-LINK/V2 in-circuit debugger and programmer for STM32 microcontrollers. The single-wire interface module (SWIM) and JTAG/serial wire debugging (SWD) interfaces are used to communicate with the STM32WB microcontroller. It also supports the STM32 virtual COM port driver for communication between a PC and the application processor via a serial interface.
Use any convenient software terminal to open the serial communication port of the PC to check the messages from the board. Select your serial port and set up your connection as follows (example done with Tera Term software).
Set a new serial connection to the ST platform:
Setup your serial connection as below:
1.3. Matter bridge (not certified)
1.3.1. Overview
Matter bridge is not yet supported in the X-CUBE-MATTER package, but an evaluation package is available on GitHub. This prototype application provides an example of the use of the Matter bridge and the NUCLEO-H753ZI-Q board with Ethernet connectivity:
- This application provides a dynamic endpoint with device commissioning and cluster control.
- The application adds the non-Matter device as an endpoint on a bridge acting as a Matter device.
In the example below, eight light devices supporting one on-off cluster have been added as endpoints.
1.3.2. Required boards
The Matter bridge runs on:
1.3.3. Package content
Download the required files on Github.
2. STM32 hotspot GitHub
The STM32 Hotspot GitHub contains repositories for prototyping and demonstration of Matter bridge and OpenThread border router based on STM32 platforms.
- stm32h7-matter-bridge for Matter bridge based on STM32H7]
- stm32mp1-otbr-posix for OpenThread border router based on STM32MP1
3. References