Exceptionally, this wiki is under maintenance.

You can continue to browse it but contributors can not improve their favorite articles, during phase.

Thank you for your understanding.

Matter develop and prototype

Contents

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 mainly depends 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 preintegrated on STM32 microcontrollers. The Matter SDK middleware uses FreeRTOS™ and mbedTLS infrastructure. It is considered as a reference implementation to demonstrate and is ready for prototyping a Matter end-device on a 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 prototypes 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, Bluetooth® Low Energy, 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. The project offers infrastructure from partners for provisioning DAC private key into STM32 secure storage (CKS). It also provides a 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 [1] website.

1.1.2 X-CUBE-MATTER versions

The X-CUBE-MATTER versions contains 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
X-CUBE-MATTER architecture blog diagram
Connectivity Matter archi blog diagram.png
1.1.3.2 Component description

The X-CUBE-MATTER software components are made by a 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 components from connectedhomeip but adapted, or modified by ST to run on STM32 infrastructure.

OpenThread stack, Bluetooth® Low Energy 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.

The low power framework, when embedded, is implemented in the utilities component.

1.1.4 Folder structure

The X-CUBE-MATTER is conform with STM32CubeFW folders that are drivers, middleware, projects, and utilities, as illustrated in the figure below.

X-CUBE-MATTER folder structure: Main folders
Connectivity XCM Folder structure Main folders.png
  • 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
Connectivity XCM Folder structure Drivers.png
  • Middleware folder

The Middleware folder contains two main subfolders:

- ST subfolder which contains components used by SBSFU and the STM32_WPAN (Bluetooth® Low Energy, Thread) middleware components
- third-party subfolder which contains the connectedhomeip source code including the STM platform specific code, and also the FreeRTOS™ and mbedtls components. Each device/app subfolder contain part of the code generated with ZAP Tool (copied from zap-generated) for a given cluster,
X-CUBE-MATTER folder structure: Middlewares
Connectivity XCM Folder structure Middlewares.png
  • Projects folder

The following figures represent different views of the X-CUBE_MATTER project that respectively show where are located in the structure:

- the binary (under X-CUBE-MATTER\Projects\P-NUCLEO-WB55.Nucleo\Thread_RCP\Binaries subfolder) 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 subfolder) 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 ...\codegena\pp subfolder,
- 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) stored 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,
- 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.
X-CUBE-MATTER folder structure: Projects - RCP
Connectivity XCM Folder structure Projects 1.png
X-CUBE-MATTER folder structure: Projects - End device coprocessor
Connectivity XCM Folder structure Projects 2.png
X-CUBE-MATTER Folder structure: Projects - End device zap code
Connectivity XCM Folder structure Projects 3.png
X-CUBE-MATTER folder structure: Projects - End device application
Connectivity XCM Folder structure Projects 4.png
  • 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 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 subfolder contains scripts provided with 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.


X-CUBE-MATTER folder structure: Utilities - APK
Connectivity XCM Folder structure Utilities.png
X-CUBE-MATTER folder structure: Utilities - OTA_Tools
Connectivity XCM Folder structure Utilities 2.png

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® Low Energy 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 transport technology (Thread, Ethernet, or Wi-Fi)

Step 2: Select an ED platform supporting the chosen transport technology

Step 3: Get the X-CUBE-MATTER

Step 4: Regenerate the application binary using STM32CubeIDE

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 right ZAP tool version to be used.

Info white.png Information
If you already have .c / .h source files generated from another source, skip to section Integrate code into STM32CubeIDE.
1.2.2.1 Windows system setup 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 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.

Connectivity python install.png

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, for example, 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 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, for example, 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 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 are very similar to what is described here.

1.2.2.3 Generate files in ZAP
Info white.png Information
To certify your device, you need to design the endpoint and clusters according to the Matter specification. The specification files are available for CSA members here. For 'hobby' and other use-cases, you can design devices, which do not conform to this, but you still need to have at least the mandatory clusters implemented to be compatible with the available OTBRs and controllers. In this case, we recommend working with the example projects available in the connectedhomeip repository.

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 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 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
Optional cluster settings in ZAP
Connectivity zap cluster.png
Connectivity zap attrs.png


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.

Save project and generate files in ZAP
Connectivity zap save.png
Connectivity zap generate.png


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 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.

Warning white.png Warning

Currently (in Matter SDK v1.1), the scenes cluster (required by some endpoints) is not available / supported yet by the Matter stack and including it produces compilation errors. You can set it up in ZAP and it will then show in the device appearance. But actually adding the cluster code to the project as shown in this section will not work.


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

The file CHIPClientCallbacks.h is needed only when an OTA Provider cluster is included. This is not the case of the end device, which is an 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, and keep 'update references'.

