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 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	Build target
Thingy:53	PCA20053	thingy53_nrf5340	thingy53_nrf5340_cpuapp

To commission the weather station device and control it remotely through a Thread 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 LE. See Thingy:53 application guide 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.

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 Thread disabled, and it must be paired with the Matter controller over Bluetooth LE to get configuration from it if you want to use the device within a Thread network. To do this, the device must be made discoverable over Bluetooth LE.

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.

Matter weather station build types

The Matter weather station application does not use a single prj.conf file. Configuration files are provided for different build types and they are located in the configuration/thingy53_nrf5340_cpuapp directory.

The prj.conf file represents a debug build type. Other build types are covered by dedicated files with the build type added as a suffix to the prj part, as per the following list. For example, the release build type file name is prj_release.conf. If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.

When the CONF_FILE variable contains a single file and this file follows the naming pattern prj_<buildtype>.conf, then the build type will be inferred to be <buildtype>. The build type cannot be set explicitly. The <buildtype> can be any string, but it is common to use release and debug.

For information about how to set variables, see Important Build System Variables in the Zephyr documentation.

The Partition Manager’s static configuration can also be made dependent on the build type. When the build type has been inferred, the file pm_static_<buildtype>.yml will have precedence over pm_static.yml.

The child image Kconfig configuration can also be made dependent on the build type. The child image Kconfig file is named <child_image>.conf instead of prj.conf, but otherwise follows the same pattern as the parent Kconfig.

Before you start testing the application, you can select one of the build types supported by Matter weather station application, depending on the building method. This application supports the following build types:

• debug - Debug version of the application. You can use this version to enable additional features for verifying the application behavior, such as logs or command-line shell.

• release - Release version of the application. You can use this version to enable only the necessary application functionalities to optimize its performance.

• factory_data - Release version of the application that has factory data storage enabled. You can use this version to enable reading factory data necessary 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.

Note

Selecting a build type is optional. The debug build type is used by default if no build type is explicitly selected.

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.

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. See the Selecting a build type section to learn how to select the debug configuration.

NFC port with antenna attached:

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

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Building and running

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

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Selecting a build type

Before you start testing the application, you can select one of the Matter weather station build types, depending on your building method.

Selecting a build type in Visual Studio Code

To select the build type in the nRF Connect for VS Code extension:

1. When building an application as described in the nRF Connect for VS Code extension documentation, follow the steps for setting up the build configuration.

2. In the Add Build Configuration screen, select the desired .conf file from the Configuration drop-down menu.

3. Fill in other configuration options, if applicable, and click Build Configuration.

Selecting a build type from command line

To select the build type when building the application from command line, specify the build type by adding the following parameter to the west build command:

-- -DCONF_FILE=prj_selected_build_type.conf

For example, you can replace the selected_build_type variable to build the release firmware for thingy53_nrf5340_cpuapp by running the following command in the project directory:

west build -b thingy53_nrf5340_cpuapp -d build_thingy53_nrf5340_cpuapp -- -DCONF_FILE=prj_release.conf

The build_thingy53_nrf5340_cpuapp parameter specifies the output directory for the build files.

Note

If the selected board does not support the selected build type, the build is interrupted. For example, if the shell build type is not supported by the selected board, the following notification appears:

File not found: ./ncs/nrf/applications/matter_weather_station/configuration/thingy53_nrf5340_cpuapp/prj_shell.conf

Generating factory data

To enable factory data support, you need to select the factory_data build type from the available application build types. You can generate new factory data set when building for the target board by invoking the following command:

west build -b thingy53_nrf5340_cpuapp -- -DCONF_FILE=prj_factory_data.conf -DOVERLAY_CONFIG="../../overlay-factory_data_build.conf"

After building the 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:

west flash --erase

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:

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

2. Commission the device into a Thread network by following the steps in Matter over Thread: Configuring Border Router and Android controller on separate devices. 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 connectivity, LED (LD1) starts blinking purple (short flash on).

3. Read sensor measurements in CHIP Tool for Android:

   1. In the CHIP Tool for Android application main menu, tap the SENSOR CLUSTERS button to open the sensor measurements section. This section contains text boxes to enter Device ID and Endpoint ID, a drop-down menu with available measurements and two buttons, READ and WATCH.

      

      Sensor cluster section selection

      On this image, Device ID has the value 5 and Endpoint ID has the value 1.

   2. Select one of the available measurement types from the drop-down menu.

   3. Enter one of the following values for Endpoint ID, depending on the selected measurement type:

      • 1 - Temperature measurement

      • 2 - Relative humidity measurement

      • 3 - Air pressure measurement

   4. Tap the READ button to read and display the single measurement value.

      

      Single temperature measurement read

   5. Tap the WATCH button to start watching measurement changes in a continuous way and display values on a chart.

      

      Continuous temperature measurement watch

      The vertical axis represents the measurement values and the horizontal axis represents the current time.

   6. To change the displayed measurement, select a different measurement type from the drop-down list and enter the corresponding Endpoint ID value.

      

      Relative humidity measurement type selection

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 build type, you can also use one of the following onboarding information formats to provide the commissioner with the data required:

• For the debug and release build types:

  Weather station application onboarding information for the debug build type

  QR Code	QR Code Payload	Manual pairing code
  Scan the following QR code with the app for your ecosystem:	MT:M1TJ342C00KA0648G00	34970112332

• For the factory data build type:

  Weather station application onboarding information for the factory data build type

  QR Code	QR Code Payload	Manual pairing code
  Scan the following QR code with the app for your ecosystem:	MT:KAYA36PF1509673GE10	14575339844

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:

• DK Buttons and LEDs

• URI messages and records

• Type 2 Tag

The application depends on the following Zephyr libraries:

• Logging

• Kernel Services