Matter develop and prototype

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

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

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

• 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

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 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.
The DataFactory subfolder contains a tool used to manage factory data and a readme file explaningf how to use the tool.

X-CUBE-MATTER folder structure: Utilities - APK

X-CUBE-MATTER folder structure: Utilities - OTA_Tools

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

• ED platforms supporting Thread
• ED platforms supporting Ethernet
• ED platform supporting Wi-Fi

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.

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.

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

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

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

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

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

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 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 and STM32WB5MM-DK Discovery kit

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

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. 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 version indicated by the release notes.

Connect physically your development platform to the PC running STM32CubeProgrammer.
Connect your platform using STM32Cubeprogrammer.

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

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

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.

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

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 the 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^® 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.
Note that addresses in 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.

Stack start address

Select the type of stack to be loaded in the STM32CubeWB package.
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

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

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.

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) over Matter

1.2.4.3.1 Firmware update procedure and environment overview

1.2.4.3.1.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. Once the file is fully copied to external flash memory then the OTA requestor triggers the installation of the image(s) into the internal flash using the SBSFU services.

1.2.4.3.1.2 Firmware update environment overview
The following figure shows the environment overview of the Matter OTA process. The environment overview displays the setup for an OTA (Over-The-Air) update process. The STM32WB55 Discovery board serves as the OTA Requestor End device, connected to Terminal C via an STLINK. The OTA Provider and Matter 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.

1.2.4.3.2 Matter OTA process- step-by-step setup

STEP 1: Raspberry Pi preparation
For Raspberry Pi (including RCP dongle) setup procedure, follow CSA instructions given in the Matter Test-Harness User Manual

STEP 2: 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 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.

- Two binaries available for a M4 core in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\XXX-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.

For firmware versioning there are two different levels: Matter stack level and SBSFU level.

1. Matter stack level
   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.
   
2. 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.

For the generation of the binary, the following projects shall be built in sequence to create the “SBSFU_XXX-App-SBSFU.bin” with current version to be loaded and be 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 SE (Secure Engine) binary integrated into 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.

The following image illustrates the compilation process described above.

SBSFU: Binaries compilation process

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 firmware on STM32WB5x 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.

STM32CubeProgrammer: SBSFU key provisioning

Your end device is all set to be updated with the newer software version of the Matter Application using the OTA process.

Warning

If an App-SBSFU;bin is installed, it sets up at the first boot some Option bytes (Read Out Protection/RDP and Write Protection/WRP1A_STRT) to activate protection mode. To be able to use again STM32CubeProgrammer to flash a binary, the Option bytes must be restored to deactivate protection. The procedure is the following: Launch the STM32CubeProgrammer application and connect the device Open the OB menu Replace the value of RDP (BB if protection is activated) by AA Replace the value of WRP1A_STRT (0x0 if protection is activated) by 0xFF Click on Apply button to validate the new values. After few seconds the OB are restored. So, disconnect from then reconnect the device to STM32CubeProgrammer and the binary programming will be again possible. The following figure illustrates the "Option bytes" setting for non-protection mode.

Option bytes setting for non-protection mode

STEP 3: 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. Now 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:

    #define CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING "1.3"

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

The VENDOR_ID and PRODUCT_ID values are either those defined in the config header file CHIPProjectConfig.h configuration file located in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\Lighting-App-SBSFU\Core\Inc folder (#define CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID 0xFFF1 and #define CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID 0x8004), or alternatively those from data factory when used for device parameters storage. In this latter case, the tool genFactoryData.py provided in X-CUBE-MATTER (X-CUBE-MATTER\Utilities\DataFactory) will be used to display factory data and get the VENDOR_ID and PRODUCT_ID values

For Example: 
python ./ota_image_tool.py create -v 0xFFF1 -p 0x8004 -vn 3 -vs "1.3" -da sha256 X-CUBE-MATTER\Utilities\OTA_Tools\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:

OTA file structure

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.

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

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

STEP 4: Perform the OTA

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 by pushing button B1 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.3.3 Firmware update over Matter - OTA Application 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

STM32WB5MM-DK 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)

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

- Front view

STM32WB55MM-DK board configuration: front view

• STLINK-V3PWR

STLINK power configuration: front view

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
   

4. Click on "TAKE CONTROL"
   

5. Configure the acquisition using these parameters:
   

6. Click on "START ACQUISITION"
7. Click on "POWER ON" to boot the STM32WB55MM-DK board
   

8. You should be now able to observe the following results:
   

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

1.3.2 Required boards

The Matter bridge runs on:

• STM32H753ZI

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