Matter NXP Contact Sensor Example Application#

This reference application implements a Contact Sensor device type. It uses board buttons or matter-cli for user input and LEDs for state feedback. You can use this example as a reference for creating your own application.

The example is based on:

Supported devices#

Introduction#

The application showcases a contact sensor that communicates with clients over a low-power, 802.15.4 Thread network.

It can be commissioned into an existing Matter network using a controller such as chip-tool.

This example implements a User-Intent Commissioning Flow, meaning the user has to press a button in order for the device to be ready for commissioning. The initial commissioning is done through ble-thread pairing method.

The Thread network dataset will be transferred on the device using a secure session over Bluetooth LE. In order to start the commissioning process, the user must enable BLE advertising on the device manually. To pair successfully, the commissioner must know the commissioning information corresponding to the device: setup passcode and discriminator. This data is usually encoded within a QR code or printed to the UART console.

Device UI#

The example application provides a simple UI that depicts the state of the device and offers basic user control. This UI is implemented via the general-purpose LEDs and buttons built in the evaluation boards. Please see each supported device readme file for details.

Prerequisites for building#

In order to build the example, it is recommended to use a Linux distribution. Please visit the supported Operating Systems list in BUILDING.md.

  • Make sure that below prerequisites are correctly installed (as described in BUILDING.md)

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

  • Step 1: checkout NXP specific submodules only

    user@ubuntu:~/Desktop/git/connectedhomeip$ scripts/checkout_submodules.py --shallow --platform nxp --recursive

  • Step 2: activate local environment

    user@ubuntu:~/Desktop/git/connectedhomeip$ source scripts/activate.sh

    If the script says the environment is out of date, you can update it by running the following command:

    user@ubuntu:~/Desktop/git/connectedhomeip$ source scripts/bootstrap.sh

  • Step 3: Init NXP SDK(s)

    user@ubuntu:~/Desktop/git/connectedhomeip$ third_party/nxp/nxp_matter_support/scripts/update_nxp_sdk.py --platform common

Note: By default, update_nxp_sdk.py will try to initialize all NXP SDKs. Please run the script with arg --help to view all available options.

Building#

There are two options for building this reference app:

  • Using build_examples.py framework.

  • Manually generating ninja files using gn.

For manual generation and building, please see the specific readme file for your device.

A list of all available contact sensor targets can be viewed in the following table:

target name

description

nxp-device-freertos-contact-sensor-low-power

Default low-power contact sensor

nxp-device-freertos-contact-sensor-low-power-factory

Default low-power contact sensor with factory data

nxp-device-freertos-contact-sensor-low-power-lit

Low-power contact sensor as LIT ICD

nxp-device-freertos-contact-sensor-low-power-sw-v2

Low-power contact sensor with software version 2 (can be used to test OTA)

nxp-device-freertos-contact-sensor-low-power-factory-sw-v2

Low-power contact sensor with factory data and software version 2 (can be used to test OTA)

where device can be one of the Supported devices.

Data model#

There are two available data models that can be used by the application:

path

description

zap-lit/contact-sensor-app.zap

Data model for LIT ICD support

zap-sit/contact-sensor-app.zap

Data model for SIT ICD support

The selection is done automatically by the build system based on the ICD configuration.

The data model can be changed by simply replacing the gn deps statement corresponding to data model target.

Manufacturing data#

Use nxp_use_factory_data=true in the gn build command to enable factory data.

For a full guide on manufacturing flow, please see Guide for writing manufacturing data on NXP devices.

Long Idle Time ICD Support#

By default, the application is compiled as a SIT ICD (Short Idle Time Intermittently Connected Device).

This is a list of ICD configuration gn args.

gn arg

default value

description

nxp_ot_idle_interval_ms

2000 (ms)

OT Idle Interval duration

nxp_ot_active_interval_ms

500 (ms)

OT Active Interval duration

nxp_idle_mode_duration_s

600 (s)

Idle Mode Interval duration

nxp_active_mode_duration_ms

10000 (ms)

Active Mode Interval duration

nxp_active_mode_threshold_ms

1000 (ms)

Active Mode Threshold value

nxp_icd_supported_clients_per_fabric

2

Registration slots per fabric

chip_enable_icd_lit

false

Enable LIT ICD support

chip_enable_icd_dsls

false

Enable LIT ICD DSLS support

chip_persist_subscriptions

true

Try once to re-establish subscriptions from the server side after reboot. May be disabled for LIT use case

chip_subscription_timeout_resumption

true

Same as above, but try to re-establish timeout out subscriptions

using Fibonacci Backoff for retries pacing. May be disabled for LIT use case

If LIT ICD support is needed then chip_enable_icd_lit=true must be specified as gn argument and the above parameters must be modified to comply with LIT requirements (e.g.: LIT devices must configure chip_ot_idle_interval_ms > 15000). Example LIT configuration:

nxp_ot_idle_interval_ms = 15000           # 15s Idle Intervals
nxp_ot_active_interval_ms = 500           # 500ms Active Intervals
nxp_idle_mode_duration_s = 3600           # 60min Idle Mode Interval
nxp_active_mode_duration_ms = 0           # 0 Active Mode Interval
nxp_active_mode_threshold_ms = 30000      # 30s Active Mode Threshold

Low power#

The example also offers the possibility to run in low power mode. This means that the board will go in deep sleep most of the time and the power consumption will be very low.

In order to build with low power support, the following gn args must be used:

nxp_use_low_power = true
chip_openthread_ftd = false
nxp_enable_ot_cli = false
chip_logging = false

In order to maintain a low power consumption, the UI LEDs are disabled. Console logs can be used instead, but it might affect low power timings. Also, please note that once the board is flashed with MCUXpresso the debugger disconnects because the board enters low power.

Flashing and debugging#

Please see the device specific readme file.