# 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: - [Matter](https://github.com/project-chip/connectedhomeip) - [NXP github SDK](https://github.com/nxp-mcuxpresso/mcux-sdk) - [Matter NXP Contact Sensor Example Application](#matter-nxp-contact-sensor-example-application) - [Supported devices](#supported-devices) - [Introduction](#introduction) - [Device UI](#device-ui) - [Prerequisites for building](#prerequisites-for-building) - [Building](#building) - [Data model](#data-model) - [Manufacturing data](#manufacturing-data) - [Long Idle Time ICD Support](#long-idle-time-icd-support) - [Low power](#low-power) - [Flashing and debugging](#flashing-and-debugging) ## Supported devices - [k32w1](k32w1/README.md) - [mcxw71](mcxw71/README.md) ## 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](../../../docs/guides/BUILDING.md#prerequisites). - Make sure that below prerequisites are correctly installed (as described in [BUILDING.md](../../../docs/guides/BUILDING.md#prerequisites)) ``` 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](#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 `chip_with_factory_data=1` 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](../../../docs/platforms/nxp/nxp_manufacturing_flow.md). ### 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: ``` chip_with_low_power = 1 chip_openthread_ftd = false chip_with_ot_cli = 0 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.