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:
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.
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.
In order to build the example, it is recommended to use a Linux distribution. Please visit the supported Operating Systems list 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.
There are two options for building this reference app:
build_examples.py framework.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.
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.
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.
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
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.
Please see the device specific readme file.