Rename the project
Connectivity ide rename.png
Connectivity ide rename2.png


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
Connectivity copy files.png
Connectivity copy files2.png


Open the structure Middlewares\connectedhomeip\src\app\ and delete the existing PluginApplicationCallbacks.h file. Next, drag-and-drop the new PluginApplicationCallbacks.h in here same as before.

Open the 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 that was copied before. Now, for each callback in the .h file, check if the corresponding folder is included in STM32CubeIDE. If there is not the needed subfolder, do the following steps.

  • Create the subfolder in STM32CubeIDE with the same name as in file explorer, for example, 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 that is not specified in PluginApplicationCallbacks.h, you can delete the .h and .cpp files (unlink them from the 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 (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, ...) 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 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 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 STM32WB5x dual-core based platforms: P-NUCLEO-WB55[1] and STM32WB5MM-DK Discovery kit[2]
P-NUCLEO-WB55 STM32WB5MM-DK
Connectivity Nucleo-connection.jpg
Connectivity DK-connection.jpg


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 STLINK to be used
  • STM32WB5MM-DK Discovery kit: Jumper JP2 to 1-2 and USB STLINK 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 an 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 (Bluetooth® Low Energy - Thread for Matter application).

Programming the STM32WB5x consists in updating the FUS if needed and programming the two CPU cores (M0+ first, then M4).

In the 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 firmware version is the latest and make an upgrade if needed by using STM32CubeProgrammer[3].

In the matter context:

  • P-NUCLEO-WB55 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.1.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[3]. 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.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 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
Connectivity Dk1.png

Start FUS
When connected, go to the firmware upgrade services interface, and start the FUS, by clicking on the associated button.

STM32CubeProgrammer: start FUS
Connectivity 3-bis.png


Warning white.png Warning
If an error occurs while starting the FUS, reconnect the board and restart the FUS.


Once the FUS has started correctly, the following logs should be visible on the CubeProgrammer logs interface.

STM32CubeProgrammer: FUS started logs
Connectivity 4.png

Read FUS
Once the FUS is started read its value by clicking the Read FUS infos button

STM32CubeProgrammer: read FUS
Connectivity 5-bis.png

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 an example. Check the release notes to find the latest FUS version and the FUS start address.

FUS information
Connectivity 7-bis.png


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
Connectivity 6.png


- 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.

STM32CubeProgrammer: update FUS
Connectivity 7-trd.png


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
Connectivity 9.png

1.2.4.1.1.2 How to update the coprocessor wireless stack (BLE-Thread or Thread RCP)
The Bluetooth® Low Energy-Thread Stack (stm32wb5x_BLE_Thread_light_dynamic_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
Connectivity Copro wireless stack table.png

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_light_dynamic_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
Connectivity BLE-Thread stack installation.png
STM32CubeProgrammer: Thread stack installation
Connectivity Thread stack installation.png


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
Connectivity Start wireless stack.png
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
Connectivity M4 application installation.png
  • 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
Connectivity RCP M4 binary installation.png
1.2.4.2 How to customize your application
1.2.4.2.1 Bluetooth® Low Energy discriminator modification

Modifying the Bluetooth® Low Energy 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\<Platform>\Applications\Matter\Lighting-App\Core\Inc\CHIPProjectConfig.h, where <Platform> is the end device platform (for example, STM32WB5MM-DK):
      • 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:
#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 0xA00


  • In ...\X-CUBE-MATTER\Projects\<Platform>\Applications\Matter\Lighting-App\STM32_WPAN\App\app_ble.c, where <Platform> is the end device platform (for example, STM32WB5MM-DK):
    • Update the discriminator value in the manuf_data table (replace "0x00, 0x0F" by "0x00, 0x0A"):
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 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.
UART log with QR Code link.png
1.2.4.2.2 Serial number modification
  • In ...\X-CUBE-MATTER\Projects\<Platform>\Applications\Matter\Lighting-App\Core\Inc\CHIPProjectConfig.h, where <Platform> is the end device platform (for example, STM32WB5MM-DK), modify the value of the #define CHIP_DEVICE_CONFIG_TEST_SERIAL_NUMBER
  • Rebuild the project
  • Program the binary to M4 and reset the device
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.

Firmware update overview.png
1.2.4.3.2 How to create an OTA file
  • Binaries and keys

For a device based on a STM32WB, there are two types of binaries:

- One binary for a 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.

- There are two binaries available for a M4 core in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Lighting-App-SBSFU\Binary:
  • SBSFU_XXX-App-SBSFU.bin, which is an uncyphered 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 cyphered 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 cypher 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.
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 is displayed in the UART log for a result verification purpose.
For the generation of the above two binaries, the following projects shall be built in sequence:
  1. STM32WB-Matter-BLE-Thread\Projects\STM32WB5MM-DK\Applications\Matter\BLE_Ota\STM32CubeIDE\.project
  2. STM32WB-Matter-BLE-Thread\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SECoreBin\STM32CubeIDE\.project
  3. STM32WB-Matter-BLE-Thread\Projects\STM32WB5MM-DK\Applications\Matter\2_Images_SBSFU\STM32CubeIDE\.project
  4. STM32WB-Matter-BLE-Thread\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App-SBSFU\STM32CubeIDE\.project
  • 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.
python .\CreateMatterBin.py -m4 XXX-App.sfb -m0 stm32wb5x_BLE_Thread_light_dynamic_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.
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 M4M0-fw.bin M4M0-fw.ota


The parameter SOFTWARE_VERSION is the numerical (int) version number that must be equal to the numerical version CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION defined in the CHIPProjectConfig.h configuration file located in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Lighting-App-SBSFU\Core\Inc 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



For more details on these scripts, see the readme.txt file in the same folder (OTA_Tools).

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 (refer to the Projects folder for the 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 that 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 a M0 core (stm32wb5x_BLE_Thread_light_dynamic_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
Connectivity OTA setup.png

For the demonstration, follow the following steps:

Step 1: 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
Connectivity Key programming.png

Step 2: 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)

Step 3: 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 "Generation of Hex Code" as indicated in the guide. This is used during the commissioning of the end device.

cd ~/apps


  • On Terminal_C:

Start the OTA provider application and path it the Matter OTA file:

sudo ./chip-ota-provider-app -f MatterM4M0.ota


  • On Terminal_B:

Commission the OTA provider into network over IP, using the user-defined node id "1" and the setup PIN code "20202021" previously obtained.

sudo ./chip-tool pairing onnetwork 1 20202021


Write to the OTA provider accesscontrol cluster (node id 1, endpoint 0) the ACL data granting Operate privileges to all nodes in 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 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:

Provide the Matter 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


  • On Terminal_B:

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 = 1 for UpdateAvailable, provider endpoint = 0, requestor node = 3, requestor endpoint = 0.;

sudo ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 1 0 3 0


Once the device receives this announce, it requests the new software image.

  • On both Terminal_A and Terminal_C:
Observe the BDX (Bulk Data Exchange) transfer
  • Save provider information 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 (for example, 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
Connectivity STM32WB55MM-DK rear.png
- Front view
STM32WB55MM-DK board configuration: front view
Connectivity STM32WB55MM-DK front.png
  • STLINK-V3PWR
STLINK power configuration: front view
Connectivity STLink Power.png

The numbers on the above images refer to board connection steps listed in the next section.

1.2.4.4.2 Steps to connect STLINK V3 power to STM32WB55MM-DK board

First ensure that the STM32WB55MM-DK and STLINK-V3PWR are not powered by any power source.

  1. Download and install on the PC the STM32CubeMonPwr
  2. On STM32WB55MM-DK, remove the JP1 jumper (top view)
  3. Use a Dupont wire to connect OUT terminal of the STLINK-V3PWR and the left pin of JP1 of STM32WB55MM-DK (top view)
  4. Use a Dupont wire to connect a GND terminal of the STLINK-V3PWR and the GND pin of the CN1 connector of STM32WB55MM-DK (rear view)
  5. Use a Dupont wire to connect +5 V terminal of the STLINK-V3PWR (side) and the VIN pin of the CN2 connector of STM32WB55MM-DK (rear view)
  6. On JP2 connectors of STM32WB55MM-DK (top), move the jumper to the pins "5 V VIN"
1.2.4.4.3 Measurement execution
  1. Plug the STLINK-V3PWR to the PC
  2. Launch STM32CubeMonitor-Power (STM32CubeMonPwr)
  3. Select your board
    Connectivity Select Board.png
  4. Click on "TAKE CONTROL"
    Connectivity Take control.png
  5. Configure the acquisition using these parameters:
    Connectivity Acquisition params.png
  6. Click on "START ACQUISITION"
  7. Click on "POWER ON" to boot the STM32WB55MM-DK board
    Connectivity Power on.png
  8. You should be now able to observe the following results:
    Connectivity Measurement result.png

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)
Connectivity tera-term-1-2.png

Setup your serial connection as below:

Tera Term setup (2/2)
Connectivity tera-term-3-4.png

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 in a 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, eight light devices supporting one on-off cluster have been added as endpoints.

Matter bridge and NUCLEO-H753ZI-Q board example
Connectivity Matter Bridge.png

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.


3 References