Matter test and demonstrate

Revision as of 12:53, 23 May 2024 by Registered User (Highlight that credentials in CHIPTool shall match with the active configuration on Thread Border Router side)

1. Overview

The following figure (from CSA) illustrates a general network topology and the different device types.

Connectivity Matter network topology.png


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:

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

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 installed as a Matter commissioner/controller device. Alternatively, when CHIPTool is chosen for the demonstration and the Matter application control is not supported by the CHIPTool APK (this is the case for Window-App and Generic-Switch-App), the RaspberryPi and its integrated CHIPTool can be used in place of the smartphone
  • 1 x Wi-Fi access point
  • 1 x PC/Laptop for displaying STM32WB5MM-DK logs
  • 1 x PC or (Display + Keyboard) for commands and logs for demonstration using RaspberryPi


Connectivity Matter demo setup.png


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 requests to a Matter device with Lighting-App for CHIPTool APK, or any cluster request with other applications for RaspberryPi CHIPTool.

2. STM ecosystem

The STM ecosystem is created with a STM32MP1+RCP as the border router, and an android smartphone with the CHIPTool application as the commissioner and controller. Both are connected to the same Wi-Fi access point.
For the OTBR setup, go to the dedicated wiki page STM32 OpenThread Border Router.
Once the complete setup is done, start the commissioning on the controller side as follow:

CHIPTool.jpg

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.

UART log with QR Code link.png
QR Code generated.png

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

CHIPTool-Payload.jpg

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.

CHIPTool Pairing.png

On the end device side, the display screen shows that the device is connected over Bluetooth LE before switching to the Thread network:

CHIPTool-BLE.jpg
CHIPTool-Thread.jpg

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:
CHIPTool-Connected.jpg
  • End device side:
EndDevice-FabricCreated.jpg

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.

CHIPTool-Commands.png

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:

CHIPTool-Control.jpg

When the device is commissioned successfully, the following trace information are shown over the UART:

To start a new commissioning properly, it is good practice to factory reset the end device by pressing the SW1 button for at least 10 seconds, then clear the CHIPTool cache, and restart the app.

3. Raspberry Pi ecosystem

The Raspberry Pi ecosystem is created with a Raspberry Pi as the border router, and an android smartphone with the CHIPTool application as the commissioner and 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, TH image location link for Matter 1.1), and follow the guide to setup the OTBR.
Once the OTBR is ready and the device programmed with the needed application, two cases have to be distinguished:

  • Application for which the CHIPTool APK is used
  • Application for which the CHIPTool within RaspberryPi is used

3.1. Application for which the CHIPTool APK is used

In this case the demo procedure is the same as for STM ecosystem.

3.2. Application for which TH CHIPTool is used

Follow the Matter Test-Harness User Manual for the device commissioning procedure which is the same for all applications. At this stage, you can now use supported chip-tool commands for each application to command your end device. Commands results/effects can be observed on the RaspberryPi logs and for some commands on the device LCD. .

3.2.1. Window-App (Window covering) application

3.2.1.1. Commissioning

The end of a successful commissioning can be observed on the device's LCD screen. The following image shows the displayed message.

Window-App comissionning completed.png


3.2.1.2. App demonstration
  • Open window cover
./chip-tool windowcovering up-or-open <node_id> <endpoint_id>

The display should show the OPEN level in percentage from 0% to 100%, and "Lift finish" at the end.


  • Close window cover
./chip-tool windowcovering down-or-close <node_id> <endpoint_id>

The display should show the CLOSE level in percentage from 100% to 0%, and "Lift finish" at the end.


  • 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 to the target percentage level given as paramter, and "Lift finish" at the end.


  • Stop window cover motion
./chip-tool windowcovering stop motion <node_id> <endpoint_id>

It will stop the motion, and OPEN or CLOSE level won't reach the full limit of respectively 100% or 0%


3.2.2. Generic-Switch (Switch) application

Supported features are the momentary switch (short and long press) and the momentary switch release short and long press). The multi-press feature is not supported.

3.2.2.1. Commissioning

The end of a successful commissioning can be observed on the device's LCD screen. The following image shows the displayed message.

Generic-Switch-App comissionning completed.png


3.2.2.2. App demonstration
  • Read current position attribute
./chip-tool switch read current-position <node_id> <endpoint_id>

You should see the following pattern within the CHIPTool logs.

Generic-Switch-App chip tool current-position.png


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

Generic-Switch-App chip tool initial-press.png


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

Generic-Switch-App chip tool short-release.png


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

Generic-Switch-App chip tool long-press.png


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

Generic-Switch-App chip tool long-release.png

4. Other ecosystems: Apple, Amazon, Google, Samsung, ...

The STM32WB5MM-DK platform is used as any other Matter device with the following QR code:

QR Code generated.png

To connect the STM32WB5MM-DK to those ecosystems and perform a demonstration, follow the guide provided for each ecosystem.

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.