| # Matter nRF Connect Window Covering Example Application |
| |
| The nRF Connect Window Covering Example demonstrates how to remotely control a |
| window shutter device. It uses buttons to test changing cover position and |
| device states and LEDs to show the state of these changes. You can use this |
| example as a reference for creating your own application. |
| |
| <img src="../../platform/nrfconnect/doc/images/Logo_RGB_H-small.png" alt="Nordic Semiconductor logo"/> |
| <img src="../../platform/nrfconnect/doc/images/nRF52840-DK-small.png" alt="nRF52840 DK"> |
| |
| The example is based on |
| [Matter](https://github.com/project-chip/connectedhomeip) and Nordic |
| Semiconductor's nRF Connect SDK, and supports remote access and control of a |
| simulated window shutter over a low-power, 802.15.4 Thread network. |
| |
| The example behaves as a Matter accessory, that is a device that can be paired |
| into an existing Matter network and can be controlled by this network. |
| |
| <hr> |
| |
| ## Overview |
| |
| This example is running on the nRF Connect platform, which is based on Nordic |
| Semiconductor's |
| [nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html) |
| and [Zephyr RTOS](https://zephyrproject.org/). Visit Matter's |
| [nRF Connect platform overview](../../../docs/guides/nrfconnect_platform_overview.md) |
| to read more about the platform structure and dependencies. |
| |
| The Matter device that runs the window shutter application is controlled by the |
| Matter controller device over the Thread protocol. By default, the Matter |
| accessory device has IPv6 networking disabled. 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. You have to make the device |
| discoverable manually (for security reasons). See |
| [Bluetooth LE advertising](#bluetooth-le-advertising) to learn how to do this. |
| The controller must get the commissioning information from the Matter accessory |
| device and provision the device into the network. |
| |
| You can test this application remotely over the Thread or the Wi-Fi protocol, |
| which in either case requires more devices, including a Matter controller that |
| you can configure either on a PC or a mobile device. |
| |
| ### Bluetooth LE advertising |
| |
| In this example, to commission the device onto a Matter network, it must be |
| discoverable over Bluetooth LE. For security reasons, you must start Bluetooth |
| LE advertising manually after powering up the device by pressing **Button 4**. |
| |
| ### Bluetooth LE rendezvous |
| |
| In this example, the commissioning procedure is done over Bluetooth LE between a |
| Matter device and the Matter controller, where the controller has the |
| commissioner role. |
| |
| To start the rendezvous, the controller must get the commissioning information |
| from the Matter device. The data payload is encoded within a QR code, printed to |
| the UART console, and shared using an NFC tag. NFC tag emulation starts |
| automatically when Bluetooth LE advertising is started and stays enabled until |
| Bluetooth LE advertising timeout expires. |
| |
| #### Thread provisioning |
| |
| Last part of the rendezvous procedure, the provisioning operation involves |
| sending the Thread network credentials from the Matter controller to the Matter |
| device. As a result, device is able to join the Thread network and communicate |
| with other Thread devices in the network. |
| |
| ### Device Firmware Upgrade |
| |
| The example supports over-the-air (OTA) device firmware upgrade (DFU) using the |
| Matter OTA update, which is mandatory for Matter-compliant devices and enabled |
| by default. |
| |
| For this method, the |
| [MCUboot](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/mcuboot/index.html) |
| bootloader solution is used to replace the old firmware image with the new one. |
| |
| #### Matter Over-the-Air Update |
| |
| The Matter over-the-air update distinguishes two types of nodes: OTA Provider |
| and OTA Requestor. |
| |
| An OTA Provider is a node that hosts a new firmware image and is able to respond |
| on an OTA Requestor's queries regarding availability of new firmware images or |
| requests to start sending the update packages. |
| |
| An OTA Requestor is a node that wants to download a new firmware image and sends |
| requests to an OTA Provider to start the update process. |
| |
| #### Simple Management Protocol |
| |
| Simple Management Protocol (SMP) is a basic transfer encoding that is used for |
| device management purposes, including application image management. SMP supports |
| using different transports, such as Bluetooth LE, UDP, or serial USB/UART. |
| |
| In this example, the Matter device runs the SMP Server to download the |
| application update image using the Bluetooth LE transport. |
| |
| See the |
| [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) |
| section to learn how to enable SMP and use it for the DFU purpose in this |
| example. |
| |
| #### Bootloader |
| |
| MCUboot is a secure bootloader used for swapping firmware images of different |
| versions and generating proper build output files that can be used in the device |
| firmware upgrade process. |
| |
| The bootloader solution requires an area of flash memory to swap application |
| images during the firmware upgrade. Nordic Semiconductor devices use an external |
| memory chip for this purpose. The memory chip communicates with the |
| microcontroller through the QSPI bus. |
| |
| See the |
| [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) |
| section to learn how to change MCUboot and flash configuration in this example. |
| |
| <hr> |
| |
| ## Requirements |
| |
| The application requires a specific revision of the nRF Connect SDK to work |
| correctly. See [Setting up the environment](#setting-up-the-environment) for |
| more information. |
| |
| ### Supported devices |
| |
| The example supports building and running on the following devices: |
| |
| | Hardware platform | Build target | Platform image | |
| | ----------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | |
| | [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` | <details><summary>nRF52840 DK</summary><img src="../../platform/nrfconnect/doc/images/nRF52840_DK_info-medium.jpg" alt="nRF52840 DK"/></details> | |
| | [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` | <details><summary>nRF5340 DK</summary><img src="../../platform/nrfconnect/doc/images/nRF5340_DK_info-medium.jpg" alt="nRF5340 DK"/></details> | |
| |
| <hr> |
| |
| ## Device UI |
| |
| This section lists the User Interface elements that you can use to control and |
| monitor the state of the device. These correspond to PCB components on the |
| platform image. |
| |
| **LED 1** shows the overall state of the device and its connectivity. The |
| following states are possible: |
| |
| - _Short Flash On (50 ms on/950 ms off)_ — The device is in the |
| unprovisioned (unpaired) state and is waiting for a commissioning |
| application to connect. |
| |
| - _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the |
| unprovisioned state and a commissioning application is connected through |
| Bluetooth LE. |
| |
| - _Short Flash Off (950ms on/50ms off)_ — The device is fully |
| provisioned, but does not yet have full connectivity for Thread or Wi-Fi |
| network. |
| |
| - _Solid On_ — The device is fully provisioned and has full Thread |
| network and service connectivity. |
| |
| **LED 2** indicates the lift position of the shutter, which is represented by |
| the brightness of the LED. The brightness level ranges from 0 to 255, where the |
| switched off LED with brightness level 0 indicates a fully opened shutter |
| (lifted) and 255 indicates a fully closed shutter (lowered). |
| |
| **LED 3** indicates the tilt position of the shutter, which is represented by |
| the brightness of the LED. The brightness level ranges from 0 to 255, where the |
| switched off LED with brightness level 0 indicates a fully opened shutter |
| (tilted to a horizontal position) and 255 indicates a fully closed shutter |
| (tilted to a vertical position). |
| |
| **Button 1** can be used for the following purposes: |
| |
| - _Pressed for 6 s_ — Initiates the factory reset of the device. |
| Releasing the button within the 6-second window cancels the factory reset |
| procedure. **LED 1** and **LED 4** blink in unison when the factory reset |
| procedure is initiated. |
| |
| - _Pressed for less than 3 s_ — Initiates the OTA software update |
| process. This feature is disabled by default, but can be enabled by |
| following the |
| [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) |
| instruction. |
| |
| **Button 2** — Pressing the button once moves the shutter towards the open |
| position by one step. Depending on the current movement mode, the button |
| decreases the brightness of **LED2** for the lift mode and **LED3** for the tilt |
| mode. |
| |
| **Button 3** — Pressing the button once moves the shutter towards the |
| closed position by one step. Depending on the current movement mode, the button |
| increases the brightness of **LED2** for the lift mode and **LED3** for the tilt |
| mode. |
| |
| **Button 2** and **Button 3** — Pressing both buttons at the same time |
| toggles the shutter movement mode between lift and tilt. After each device |
| reset, the mode is set to lift by default. |
| |
| > **Note**: |
| > |
| > Completely opening and closing the shutter requires 20 button presses (steps). |
| > Each step takes approximately 200 ms to simulate the real shutter movement. |
| > The shutter position and LED brightness values are stored in non-volatile |
| > memory and are restored after every device reset. After the firmware update or |
| > factory reset both LEDs are switched off by default, which corresponds to the |
| > shutter being fully open, both lift-wise and tilt-wise. |
| |
| **Button 4** — Pressing the button once starts the NFC tag emulation and |
| enables Bluetooth LE advertising for the predefined period of time (15 minutes |
| by default). |
| |
| **SEGGER J-Link USB port** can be used to get logs from the device or |
| communicate with it using the |
| [command line interface](../../../docs/guides/nrfconnect_examples_cli.md). |
| |
| **NFC port with antenna attached** can be used to start the |
| [rendezvous](#bluetooth-le-rendezvous) by providing the commissioning |
| information from the Matter device in a data payload that can be shared using |
| NFC. |
| |
| <hr> |
| |
| ## Setting up the environment |
| |
| Before building the example, check out the Matter repository and sync submodules |
| using the following command: |
| |
| $ git submodule update --init |
| |
| The example requires a specific revision of the nRF Connect SDK. You can either |
| install it along with the related tools directly on your system or use a Docker |
| image that has the tools pre-installed. |
| |
| If you are a macOS user, you won't be able to use the Docker container to flash |
| the application onto a Nordic development kit due to |
| [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). |
| Use the [native shell](#using-native-shell-for-setup) for building instead. |
| |
| ### Using Docker container for setup |
| |
| To use the Docker container for setup, complete the following steps: |
| |
| 1. If you do not have the nRF Connect SDK installed yet, create a directory for |
| it by running the following command: |
| |
| $ mkdir ~/nrfconnect |
| |
| 2. Download the latest version of the nRF Connect SDK Docker image by running |
| the following command: |
| |
| $ docker pull nordicsemi/nrfconnect-chip |
| |
| 3. Start Docker with the downloaded image by running the following command, |
| customized to your needs as described below: |
| |
| $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \ |
| -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip |
| |
| In this command: |
| |
| - _~/nrfconnect_ can be replaced with an absolute path to the nRF Connect |
| SDK source directory. |
| - _~/connectedhomeip_ must be replaced with an absolute path to the CHIP |
| source directory. |
| - _-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:_ rmw"\* |
| parameters can be omitted if you are not planning to flash the example |
| onto hardware. These parameters give the container access to USB devices |
| connected to your computer such as the nRF52840 DK. |
| - _--rm_ can be omitted if you do not want the container to be |
| auto-removed when you exit the container shell session. |
| - _-e RUNAS=\$(id -u)_ is needed to start the container session as the |
| current user instead of root. |
| |
| 4. Update the nRF Connect SDK to the most recent supported revision, by running |
| the following command: |
| |
| $ cd /var/chip |
| $ python3 scripts/setup/nrfconnect/update_ncs.py --update |
| |
| Now you can proceed with the [Building](#building) instruction. |
| |
| ### Using native shell for setup |
| |
| To use the native shell for setup, complete the following steps: |
| |
| 1. Download and install the following additional software: |
| |
| - [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools) |
| - [GN meta-build system](https://gn.googlesource.com/gn/) |
| |
| 2. If you do not have the nRF Connect SDK installed, follow the |
| [guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_assistant.html#) |
| in the nRF Connect SDK documentation to install the latest stable nRF |
| Connect SDK version. Since command-line tools will be used for building the |
| example, installing SEGGER Embedded Studio is not required. |
| |
| If you have the SDK already installed, continue to the next step and update |
| the nRF Connect SDK after initializing environment variables. |
| |
| 3. Initialize environment variables referred to by the CHIP and the nRF Connect |
| SDK build scripts. Replace _nrfconnect-dir_ with the path to your nRF |
| Connect SDK installation directory, and _toolchain-dir_ with the path to GNU |
| Arm Embedded Toolchain. |
| |
| $ source nrfconnect-dir/zephyr/zephyr-env.sh |
| $ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb |
| $ export GNUARMEMB_TOOLCHAIN_PATH=toolchain-dir |
| |
| 4. Update the nRF Connect SDK to the most recent supported revision by running |
| the following command (replace _matter-dir_ with the path to Matter |
| repository directory): |
| |
| $ cd matter-dir |
| $ python3 scripts/setup/nrfconnect/update_ncs.py --update |
| |
| Now you can proceed with the [Building](#building) instruction. |
| |
| <hr> |
| |
| ## Building |
| |
| Complete the following steps, regardless of the method used for setting up the |
| environment: |
| |
| 1. Navigate to the example's directory: |
| |
| $ cd examples/window-app/nrfconnect |
| |
| 2. Run the following command to build the example, with _build-target_ replaced |
| with the build target name of the Nordic Semiconductor's kit you own, for |
| example `nrf52840dk_nrf52840`: |
| |
| $ west build -b build-target |
| |
| You only need to specify the build target on the first build. See |
| [Requirements](#requirements) for the build target names of compatible kits. |
| |
| The output `zephyr.hex` file will be available in the `build/zephyr/` directory. |
| |
| ### Removing build artifacts |
| |
| If you're planning to build the example for a different kit or make changes to |
| the configuration, remove all build artifacts before building. To do so, use the |
| following command: |
| |
| $ rm -r build |
| |
| ### Building with release configuration |
| |
| To build the example with release configuration that disables the diagnostic |
| features like logs and command-line interface, run the following command: |
| |
| $ west build -b build-target -- -DCONF_FILE=prj_release.conf |
| |
| Remember to replace _build-target_ with the build target name of the Nordic |
| Semiconductor's kit you own. |
| |
| ### Building with Device Firmware Upgrade support |
| |
| Support for DFU using Matter OTA is enabled by default. |
| |
| To enable DFU over Bluetooth LE, run the following command with _build-target_ |
| replaced with the build target name of the Nordic Semiconductor kit you are |
| using (for example `nrf52840dk_nrf52840`): |
| |
| ``` |
| $ west build -b build-target -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y |
| ``` |
| |
| To completely disable support for DFU, run the following command with |
| _build-target_ replaced with the build target name of the Nordic Semiconductor |
| kit you are using (for example `nrf52840dk_nrf52840`): |
| |
| $ west build -b build-target -- -DCONF_FILE=prj_no_dfu.conf |
| |
| > **Note**: |
| > |
| > There are two types of Device Firmware Upgrade modes: single-image DFU and |
| > multi-image DFU. Single-image mode supports upgrading only one firmware image, |
| > the application image, and should be used for single-core nRF52840 DK devices. |
| > Multi-image mode allows to upgrade more firmware images and is suitable for |
| > upgrading the application core and network core firmware in two-core nRF5340 |
| > DK devices. |
| |
| #### Changing bootloader configuration |
| |
| To change the default MCUboot configuration, edit the `prj.conf` file located in |
| the `child_image/mcuboot` directory. |
| |
| Make sure to keep the configuration consistent with changes made to the |
| application configuration. This is necessary for the configuration to work, as |
| the bootloader image is a separate application from the user application and it |
| has its own configuration file. |
| |
| #### Changing flash memory settings |
| |
| In the default configuration, the MCUboot uses the |
| [Partition Manager](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#partition-manager) |
| to configure flash partitions used for the bootloader application image slot |
| purposes. You can change these settings by defining |
| [static partitions](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/scripts/partition_manager/partition_manager.html#ug-pm-static). |
| This example uses this option to define using an external flash. |
| |
| To modify the flash settings of your board (that is, your _build-target_, for |
| example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the |
| `configuration/build-target/` directory. |
| |
| <hr> |
| |
| ## Configuring the example |
| |
| The Zephyr ecosystem is based on Kconfig files and the settings can be modified |
| using the menuconfig utility. |
| |
| To open the menuconfig utility, run the following command from the example |
| directory: |
| |
| $ west build -b build-target -t menuconfig |
| |
| Remember to replace _build-target_ with the build target name of the Nordic |
| Semiconductor's kit you own. |
| |
| Changes done with menuconfig will be lost if the `build` directory is deleted. |
| To make them persistent, save the configuration options in the `prj.conf` file. |
| |
| ### Example build types |
| |
| The example uses different configuration files depending on the supported |
| features. Configuration files are provided for different build types and they |
| are located in the application root 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. |
| |
| Before you start testing the application, you can select one of the build types |
| supported by the sample. This sample supports the following build types, |
| depending on the selected board: |
| |
| - debug — Debug version of the application - can be used to enable |
| additional features for verifying the application behavior, such as logs or |
| command-line shell. |
| - release — Release version of the application - can be used to enable |
| only the necessary application functionalities to optimize its performance. |
| - no_dfu — Debug version of the application without Device Firmware |
| Upgrade feature support - can be used only for the nRF52840 DK and nRF5340 |
| DK, as those platforms have DFU enabled by default. |
| |
| For more information, see the |
| [Configuring nRF Connect SDK examples](../../../docs/guides/nrfconnect_examples_configuration.md) |
| page. |
| |
| <hr> |
| |
| ## Flashing and debugging |
| |
| To flash the application to the device, use the west tool and run the following |
| command from the example directory: |
| |
| $ west flash --erase |
| |
| If you have multiple development kits connected, west will prompt you to pick |
| the correct one. |
| |
| To debug the application on target, run the following command from the example |
| directory: |
| |
| $ west debug |
| |
| <hr> |
| |
| ## Testing the example |
| |
| Check the [CLI tutorial](../../../docs/guides/nrfconnect_examples_cli.md) to |
| learn how to use command-line interface of the application. |
| |
| ### Testing using Linux CHIPTool |
| |
| Read the [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md) to see |
| how to use [CHIP Tool for Linux or mac OS](../../chip-tool/README.md) to |
| commission and control the application within a Matter-enabled Thread network. |
| |
| ### Testing using Android CHIPTool |
| |
| Read the |
| [Android commissioning guide](../../../docs/guides/nrfconnect_android_commissioning.md) |
| to see how to use [CHIPTool](../../../examples/android/CHIPTool/README.md) for |
| Android smartphones to commission and control the application within a |
| Matter-enabled Thread network. |
| |
| ### Testing Device Firmware Upgrade |
| |
| Read the |
| [DFU tutorial](../../../docs/guides/nrfconnect_examples_software_update.md) to |
| see how to upgrade your device firmware. |
