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
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 STM32WB5MM-DK end device platform is programmed with one of the applications delivered in X-CUBE-MATTER:
- Lighting-App
- Window-App
- Generic-Switch-App
Note that when low power is enabled for an application, the UART traces and the device display are disabled. For demonstration it could be useful to observe UART traces and messages displayed on the device screen. For that, you can disable the low power by setting CFG_FULL_LOW_POWER to 0 (#define CFG_FULL_LOW_POWER 0) in the app_conf.h located in ...\Projects\STM32WB5MM-DK\Applications\Matter\XXX-App\Core\Inc. The Generic-Switch-App delivered in the X-CUBE-MATTER is configured with low power, so for demonstration the user must disable low power and regenerate the binary.
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 STM32WB5MM-DK board as the end device, flashed 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.
- 1 x Wi-Fi access point
- 1 x PC/Laptop for programming or displaying STM32WB5MM-DK logs
- 1 x PC or (Display + Keyboard) for commands and logs for demonstration using RaspberryPi
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_1_0\Utilities\APK\app_debug_v_1_1.zip). Open the .zip file, get the application (CHIPTool_v1_1.apk), and install it on the device used as commissioner/controller. See top release notes for backward compatibility.
CHIPTool 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.
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.
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.
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 before switching to the Thread network:
At the end of the commissioning, the STM32WB5MM-DK device 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" message on the device's LCD screen. The successful commissioning completion can be observed 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 50% with as initial position the window completely opened
The percentage parameter value for 50% is set to 5000.
- 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's LCD screen. The successful commissioning completion can be observed on the device logs with the message "Commissioning completed successfully".
2.3.2. App demonstration
Commands results/effects can be observed on the RaspberryPi 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 chip-tool 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.
- - Subscription to long release event
sudo chip-tool 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. 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 RaspberryPi (Standalone RPi) for any of the application.
3.1. Demonstrating Lignting-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 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" 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 50% with as initial position the window completely opened
The percentage parameter value for 50% is set to 5000.
- 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 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" 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 RaspberryPi 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.
4. Other ecosystems (interoperability): Apple, Amazon, Google, Samsung, ...
The STM32WB5MM-DK platform is used as any other Matter device with the following QR code:
To connect the STM32WB5MM-DK 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.
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 STM32WB5MM-DK 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 STM32WB5MM-DK 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 STM32WB5MM-DK 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 STM32WB5MM-DK 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 STM32WB5MM-DK 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.