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 running on different STM32 Microcontrollers development platforms based on Arm® cores. A development platform consists of a set of hardware: a single board or a combination of two boards. The choice of the platform will mainly depend on the target transport technology (Thread, Ethernet, Wi-Fi) and the target type of Matter device (Matter end device, Matter bridge). Binaries are provided for a quick demo.
X-CUBE-MATTER Expansion Package has Matter SDK pre-integrated on STM32 Microcontrollers. The Matter SDK middleware uses FreeRTOS and mbedTLS infrastructure. It is considered as reference implementation to demonstrate and is ready for prototyping a Matter end-device on reference development platform. Supported STM32 platforms are presented in this wiki.
The X-CUBE-MATTER is ready for CSA certification with the default “dimmable light cluster”. However other Clusters are also provided as prototype for evaluation.
The STM32 SoC embeds most of the hardware blocks (Flash, Crypto Engine, RNG, RTC). The different connectivity technologies can be embedded in a standalone SoC or a chipset. Thread, BLE, Wi-Fi and Ethernet technologies are supported along with STM32 Microcontroller families. The supported technologies are detailed in this wiki.
The project stores the device credentials and keys in the STM32 embedded flash memory or an external flash memory for which X-CUBE-MATTER provides a driver. For production, the project offers infrastructure from partners for provisioning DAC private key into STM32 secure storage (CKS) and related driver for operational network. Once provisioned, the security-sensitive data and operations remain in a secure partition, where they are not exposed to the user application. The secure boot process acts as a Root of Trust for the application before launching it. It takes care of the secure firmware update once a new image has been downloaded by the user application.
X-CUBE-MATTER is available for free download from st.com website.
1.1.2. X-CUBE-MATTER versions
The X-CUBE-MATTER versions contains software components and features which are continuously evolving, please refers to the release note included in the package for more details.
1.1.3. Software architecture
1.1.3.1. Overall bloc diagram
X-CUBE-MATTER architecture blog diagram |
---|
1.1.3.2. Components description
The X-CUBE-MATTER software components are made by Core Matter SDK stack from connectedhomeip, files generated by ZAPTool and tools provided by connectehomeip, FreeRTOS, mbedTLS and LwIP. The adaption layers are either based on component from connectedhomeip but adapted or modified by ST to run on STM32 infrastructure.
OpenThread stack, BLE stack and IP stack can be located on the Application MCU in the case of chipset solution or on the dedicated wireless stack coprocessor. The software partitioning for each target platform is detailed in this wiki.
The delivered application examples as part of the project are provided with compiled binary for an out-of-the box experience. Source codes are also provided and can be compiled with supported IDEs. Finally, the Project can be modified and regenerated using STM32CubeIDE. For features supported with this version of X-CUBE-MATTER (Matter SDK version, supported applications and their list of features), refer to the release note.
Low power framework, when embedded, is implemented in Utilities component.
1.1.4. Folder structure
The X-CUBE-MATTER is conform with STM32CubeFW folders which are Drivers, Middleware, Projects and Utilities, as illustrated in the figure below.
X-CUBE-MATTER Folder structure: Main folders |
---|
- Driver 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.
X-CUBE-MATTER Folder structure: Drivers |
---|
- Middleware folder
The Middleware folder contains two main sub-folders:
- - ST sub-folder which contains components used by SBSFU and the STM32_WPAN (BLE, Thread) middleware components
- - Third_Party sub-folder which contains the connectedhomeip source code including the STM platform specific code, and also the FreeRTOS and mbedtls components. each devices/app sub-folder contain part of the code generated with ZAP Tool (copied from zap-generated) for a given cluster,
X-CUBE-MATTER Folder structure: Middlewares |
---|
- Projects folder
The following figures represent different views of the X-CUBE_MATTER project which respectively show where are located in the structure:
- - the binary (under X-CUBE-MATTER\Projects\P-NUCLEO-WB55.Nucleo\Thread_RCP\Binaries sub-folder) used to program the M4 core of the P-NUCLEO-WB55 when used as RCP for an OTBR,
- - the binaries (under X-CUBE-MATTER\Projects\STM32WB_Copro_Wireless_Binaries sub-folder) used to program the M0 core of STM32WB5x based platforms,
- - part of the code generated with ZAP Tool for a given cluster, copied from zap-generated and stored in .../codegen/app sub-folder,
- - the binary of the Matter application stored in the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\”App”\Binaries sub-folder of each application and to be used to program the M4 core,
- - the key used to decrypt the .sfb binary file received from the OTA provider during software upgrade procedure. It is located in the...\2_Images_SECoreBin\Binary folder.
X-CUBE-MATTER Folder structure: Projects - RCP |
---|
X-CUBE-MATTER Folder structure: Projects - End Device coprocessor |
---|
X-CUBE-MATTER Folder structure: Projects - End Device zap code |
---|
X-CUBE-MATTER Folder structure: Projects - End Device application |
---|
- Utilities folder
The .zip file in the APK sub-folder contains the CHIPTool application used as commissioner and controller in STM or RPi ecosystems. This CHIPTool 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 Arm54 CPU based devices and Android 8 or later is required.
The OTA_tools sub-folder contains scripts provided with X-CUBE-MATTER for OTA firmware update over Matter,
X-CUBE-MATTER Folder structure: Utilities - APK |
---|
X-CUBE-MATTER Folder structure: Utilities - OTA_tools |
---|
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 (e.g.: modification of BLE discriminator) and recompile the project.
Follow the following steps:
Step1: Select the transport technology (Thread, Ethernet, or Wi-Fi)
Step2: Select an ED platforms supporting the chosen transport technology
Step3: Get the X-CUBE-MATTER delivery from st.com website
Step4: Regenerated the application binary using STM32CubeIDE
Step5: Program firmware (the generated one for the application and the delivered ones for co-processor core) into the platform’s cores as indicated in End devices How To
Step6: 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 Zigbee Cluster Library, one of the specifications developed by CSA. On top of this, CSA provides a set of scripts and templates which 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 right ZAP tool version to be used.
1.2.2.1. Windows system set-up for ZAP (one-time)
Before proceeding to work with a project, several tools need to be installed. These include the STM32CubeIDE to work with and compile the project, the additional X-CUBE-MATTER package which 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 will be similar, apart from the version of ZAP tool which is platform-dependant. The Linux version uses Pyhton library called fcntl instead of PORTALOCKER in step Environment configuration and does not require modificatoins.
Install Python
Install the latest version of Python 3.x.
Python should be added to 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
- Download the repository from connectedhomeip and extract the content into e.g. C:\chip-matter-tools.
- The ZAP tool can be found here. Look for and download the latest stable (not nightly) release of zap-win-x64.zip. Extract to C:\chip-matter-tools.
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 in order 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:
import portalocker
- line 337:
portalocker.lockf(self.lock_file, portalocker.LOCK_EX)
- line 343:
portalocker.lockf(self.lock_file, portalocker.LOCK_UN)
It is also advisable to create a separate folder for files generated by ZAP, e.g. C:\chip-matter-tools\zap_gen_files.
1.2.2.2. Starting project
After you have generated the configuration files for your Matter device, you will 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.
Basic functionality can be achieved based on the Lighting-App project. You can also use the project Lighting-App-SBSFU in case you want update-over-the-air capability ("#define OTA_SUPPORT" needs to be set to 1). In all cases, the steps will be very similar to what is described here.
1.2.2.3. Generate files in ZAP
In this section, we will show how to set your device's clusters and export the basic code in ZAP. This code, when integrated into a project, dictates how the device is seen by the Matter network and all of its basic functionality which is defined 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 needs to be done at every Bash launch.
Change to Matter directory, e.g.
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 given endpoint and enable them
- for each cluster, there are also mandatory and optional Attributes and Commands, e.g. Long press for a Generic switch
Optional cluster settings in ZAP | ||
---|---|---|
|
Save as a new file, e.g. 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.
Save project and generate files in ZAP | ||
---|---|---|
|
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 are used to expose Matter callbacks from each cluster to other clusters and to the user application, thus enabling communication between them.
Still 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 gnereate 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 will 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
- CHIPClusters.h
- CHIPClientCallbacks.h
- endpoint_config.h
- gen_config.h
- IMClusterCommandHandler.cpp
Note that the file CHIPClientCallbacks.h is needed only when an OTA Provider cluster is included, that is not the case of the end device which is OTA Requestor.
Next, go to X-CUBE-MATTER\Projects\STM32WB5MM-DK\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, keep 'update references'.
Rename the project | ||
---|---|---|
|
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
- CHIPClusters.h
- CHIPClientCallbacks.h
- endpoint_config.h
- gen_config.h
- IMClusterCommandHandler.cpp
Copy the generated files | ||
---|---|---|
|
Open structure Middlewares\connectedhomeip\src\app\ and delete the exising PluginApplicationCallbacks.h file. Next, drag-and-drop the new PluginApplicationCallbacks.h in here same as before.
Open structure Middlewares\connectedhomeip\src\app\clusters\ in STM32CubeIDE and folder X-CUBE-MATTER\Middlewares\Third_Party\connectedhomeip\src\app\clusters\ in the File Explorer. Also open the file PluginApplicationCallbacks.h which was copied before. Now, for each callback in the .h file, check if the corresponding folder is included in STM32CubeIDE. If there isn't the needed subfolder, do the following steps.
- Create the subfolder in STM32CubeIDE with the same name as in File Explorer, e.g. MatterBasicInformationPluginServerInitCallback => basic-information subfolder.
- Drag-and-drop the source files from the File Explorer subfolder into the STM32CubeIDE subfolder.
- Choose 'Link to files' and 'Create link locations relative to PROJECT_LOC'.
If there is a cluster subfolder which is not specified in PluginApplicationCallbacks.h, you can delete the .h and .cpp files (unlink them from project) and then delete the cluster subfolder (delete from file system).
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 (e.g. name, serial number) can be changed as explained in How to customize your application. Functionality based on the target platform (second user button, LEDs, ...) can also be added.
Application-specific functions should be modified to reflect the needs of your device. For this purpose, you can create a new ...Manager.cpp/.h files based on the LightingManager.cpp/.h. Then you would 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 will call the functions in ...Manager.cpp file.
1.2.2.7. Program the application
After modifying the source files, you can generate the project in STM32STM32CubeIDE. Then, program firmware (the generated one for the application and the delivered one for co-processor 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 devices hardware platforms
1.2.3.1. Platforms supporting Thread technology
1.2.3.1.1. STM32WB5x dual-core based platforms: P-NUCLEO-WB55[1] and STM32WB5MM-DK Discovery kit[2]
P-NUCLEO-WB55 | STM32WB5MM-DK |
---|---|
The USB cable (standard A male port to micro-B male port) from the PC is used to power and interact with the STM32.
Hardware configuration
- P-NUCLEO-WB55: Jumper JP1 to USB STL and USB ST-LINK to be used
- STM32WB5MM-DK Discovery kit: Jumper JP2 to 1-2 and USB ST-LINK to be used
Note that currently Nucleo is used for RCP with an OTBR and STM32WB5MM-DK runs the Matter End Device Accessory.
1.2.3.2. Platforms supporting Ethernet technology
Coming soon
1.2.3.3. Platforms supporting Wi-Fi technology
Coming soon.
1.2.4. End devices How To
1.2.4.1. How to program firmware on STM32WB5x
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 (BLE-Thread for Matter application).
Programming the STM32WB5x will consist in updating the FUS if needed and programming the two CPU cores (M0+ first, then M4).
In case M0 is reprogrammed after 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 FW version is the latest and upgrade it if needed using STM32CubeProgrammer[3].
In the matter context:
- P-NUCLEO-WB55 is used as radio coprocessor (RCP) that could be combined with an STM32MP1 to form an OTBR.
- STM32WB5MM-DK is used as Matter end device.
1.2.4.1.1. How to program the M0+ core
All the code running on Arm® Cortex®-M0+ is delivered as encrypted binary, and it is necessary to upgrade the wireless stack before developing a project on the application side.
The STM32WB is pre-loaded 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 FUS is not the latest one, the FUS must be updated.
The firmware upgrade service (FUS) and BLE-Thread wireless stack can be updated using STM32CubeProgrammer software[3]. More information about the FUS can be found on the dedicated Firmware Upgrade Services wiki article or within the firmware upgrade service for STM32WB series application note AN5185: FUS for STM32WB.
1.2.4.1.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 in order to update the FUS of P-NUCLEO-WB55 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[3] version indicated by the Release Notes
Connect physically your development platform to the PC running STM32CubeProgrammer
Connect your platform using STM32Cubeprogrammer[3].
STM32CubeProgrammer: connection |
---|
Start FUS
When connected, go to the firmware upgrade services interface, and start the FUS, by clicking on the associated button.
STM32CubeProgrammer: start FUS |
---|
Once the FUS has started correctly, the following logs should be visible on the CubeProgrammer logs interface.
STM32CubeProgrammer: FUS started logs |
---|
Read FUS
Once the FUS is started read its value by clicking the Read FUS infos button
STM32CubeProgrammer: read FUS |
---|
Update firmware upgrade service binary
The latest version of the FUS can be found in STM32CubeWB MCU Package[4].
Start addresses and versions are given as example. Check the release notes to find the latest FUS version and the FUS start address.
FUS information |
---|
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
.
STM32CubeProgrammer: FUS 0.5.3 |
---|
- 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 start address (see release notes).
Click on Firmware Upgrade.
STM32CubeProgrammer: update FUS |
---|
A popup occurs to confirm that the upgrade is correct.
Check new FUS version
Check the new FUS version by clicking on the Read FUS info button.
STM32CubeProgrammer: read new FUS |
---|
1.2.4.1.1.2 How to update the coprocessor wireless stack (BLE-Thread or Thread RCP)
The Bluetooth® LE-Thread Stack (stm32wb5x_BLE_Thread_ForMatter_fw.bin) for STM32WB5MM-DK, or the Thread stack for P-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.
Stack start address |
---|
Select the type of stack to be loaded in the STM32CubeWB package[4].
For P-NUCLEO-WB55 platform the recommended stack is:
...\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_Thread_RCP_fw.bin.
For STM32WB5MM-DK Discovery platform the recommended stack is: ...\Projects\STM32WB_Copro_Wireless_Binaries\STM32WB5x\stm32wb5x_BLE_Thread_ForMatter_fw.bin.
Check the First install checkbox if it is the first time you are installing the stack on your platform.
STM32CubeProgrammer: BLE-Thread stack installation |
---|
STM32CubeProgrammer: Thread stack installation |
---|
After having programmed the M0 and before programming the M4, ensure that the wireless stack is started by clicking on the Start Wireless Stack button.
STM32CubeProgrammer: Start Wireless Stack |
---|
1.2.4.1.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.
STM32CubeProgrammer: Matter application installation |
---|
- Programming M4 on P-NUCLEO-WB55 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.
STM32CubeProgrammer: RCP M4 binary installation |
---|
1.2.4.2. How to customize your application
BLE discriminator modification
Modifying the BLE discriminator will allow to avoid 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\<Platform>\Applications\Matter\Lighting-App\Core\Inc\CHIPProjectConfig.h, where <Platform> is the end device platform (e.g. STM32WB5MM-DK):
- Modify the value of the #define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR: e.g. replace the default value 0xF00 (3840 in decimal) by 0xA00:
- In ...\X-CUBE-MATTER\Projects\<Platform>\Applications\Matter\Lighting-App\Core\Inc\CHIPProjectConfig.h, where <Platform> is the end device platform (e.g. STM32WB5MM-DK):
#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 0xA00
- In ...\X-CUBE-MATTER_1_0\Projects\<Platform>\Applications\Matter\Lighting-App\STM32_WPAN\App\app_ble.c, where <Platform> is the end device platform (e.g. STM32WB5MM-DK):
- Update the discriminator value in the manuf_data table (replace "0x00, 0x0F" by "0x00, 0x0A"):
- In ...\X-CUBE-MATTER_1_0\Projects\<Platform>\Applications\Matter\Lighting-App\STM32_WPAN\App\app_ble.c, where <Platform> is the end device platform (e.g. STM32WB5MM-DK):
uint8_t manuf_data[15] = { 0x02, 0x01, 0x06, 0x0B, 0x16, 0xF6, 0xFF, 0x00, 0x00, 0x0A, 0xF1, 0xFF, 0x04, 0x80, 0x00, };
- Re-build the project
- Program the binary to M4 and reset the device
- Find the QR code link in the UART LOG and click on to show the new QR code.
1.2.4.3. How to perform remote firmware update (OTA)
1.2.4.3.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.
1.2.4.3.2. How to create ota file
- Binaries and keys
For device based on STM32WB there are two types of binaries:
- - One binary for M0 core
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 secure part of the internal flash.
- - Two binaries for M4 core
- X-App-SBSFU.bin that is a uncyphered binary, to be flashed for the very first Matter application (refer to section How to program the M4 core). It contains BLE_ota (aka BLE loader), Secure engine, SBSFU and the first version of the application.
- X-App.sfb is a cyphered binary to be programmed through SBSFU in internal flash during firmware upgrade process. It contains the application (.bin) and its header used by SBSFU process during M4 installation in internal flash. The encryption/decryption key that has been used to cypher this binary must be stored in the device in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\Binary folder (using STM32CubeProgrammer) before trying to upgrade the M4 application.
- This firmware shall 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 will be displayed in the UART log for result verification purpose.
- Tools
The .ota is created in two steps using respectively the following two tools:
- - CreateMatterBin.py: this tool from STMicroelectronics is used in a first step to concatenate M0 and M4 binaries and to add a STMicroelectronics header.
CreateMatterBin.py -m4 X-App.sfb -m0 stm32wb5x_BLE_Thread_ForMatter_fw.bin -o M4M0-fw.bin
The output M4M0-fw.bin is used as input for the second step.
- - ota_image_tool.py: this tool from CSA is used in a second step to add the matter header and produce the .ota file.
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 M4M0-fw.bin M4M0-fw.ota
The parameter SOFTWARE_VERSION is the numerical (int) version number which must be equal to the numerical version CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION defined in the CHIPProjectConfig.h configuration file.
STMicroelectronics provide two wrappers of the above scripts:
- - ST_ota_image_tool.py that simplifies the ota_image_tool.py usage,
- - ST_MFT.py (based on PySimpleGui library) that brings GUI experience over CSA and STMicroelectronics scripts.
1.2.4.3.3. Demonstration of firmware update over Matter
This is the fastest way to demonstrate the software upgrade as based on binaries delivered in X-CUBE-MATTER under the XXX-App-SBSFU\Binary folder for each delivered application (please refer to the Projects folder for end device application in Projects folder structure section of this page), XXX being the name of the application.
For Lighting-App application, the binaries to be used are SBSFU-Lighting-App-SBSFU.bin and M4M0-fw.ota
- SBSFU-Lighting-App-SBSFU.bin is the M4 Firmware which comprises SBSFU and Matter Accessory application. It is the binary that run the device initially.
- M4M0-fw.ota is the firmware provided to the OTA Provider and which contains a newer version of Lighting-App application. It is a concatenation of the encrypted newer application binary for M4 core (Lighting-App-SBSFU.sfb), the binary for M0 core (stm32wb5x_BLE_Thread_ForMatter_fw.bin), a header indicating "start index" and "size" for those binaries, and a global Matter header indicating information on the device and firmware (vendor id, product id, software version, software version string, and the digest algorithm). The .ota is generated by following the procedure described in the section How to create ota file.
The demonstration setup is composed of:
- a STM32WB5MM-DK used as end device
- a Raspberry Pi as a border router including the OTA provider application
- a laptop connected to the Raspberry Pi and to the end device in ssh to allow use of Terminals
Software upgrade over Matter: Demonstration setup |
---|
For the demonstration follow the following steps:
Step1: Prepare the device with a firmware
Program the STM32WB5MM-DK as a Matter device as explained in the section How to program firmware on STM32WB5x of this page but using the binary SBSFU-Lighting-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.
STM32CubeProgrammer: SBSFU key provisioning |
---|
Step2: Prepare the Raspberry Pi
- Get Test Harness Raspberry Pi bootable image and flash it to the Raspberry Pi following CSA instructions (Matter Test-Harness User Manual, TH image location link for Matter 1.1)
Step3: Perform the firmware upgrade (OTA)
- Open three Terminals: Terminal_A for end device debug logging, Terminal_B to control the test sequence, and Terminal_C that controls the OTA Provider
- On Terminal_B start OTBR:
sudo ifconfig wlan0 down (optional to ease Thread network)
cd ~/chip-certification-tool/scripts/OTBR
sudo ./otbr_start.sh
Get the "Thread network dataset" in "generating hex_code" as indicated in the guide. This will be used during the commissioning of the end device.
cd ~/apps
- On Terminal_C:
sudo ./chip-ota-provider-app -f MatterM4M0.ota
- On Terminal_B:
sudo ./chip-tool pairing onnetwork 1 20202021
- Start end device (if not yet) in fast advertizing mode by reseting the board, then
- On Terminal_B:
sudo ./chip-tool pairing ble-thread 3 hex:"Thread network dataset" 20202021 3840
- On Terminal_B:
sudo ./chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex":1, "providerNodeID":1,"endpoint":0}]' 3 0
- On Terminal_B:
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
- On Terminal_B:
sudo ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 1 0 3 0
- On both Terminal_A and Terminal_C:
- Observe the BDX transfer
- Save provider informations in NVM by pushing button on end device at start of BDX transfers
- On Terminal_A
- Check that at the end of BDX transfer, the end device restarts correctly with the new firmware (version visible from boot log)
1.2.4.4. 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 shall be a Sleepy End Device (e.g. Generic-Switch app) and Low Power shall be enabled ("#define CFG_FULL_LOW_POWER 1” in Applications\Matter\”App”\Core\Inc\app_conf.h).
1.2.4.4.1. Hardware configuration for power measurement
- STM32WB55MM-DK board
- - Rear view
STM32WB55MM-DK board configuration: rear view |
---|
- - Front view
STM32WB55MM-DK board configuration: front view |
---|
- STLink-V3PWR
STLink Power configuration: front view |
---|
Numbers on the above images refer to boards connection steps listed in the next section.
1.2.4.4.2. Steps to connect ST link V3 power to STM32WB55MM-DK board
First ensure that the STM32WB55MM-DK and STLink-V3PWR are not powered by any power source.
- Download and install on the PC the STM32CubeMonPwr
- On STM32WB55MM-DK, remove JP1 jumper (top view)
- Use a Dupont wire to connect OUT terminal of the STLink-V3PWR and the left pin of JP1 of STM32WB55MM-DK (top view)
- Use a Dupont wire to connect GND terminal of the STLink-V3PWR and the GND pin of the CN1 connector of STM32WB55MM-DK (rear view)
- Use a Dupont wire to connect +5V terminal of the STLink-V3PWR (side) and the VIN pin of the CN2 connector of STM32WB55MM-DK (rear view)
- On JP2 connectors of STM32WB55MM-DK (top), move the jumper to the pins "5V VIN"
1.2.4.4.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
- You should be now able to observe the following result:
In the first seconds of this snapshot, the module is in activity while low power mode is not active, then the consumption is more than 15 mA. It after falls in stop mode 2, and only wake up when radio activity is needed. Between these short radio activity times, the module is in stop mode, and the consumption falls to 3µA.
1.2.4.5. Debug Logging
The P-NUCLEO-WB55 and STM32WB5MM-DK platforms 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:
Tera Term setup (1/2) |
---|
Setup your serial connection as below:
Tera Term setup (2/2) |
---|
1.3. Matter bridges (not certified)
1.3.1. Overview
Matter bridge is not yet supported in X-CUBE-MATTER package, but an evaluation package is available in GitHub hotspot.
This prototype application provides an example of 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, 8 light devices supporting one on-offf cluster have been added as endpoints.
Matter bridge and NUCLEO-H753ZI-Q board example |
---|
1.3.2. Required boards
The Matter bridge runs on:
1.3.3. Package content
Download the required files on Github
1.3.4. How to perform remote software update (OTA)
TBD
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
[[Category:Matter|20]]