1. Overview
The following figure (from CSA) illustrates a general network topology and the different device types.
A Matter Fabric platform is composed of different equipment types:
- Matter end device
- Matter bridge
- Simple controller
- Combined controller and Border Router
Matter end devices
The STM end devices have been demonstrated with the following platforms:
- STM32 OpenThread Border Router (OTBR)
- Raspberry Pi (RPi)
- Google ecosystem
- Apple ecosystem
- Samsung ecosystem
- Amazon ecosystem
For the test and the demonstration, the STM32 Matter ED platform is programmed with one of the applications delivered in X-CUBE-MATTER:
- Lighting-App
- Window-App
- Generic-Switch-App
When Generic-Switch app is provided with low power enabled, there is no UART trace and device display is disabled. To get a more interactive demonstration of Matter functionality, it is suggested to disable low power. It can be done setting CFG_FULL_LOW_POWER to 0.
The operation mode for each ecosystem is presented in the following section.
For all ecosystems, the Matter network is composed of the following elements:
- 1 x STM32 Matter ED platform (e.g. STM32WBA65I-DK1) as the end device, programmed with the relevant firmware binaries
- 1 x OpenThread border router
- 1 x Smartphone with an ecosystem application or CHIPTool APK installed as a Matter commissioner/controller device. In case the Matter application control is not supported by the CHIPTool APK (this is the case for Window-App and Generic-Switch-App), a Linux machine (native or virtual) with Linux CHIPTool installed can be used as a Matter commissioner/controller. The Linux CHIPTool machine can be a RaspberryPi with the TH image or a Linux machine, both acting as a commissioner/controller. The Linux CHIPTool used in this demonstration section is the "Chip Tool Snap" from the snap packaging. Guidance for installation of this CHIPTool Snap, and its usage for commissioning and control, refer to the Canonical chip-tool-snap github.
- 1 x Wi-Fi access point
- 1 x PC/Laptop for programming or displaying the STM32 Matter ED platform logs. For terminal Tera Term configuration refer to Debug Logging
- 1 x PC or (display + keyboard) for commands and logs for demonstration using Raspberry Pi
The following three figures illustrate respectively:
- The demonstration setup using a smartphone as commissioner/controller
- The demonstration setup using a Linux PC with CHIPTool as commissioner/controller
- The demonstration setup using a standalone RPi with integrated CHIPTool as commissioner/controller
For a demonstration using CHIPTool APK (Android Package Kit), a zip file is embedded in the X-CUBE-MATTER at the utilities folder (...\X-CUBE-MATTER\Utilities\APK\app_debug_v_1_3.zip). Open the .zip file, get the application (CHIPTool_v1_3.apk), and install it on the device used as commissioner/controller. See top release notes for backward compatibility.
CHIPTool APK offers the following features:
- Scan the Matter QR code and display payload information to the user.
- Commission a Matter device.
- Send ON/OFF cluster commands to a Matter device with Lighting-App for CHIPTool APK, or any cluster request with other applications for Linux CHIPTool.
Matter bridge devices
The STM bridge devices have been demonstrated with the following platforms:
- Raspberry Pi (RPi)
- Google ecosystem
- Apple ecosystem
- Samsung ecosystem
- Amazon ecosystem
For an out of the box demonstration, the STM32 Matter bridge platform (currently only the NUCLEO-H753ZI board is supported) is programmed with the bridge application example (Bridge-App_debug.bin or Bridge-App_release.bin) delivered in X-CUBE-MATTER. This bridge application example is configured with six Lights On/Off virtual (simulated) bridged devices.
The Matter network is composed of the following elements:
- 1 x STM32 Matter bridge platform (NUCLEO-H753ZI board) as the bridge device including simulation of bridged devices, programmed with the bridge application binary
- 1 x OpenThread border router
- 1 x Linux machine (native or virtual) with Linux CHIPTool installed for demonstration in the Raspberry Pi ecosystem, as Matter commissioner/controller device and for CHIPTool logs. The Linux CHIPTool used in this demonstration section is the "Chip Tool Snap" from the snap packaging. Guidance for installation of this CHIPTool Snap, and its usage for commissioning and control, refer to the Canonical chip-tool-snap github.
- 1 x Smartphone with an ecosystem application for demonstration in the other ecosystems, as Matter commissioner/controller device.
- 1 x Wi-Fi access point
- 1 x PC/Laptop for programming or displaying the STM32 Matter bridge platform logs
The following two figures illustrate respectively:
- The demonstration setup using a smartphone as commissioner/controller
- The demonstration setup using a Linux PC with CHIPTool as commissioner/controller
To start the bridge application demonstration:
- Open a terminal with Tera Term VT (or another logging terminal)
- In the Tera Term window, open a connection to the COM port corresponding to the STM32 board
- The Matter STM32 bridge is ready to be paired to a Matter network (commissioning) when the following logs appear in the logging terminal
- The pairing parameters also logged in the logging terminal
- If commissioning is not performed within 15 minutes, the commissioning window will be closed as illustrated in the following figure, and it will be necessary to reset the bridge device to be able to attempt a new commissioning.
- Go to one of the following sections corresponding to continue the demonstration in the corresponding chosen ecosystem
2. STM ecosystem
The STM ecosystem is created with a STM32MP1+RCP as the border router, and either an android smartphone with the CHIPTool APK or a Linux machine with Linux CHIPTool as the commissioner and controller. Both the border router and the CHIPTool APK device are connected to the same Wi-Fi access point. Linux CHIPTool device is either connected to the Wi-Fi access point or directly to the STM32MP1 via Ethernet.
For the OTBR setup, go to the dedicated wiki page STM32 OpenThread Border Router.
2.1. Demonstrate Lighting-App using CHIPTool APK
2.1.1. Commissioning
Once the complete setup is done, start the commissioning on the controller side as follow:
The commissioning is done in PROVISION CHIP DEVICE WITH THREAD, where the user scans the QR code generated by the end device, and display the payload information. The controller must get the commissioning information from the Matter device. The data payload is encoded within a QR code, printed to the UART console by clicking on the following link from the UART log.
Once the QR code scanned, the CHIPTool app displays the default Thread credentials needed to establish a Thread network between the end device and the border router. Those credentials shall match with the active configuration on Thread border router side. Indeed, ChipTool does not get dynamically Thread credentials from border router, it is up to the end user to ensure that Thread configuration sent to end device is consistent with Thread border router one.
To initiate the commissioning over the Bluetooth® LE protocol, click on SAVE NETWORK and scan for discoverable Matter devices. Pair with the device and start the procedure.
On the end device side, the display screen shows that the device is connected over Bluetooth® LE (BLE connected) before switching to the Thread network (Network Joined):
At the successful end of the commissioning, the STM32 Matter ED is connected to the Matter network and the Fabric is created. The result on both controller and end device sides is shown below:
- Controller side:
- End device side:
2.1.2. App demonstration
At this stage, it is possible to pilot the light of the end device directly using the controller (here the CHIPTool APK app) by sending ON/OFF commands and changing the light level using the LIGHT ON/OFF & LEVEL CLUSTER.
On the end device side, the received commands are displayed on the LCD screen which shows the message LED ON when the ON command is pressed, and update the light level when the level cluster is modified as follow:
When the device is commissioned successfully, the following trace information are shown over the UART:
To start a new commissioning properly, it is mandatory to perform a factory reset by pressing the SW1 button for at least 10 seconds, then clear the CHIPTool cache, and restart the app.
2.2. Demonstrate window-app using Linux CHIPTool
2.2.1. Commissioning
Run the following command to obtain the Thread network dataset
sudo ot-ctl dataset active -x
Then run the discovery and pairing command
sudo chip-tool pairing ble-thread <node_id> hex:<Thread network dataset> 20202021 <discriminator_id>
The default PIN code is 20202021 and the default discriminator id is 3840
When the device successfully joins the Thread network during the commissioning procedure, this is indicated on the device's LCD screen as illustrated by the following picture.
The commissioning then continues on the Thread network, and if it fails this is indicated by a "fabric failed" on the device's LCD screen. The successful commissioning completion can be observed on the device's LCD screen ("fabric created") and on the device logs with the message "commissioning completed successfully".
2.2.2. App demonstration
Commands results/effects can be observed on the device LCD.
- Open window cover
sudo chip-tool windowcovering up-or-open <node_id> <endpoint_id>
The display should show the OPEN level in percentage from 5% to 95%, then "lift finish" (corresponding to 100%) at the end. This is illustrated by the following figure.
- Close window cover
sudo chip-tool windowcovering down-or-close <node_id> <endpoint_id>
The display should show the CLOSE level in percentage from 95% to 5%, then "lift finish" (corresponding to 0%) at the end. This is illustrated by the following figure.
- Lift window cover to a given position
sudo chip-tool windowcovering go-to-lift-percentage <percentage in units 0.01%> <node_id> <endpoint_id>
The display should show the OPEN or CLOSE level in percentage from the current percentage level (minus 5%) to the target percentage level given as parameter (minus 5%), then "Lift finish" (corresponding to the target position) at the end. The two following figures illustrate respectively:
- a Lift OPEN to 50% with as initial position the window completely closed
- a Lift CLOSE to 25% with as initial position the window completely opened
The percentage parameter value is 5000 for 50% and 2500 for 25%.
- Stop window cover motion
sudo chip-tool windowcovering stop-motion <node_id> <endpoint_id>
This command is launched while a Lift OPEN/CLOSE is ongoing and will result in stopping of the motion at the current OPEN/CLOSE level. The display then should show "Lift finish" just after the current percentage. The two following figures illustrate respectively:
- a stop motion during a Lift OPEN with as initial position the window completely closed
- a stop motion during a Lift CLOSE with as initial position the window completely opened
2.3. Demonstrating generic switch app using Linux CHIPTool
Supported features are the momentary switch (short and long press) and the momentary switch release (short and long press release).
Multi-press feature is not supported.
2.3.1. Commissioning
Run the following command to obtain the Thread network dataset:
sudo ot-ctl dataset active -x
Then run the discovery and pairing command:
sudo chip-tool pairing ble-thread <node_id> hex:<Thread network dataset> 20202021 <discriminator_id>
The default PIN code is 20202021 and the default discriminator id is 3840.
When the device joins the Thread network during the commissioning procedure, this is indicated on the device's LCD screen as illustrated by the following picture.
The commissioning then continues on the Thread network, and if it fails this is indicated by a "fabric failed" message on the device LCD screen. The successful commissioning completion can be observed on the device LCD screen ("fabric created") and on the device logs with the message "commissioning completed successfully".
2.3.2. App demonstration
Commands results/effects can be observed on the Raspberry Pi CHIPTool logs.
- Read current position attribute
sudo chip-tool switch read current-position <node_id> <endpoint_id>
You should see the following pattern within the CHIPTool logs.
- Subscription to events
The button B2 on the STM32WB5MM-DK board is used as the switch. Event notifications can be observed on the CHIPTool logs. For that, you need to activate the CHIPTool interactive mode by executing the following.
sudo chip-tool interactive start
For parameters <...> please refer the CHIPTool help.
- - Subscription to short press event
sudo chip-tool switch subscribe-event initial-press <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a short press to the button B2, you should see the following pattern within the CHIPTool logs.
- - Subscription to short release event
sudo chip-tool switch subscribe-event short-release <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a short press then release to the button B2, you should see the following pattern within the CHIPTool logs.
- - Subscription to long press event
sudo chip-tool switch subscribe-event long-press <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a long press to the button B2, you should see the following pattern within the CHIPTool logs.
3. Raspberry Pi ecosystem
The Raspberry Pi is mainly used for Matter Test Harness, but it can be used for Matter device demonstration. The Raspberry Pi ecosystem is created with a Raspberry Pi as the border router, and either an android smartphone with the CHIPTool APK or the Linux CHIPTool embedded in the TH image as the commissioner/controller.
For the RPi setup, get a Test Harness Raspberry Pi bootable image, flash it to the Raspberry Pi following the CSA instructions (Matter Test-Harness User Manual), and follow the guide to setup the OTBR.
Once the OTBR is ready and the device programmed with the chosen application, proceed to the demonstration using either CHIPTool APK for Lighting App or Linux CHIPTool within Raspberry Pi (standalone RPi) for any of the application.
3.1. Demonstrating Lighting-App using CHIPTool APK
In this case the demo procedure is the same as for STM ecosystem, only difference being that the RPi is used as OTBR instead of STM32MP1+RCP. .
3.2. Demonstrating Window-App using Linux CHIPTool
3.2.1. Commissioning
Follow the Matter Test-Harness User Manual for the device commissioning procedure.
When the device successfully joins the Thread network during the commissioning procedure, this is indicated on the device LCD screen as illustrated by the following picture.
The commissioning then continues on the Thread network, and if it fails this is indicated by a "fabric failed" message on the device's LCD screen. The successful commissioning completion can be observed on the device logs with the message "commissioning completed successfully".
3.2.2. App demonstration
Commands results/effects can be observed on the device LCD.
- Open window cover
./chip-tool windowcovering up-or-open <node_id> <endpoint_id>
The display should show the OPEN level in percentage from 5% to 95%, then "Lift finish" (corresponding to 100%) at the end. This is illustrated by the following figure.
- Close window cover
./chip-tool windowcovering down-or-close <node_id> <endpoint_id>
The display should show the CLOSE level in percentage from 95% to 5%, then "Lift finish" (corresponding to 0%) at the end. This is illustrated by the following figure.
- Lift window cover to a given position
./chip-tool windowcovering go-to-lift-percentage <percentage in units 0.01%> <node_id> <endpoint_id>
The display should show the OPEN or CLOSE level in percentage from the current percentage level (minus 5%) to the target percentage level given as parameter (minus 5%), then "Lift finish" (corresponding to the target position) at the end. The two following figures illustrate respectively:
- a Lift OPEN to 50% with as initial position the window completely closed
- a Lift CLOSE to 25% with as initial position the window completely opened--->
The percentage parameter value is 5000 for 50% and 2500 for 25%.
- Stop window cover motion
./chip-tool windowcovering stop-motion <node_id> <endpoint_id>
This command is launched while a Lift OPEN/CLOSE is ongoing and will result in stopping of the motion at the current OPEN/CLOSE level. The display then should show "Lift finish" just after the current percentage. The two following figures illustrate respectively:
- a stop motion during a Lift OPEN with as initial position the window completely closed
- a stop motion during a Lift CLOSE with as initial position the window completely opened
3.3. Demonstrating generic switch app using Linux CHIPTool
Supported features are the momentary switch (short and long press) and the momentary switch release (short and long press release).
Multi-press feature is not supported.
3.3.1. Commissioning
Follow the Matter Test-Harness User Manual for the device commissioning procedure.
When the device successfully joins the Thread network during the commissioning procedure, this is indicated on the device LCD screen as illustrated by the following picture.
The commissioning then continues on the Thread network, and if it fails this is indicated by a "fabric failed" message on the device's LCD screen. The successful commissioning completion can be observed on the device logs with the message "commissioning completed successfully".
3.3.2. App demonstration
Commands results/effects can be observed on the Raspberry Pi CHIPTool logs.
- Read current position attribute
./chip-tool switch read current-position <node_id> <endpoint_id>
You should see the following pattern within the CHIPTool logs.
- Subscription to events
The Button B2 on the STM32WB5MM-DK board is used as the switch. Event notifications can be observed on the CHIPTool logs. For that, you need to activate the CHIPTool interactive mode by executing the following.
./chip-tool interactive start
For parameters <...> please refer the chip-tool help.
- - Subscription to short press event
switch subscribe-event initial-press <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a short press to the button B2, you should see the following pattern within the CHIPTool logs.
- - Subscription to short release event
switch subscribe-event short-release <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a short press then release to the button B2, you should see the following pattern within the CHIPTool logs.
- - Subscription to long press event
switch subscribe-event long-press <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a long press to the button B2, you should see the following pattern within the CHIPTool logs.
- - Subscription to long release event
switch subscribe-event long-release <min-interval> <max-interval> <node_id> <endpoint_id>
Then, when you apply a long press then release to the button B2, you should see the following pattern within the CHIPTool logs.
3.4. Demonstrating Bridge-App using Linux CHIPTool
3.4.1. Commissioning
On the Linux CHIPTool PC you can check the commissionable status of the bridge device using the following command
./chip-tool discover commissionables
You should see the bridge device in the result. Then start the commissioning using the following pairing command
./chip-tool pairing onnetwork <node_id> <pin_code>
The node_id is any number that uniquely identify the bridge node in the Matter network, and the pin_code is a password with a default value of 20202021.
For example, with a node_id equal to 1 and the default pin_code, the pairing command will be the following:
./chip-tool pairing onnetwork 1 20202021
The successful commissioning completion can be observed on the logging terminal with the message "commissioning complete".
3.4.2. App demonstration
The bridge is configured to have a maximum of 8 devices, but the delivered example contains 6 pre-initialized virtual (simulated) bridged Lights On/Off devices (Light1 to Light6).
The identifiers of the endpoints attached to these devices are written at the beginning of the log:
Note: As you can observe from the above figure, endpoints for bridged devices take values from 3 to 8. The reason is that value 0 is dedicated to the root node endpoint and value 1 to n (n = 2 in the current use case) being for aggregators endpoints. Endpoints 3 to 8 correspond to devices Light1 to Light6.
CHIPTool commands are used to control ON/OFF Light devices, and the command result can be observed on logging terminal and/or CHIPTool logs.
- Light on while current state is OFF
./chip-tool onoff on <node_id> <endpoint_id>
- Light off while current state is ON
./chip-tool onoff off <node_id> <endpoint_id>
- Light toggle
./chip-tool onoff toggle <node_id> <endpoint_id>
In case of a successful command 'onoff on', 'onoff off' or 'on/off toggle', you should see the following patterns (for respectively 'off to on' and 'on to off') on the logging terminal:
- Light on/off status
./chip-tool onoff read on-off <node_id> <endpoint_id>
In case of a successful command 'onoff read on-off', you should see the following pattern within the CHIPTool logs:
- - 'OnOff: FALSE' if the status is OFF
- - 'OnOff: TRUE' if the status is ON
Command Line Interface (CLI) commands from the terminal can be used for several purposes.
With focus on the terminal, press the key 'Enter' and CLI commands help is displayed as shown in the following figure.
4. Other ecosystems (interoperability): Apple, Amazon, Google, Samsung, ...
The STM32 Matter device platform (end-device platform e.g. STM32WBA65I-DK1, or bridge platform e.g. STM32H753ZI) is used as any other Matter device with the provided QR code
- QR code for STM32 Matter end-device platform
- QR code for STM32 Matter bridge platform
To connect the STM32 Matter device to those ecosystems and perform a demonstration, follow the guide provided for each ecosystem.
For ST device types (applications provided in X-CUBE-MATTER) interoperability with the different ecosystems, refer to the "Matter Device Type Platform Compatibility Matrix" from CSA.
For the demonstration setup, refer to the Overview section
4.1. Apple ecosystem
The Apple ecosystem is created with an Apple HomePod Mini (with 16.1 or higher system version) as the border router, and an Apple iPhone (with iOS 16.1 or higher system version) with the Apple Home application (or any application that supports the Matter smart home standard) as the commissioner and controller. For a demonstration of the STM32 Matter device with an Apple ecosystem, follow this link.
4.2. Amazon ecosystem
The Amazon ecosystem is created with an Amazon Echo Hub as the border router, and an Alexa application as the commissioner and controller on an Android or iOS device. For a demonstration of the STM32 Matter device with an Amazon ecosystem, follow this link.
During the commissioning phase, Alexa (the controller) instructs the device to discover the surrounding Thread networks. The available list of Thread networks is sent to Alexa and displayed on the phone screen. The user is then invited to select one. If the selected network is known by Alexa, the commissioning will continue, otherwise Alexa will ask for the network key.
Note that Alexa checks the serial number during the device commissioning. Therefore, when several STM32 Matter device kits are used in a demonstration, it is necessary to modify the serial number, as described in Serial number modification, to differentiate the different kits.
4.3. Google ecosystem
The Google ecosystem is created with a Google Nest Hub 2nd-gen as the border router, and an Android device with the Google Home Application (GHA) as the commissioner and controller. For a demonstration of the STM32 Matter device with a Google ecosystem, follow this link.
4.4. Samsung ecosystem
The Samsung ecosystem is created with a SmartThings Station as the border router, and an Android device with the SmartThings Application, or an iOS device running iOS 16.2 or higher and SmartThings Application version 1.6.94 or higher as the commissioner and controller. For a demonstration of the STM32 Matter device with a Samsung ecosystem, follow this link.
5. Multifabric
For a multifabric demonstration, select the first fabric, and commission the device in this fabric. Then follow the guide provided by the related ecosystem on how to commission a device in other ecosystems.