Thingy:53: Matter weather station

This Matter weather station application demonstrates the usage of the Matter application layer to build a weather station device using the Nordic Thingy:53. Such a device lets you remotely gather different kinds of data using the device sensors, such as temperature, air pressure, and relative humidity. The device works as a Matter accessory device, meaning it can be paired and controlled remotely over a Matter network built on top of a low-power, 802.15.4 Thread or 802.11ax (Wi-Fi 6) network. You can use this application as a reference for creating your own application.

Note

The Matter weather station application from the v2.1.1 nRF Connect SDK release participated in Matter Specification Validation Event (SVE) and successfully passed all required test cases to be considered as a device compliant with Matter 1.0. You can use the nRF Connect SDK v2.1.1 release to see the application configuration and the files that were originally used in Matter 1.0 certification.

Requirements 

The application supports the following development kits:

Hardware platforms	PCA	Board name	Board target	Shields
Thingy:53	PCA20053	thingy53	`thingy53/nrf5340/cpuapp`	`nrf7002eb`

To commission the weather station device and control it remotely through a Thread or Wi-Fi network, you also need a Matter controller device configured on PC or smartphone. This requires additional hardware depending on your setup. The recommended way of getting measurement values is using the mobile Matter controller application that comes with a graphical interface, performs measurements automatically and visualizes the data.

To program a Thingy:53 device where the preprogrammed MCUboot bootloader has been erased, you need the external J-Link programmer. If you have an nRF5340 DK that has an onboard J-Link programmer, you can also use it for this purpose.

If the Thingy:53 is programmed with Thingy:53-compatible sample or application, you can also update the firmware using MCUboot’s serial recovery or DFU over Bluetooth® Low Energy (LE).

Note

If you build Matter Weather Station firmware with factory data support it will not be compatible with other Thingy:53 samples and applications. Then, the only way you can program the new firmware image is by flashing the board with J-Link programmer.

See Application guide for Thingy:53 for details.

Note

Matter requires the GN tool. If you are updating from the nRF Connect SDK version earlier than v1.5.0, see the GN installation instructions.

IPv6 network support 

The development kits for this sample offer the following IPv6 network support for Matter:

Matter over Thread is supported for thingy53/nrf5340/cpuapp.
Matter over Wi-Fi is supported for thingy53/nrf5340/cpuapp with the nrf7002 expansion board attached, for the release configuration only. See Building for the nRF7002 Wi-Fi expansion board for more information.

Overview 

The application uses a single button for controlling the device state. The weather station device is periodically performing temperature, air pressure, and relative humidity measurements. The measurement results are stored in the device memory and can be read using the Matter controller. The controller communicates with the weather station device over the Matter protocol using Zigbee Cluster Library (ZCL). The library describes data measurements within the proper clusters that correspond to the measurement type.

The application supports over-the-air (OTA) device firmware upgrade (DFU) using one of the two following protocols:

Matter OTA update protocol that uses the Matter operational network for querying and downloading a new firmware image.
Simple Management Protocol (SMP) over Bluetooth LE. In this case, the DFU can be done either using a smartphone application or a PC command line tool. Note that this protocol is not part of the Matter specification.

In both cases, MCUboot secure bootloader is used to apply the new firmware image. For information about how to upgrade the device firmware using a PC or a mobile, see the Updating the device firmware section.

Remote testing in a network 

By default, the Matter accessory device has no IPv6 network configured. You must pair it with the Matter controller over Bluetooth LE to get the configuration from the controller to use the device within a Thread or Wi-Fi network.

The Bluetooth LE advertising starts automatically upon the device startup, but only for a predefined period of time (15 minutes by default). If the Bluetooth LE advertising times out, you can re-enable it manually using Button (SW3).

Additionally, the controller must get the Onboarding information from the Matter accessory device and provision the device into the network. For details, see the Testing section.

User interface 

LED (LD1):

Shows the overall state of the device and its connectivity. The following states are possible:

Short flash on (green color, 50 ms on/950 ms off) - The device is in the unprovisioned (unpaired) state and is not advertising over Bluetooth LE.
Short flash on (blue color, 50 ms on/950 ms off) - The device is in the unprovisioned (unpaired) state, but is advertising over Bluetooth LE.
Rapid even flashing (blue color, 100 ms on/100 ms off) - The device is in the unprovisioned state and a commissioning application is connected through Bluetooth LE.
Short flash on (purple color, 50 ms on/950 ms off) - The device is fully provisioned and has Thread enabled or has Wi-Fi connection established.
Rapid even flashing after commissioning (blue color, 100 ms on/100 ms off) - The device lost connection to Wi-Fi network (only in Wi-Fi mode).

Note

Thingy:53 allows to control RGB components of its single LED independently. This means that the listed color components can overlap, creating additional color effects.

Button (SW3):

Used during the commissioning procedure. Depending on how long you press the button:

If pressed for 6 seconds, it initiates the factory reset of the device. Releasing the button within the 6-second window cancels the factory reset procedure.
If pressed for less than 3 seconds, it starts the NFC tag emulation, enables Bluetooth LE advertising for the predefined period of time (15 minutes by default), and makes the device discoverable over Bluetooth LE.

USB port:

Used for getting logs from the device or communicating with it through the command-line interface. It is enabled only for the debug configuration of an application.

NFC port with antenna attached:

Used for obtaining the Onboarding information from the Matter accessory device to start the commissioning procedure.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Matter weather station custom configurations 

The Matter weather station application uses a prj.conf configuration file located in the root directory for the default configuration. It also provides additional files for different custom configurations. When you build the application, you can select one of these configurations using the FILE_SUFFIX variable.

See Custom configurations and Providing CMake options for more information.

The application supports the following configurations:

Matter weather station configurations
Configuration	File name	FILE_SUFFIX	Supported board	Description
Debug (default)	`prj.conf`	No suffix	All from Requirements	Debug version of the application. Enables additional features for verifying the application behavior, such as logs.
Release	`prj_release.conf`	`release`	All from Requirements	Release version of the application. Enables only the necessary application functionalities to optimize its performance. Currently, only the release configuration is supported when Building for the nRF7002 Wi-Fi expansion board.

Matter weather station build configuration overlays 

The application comes with the following overlays:

overlay-factory_data - factory data storage support enabled. You can use this optional configuration overlay to enable reading necessary factory data from a separate partition in the device non-volatile memory. This way, you can read information such as product information, keys, and certificates, useful for example for Matter certification. See Generating factory data to learn how to put factory data into device’s storage. To learn more about factory data, read the Configuring factory data for the nRF Connect examples page in the Matter documentation.

This overlay requires providing of the pm_static_factory_data.yml Partition Manager static configuration file.

To build the example with the factory data support, run the following command:
```
west build -b thingy53/nrf5340/cpuapp -- -DEXTRA_CONF_FILE=overlay-factory_data.conf -DPM_STATIC_YML_FILE=pm_static_factory_data.yml
```

Note

Matter factory data support requires the dedicated partition layout. This means that if you build the application using the overlay-factory_data configuration overlay, it will not be compatible with other Thingy:53 applications and samples.

Building and running 

This sample can be found under applications/matter_weather_station in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Selecting a configuration 

Before you start testing the application, you can select one of the Matter weather station custom configurations. See Custom configurations and Providing CMake options for more information how to select a configuration.

Building for the nRF7002 Wi-Fi expansion board 

To build this application to work with the nRF7002 Wi-Fi expansion board:

Connect the nRF7002 EB to the P9 connector on Thingy:53.
Build the application:
To build the application in the nRF Connect for VS Code IDE for Thingy:53 with the nRF7002 EB attached, add the expansion board and the file suffix variables in the build configuration’s Extra CMake arguments and rebuild the build configuration. For example: -- -Dmatter_weather_station_SHIELD=nrf7002eb -DFILE_SUFFIX=release -DSB_CONFIG_WIFI_NRF700X=y.
To build the sample from the command line for Thingy:53 with the nRF7002 EB attached, use the following command within the sample directory:
west build -b thingy53/nrf5340/cpuapp -- -Dmatter_weather_station_SHIELD=nrf7002eb -DFILE_SUFFIX=release -DSB_CONFIG_WIFI_NRF700X=y

Generating factory data 

To enable factory data support, you need to select the overlay-factory_data configuration overlay from the available application build configuration overlays, set the SB_CONFIG_MATTER_FACTORY_DATA_GENERATE kconfig option to y, and use the factory_data file suffix. You can generate new factory data set when building for the given board target by invoking the following command:

west build -b thingy53/nrf5340/cpuapp -- -DEXTRA_CONF_FILE=overlay-factory_data.conf -DSB_CONFIG_MATTER_FACTORY_DATA_GENERATE=y -DFILE_SUFFIX=factory_data

This command builds the application with default certificates. After building for the board target, the generated factory_data.hex file will be merged with the application target HEX file, so you can use the regular command to flash it to the device.

If you want to use Vendor ID, Product ID or other data that is not reserved for tests, you need custom test certificates. To build with custom certificates, you need to install CHIP Certificate Tool.

Testing 

Note

The testing procedure assumes you are using the CHIP Tool for Android Matter controller application. You can also obtain the measurement values using the PC-based CHIP Tool for Linux and iOS Matter controller and invoking the read commands manually. Compared with the PC Matter controller, the mobile Matter controller only gives access to a subset of clusters supported by the Matter weather station application. If you want to access all the supported clusters, including Descriptor, Identify, and Power Source clusters, use the PC Matter controller. To see how to send commands from the PC Matter controller, read the Working with the CHIP Tool page in the Matter documentation.

After programming the application, perform the following steps to test the Matter weather station application on the Thingy:53 with the mobile Matter controller application:

Turn on the Thingy:53. The application starts in an unprovisioned state. The advertising over Bluetooth LE and DFU start automatically, and LED (LD1) starts blinking blue (short flash on).
Commission the device to the network of your choice:
- For Thread network, follow the steps in Matter over Thread: Configuring Border Router and Linux/macOS controller on separate devices.
- For Wi-Fi network, follow the steps in Matter over Wi-Fi: Configuring CHIP Tool for Linux or macOS.
During the commissioning procedure, LED (LD1) of the Matter device starts blinking blue (rapid even flashing). This indicates that the device is connected over Bluetooth LE, but does not yet have full Thread network connectivity.

Note

To start commissioning, the controller must get the Onboarding information from the Matter accessory device.

Once the commissioning is complete and the device has full Thread or Wi-Fi connectivity, LED (LD1) starts blinking purple (short flash on).
Request to read sensor measurements in CHIP Tool for Linux or macOS:
1. Choose one of the following measurement type and invoke the command using CHIP Tool for Linux or macOS (Fill the Device ID argument with the same as was used to commissioning):
  - To read temperature:
    chip-tool temperaturemeasurement read measured-value <Device ID> 1
  - To read relative humidity:
    chip-tool relativehumiditymeasurement read measured-value <Device ID> 2
  - To read air pressure:
    chip-tool pressuremeasurement read measured-value <Device ID> 3
2. After invoking the chosen command, search the CHIP Tool for Linux or macOS console logs and look for the measurement value:
  - Example of the temperature measurement value log:
    [1675846190.922905][72877:72879] CHIP:TOO: Endpoint: 1 Cluster: 0x0000_0402 Attribute 0x0000_0000 DataVersion: 1236968801 [1675846190.922946][72877:72879] CHIP:TOO: MeasuredValue: 2348
    
    This means that the current temperature value is equal to 23.48°C.
  - Example of the relative humidity measurement value log:
    [1675849697.750923][164859:164861] CHIP:TOO: Endpoint: 2 Cluster: 0x0000_0405 Attribute 0x0000_0000 DataVersion: 385127250 [1675849697.750953][164859:164861] CHIP:TOO: measured value: 2526
    
    This means that the current relative humidity value is equal to 25.26%.
  - Example of the air pressure measurement value log:
    [1675849714.536985][164896:164898] CHIP:TOO: Endpoint: 3 Cluster: 0x0000_0403 Attribute 0x0000_0000 DataVersion: 3096547 [1675849714.537008][164896:164898] CHIP:TOO: MeasuredValue: 1015
    
    This means that the current air pressure value is equal to 1015 hPa.

Onboarding information

When you start the commissioning procedure, the controller must get the onboarding information from the Matter accessory device. The onboarding information representation depends on your commissioner setup.

For this application, the data payload, which includes the device discriminator and setup PIN code, is encoded and shared using an NFC tag. When using the debug configuration, you can also get this type of information from the USB interface logs.

Alternatively, depending on your configuration and selected overlay, you can also use one of the following onboarding information formats to provide the commissioner with the data required:

For the debug and release configurations:

Weather station application onboarding information for the debug or release configurations
QR Code	QR Code Payload	Manual pairing code
Scan the following QR code with the app for your ecosystem:	MT:M1TJ342C00KA0648G00	34970112332

Additionally, if the factory data build configuration overlay is selected:

Weather station application onboarding information for the factory data build configuration overlay
QR Code	QR Code Payload	Manual pairing code
Scan the following QR code with the app for your ecosystem:	MT:KAYA36PF1509673GE10	14575339844

This data payload also includes test Device Attestation, with test Certification Declaration, Product ID, and Vendor ID. These are used for Device Attestation within commissioning, and you can generate your own test Certification Declaration when you work on Matter end product.

Updating the device firmware 

To update the device firmware, complete the steps listed for the selected method in the Performing Device Firmware Upgrade in the nRF Connect examples tutorial in the Matter documentation.

Dependencies 

This application uses the Matter library, which includes the nRF Connect SDK platform integration layer:

Matter

In addition, the application uses the following nRF Connect SDK components:

The application depends on the following Zephyr libraries: