examples/lock-app/nrfconnect/README.md

   1 # CHIP nRF Connect Lock Example Application
   2
   3 The nRF Connect Lock Example demonstrates how to remotely control a door lock
   4 device with one basic bolt. It uses buttons to test changing the lock and device
   5 states and LEDs to show the state of these changes. You can use this example as
   6 a reference for creating your own application.
   7
   8 <p align="center">
   9   <img src="../../platform/nrfconnect/doc/images/Logo_RGB_H-small.png" alt="Nordic Semiconductor logo"/>
  10   <img src="../../platform/nrfconnect/doc/images/nRF52840-DK-small.png" alt="nRF52840 DK">
  11 </p>
  12
  13 The example is based on [CHIP](https://github.com/project-chip/connectedhomeip)
  14 and Nordic Semiconductor's nRF Connect SDK, and supports remote access and
  15 control of a simulated door lock over a low-power, 802.15.4 Thread network.
  16
  17 The example behaves as a CHIP accessory, that is a device that can be paired
  18 into an existing CHIP network and can be controlled by this network.
  19
  20 <hr>
  21
  22 -   [Overview](#overview)
  23     -   [Bluetooth LE advertising](#bluetooth-le-advertising)
  24     -   [Bluetooth LE rendezvous](#bluetooth-le-rendezvous)
  25 -   [Requirements](#requirements)
  26     -   [Supported devices](#supported_devices)
  27 -   [Device UI](#device-ui)
  28 -   [Setting up the environment](#setting-up-the-environment)
  29     -   [Using Docker container for setup](#using-docker-container-for-setup)
  30     -   [Using native shell for setup](#using-native-shell-for-setup)
  31 -   [Building](#building)
  32 -   [Configuring the example](#configuring-the-example)
  33 -   [Flashing and debugging](#flashing-and-debugging)
  34 -   [Testing the example](#testing-the-example)
  35     -   [Testing using CHIPTool](#testing-using-chiptool)
  36
  37 <hr>
  38
  39 <a name="overview"></a>
  40
  41 ## Overview
  42
  43 This example is running on the nRF Connect platform, which is based on Nordic
  44 Semiconductor's
  45 [nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html)
  46 and [Zephyr RTOS](https://zephyrproject.org/). Visit CHIP's
  47 [nRF Connect platform overview](../../../docs/guides/nrfconnect_platform_overview.md)
  48 to read more about the platform structure and dependencies.
  49
  50 The CHIP device that runs the lock application is controlled by the CHIP
  51 controller device over the Thread protocol. By default, the CHIP device has
  52 Thread disabled, and it should be paired with CHIP controller and get
  53 configuration from it. Some actions required before establishing full
  54 communication are described below.
  55
  56 The example also comes with a test mode, which allows to start Thread with the
  57 default settings by pressing button manually. However, this mode does not
  58 guarantee that the device will be able to communicate with the CHIP controller
  59 and other devices.
  60
  61 ### Bluetooth LE advertising
  62
  63 In this example, to commission the device onto a CHIP network, it must be
  64 discoverable over Bluetooth LE. For security reasons, you must start Bluetooth
  65 LE advertising manually after powering up the device by pressing **Button 4**.
  66
  67 ### Bluetooth LE rendezvous
  68
  69 In this example, the commissioning procedure (called rendezvous) is done over
  70 Bluetooth LE between a CHIP device and the CHIP controller, where the controller
  71 has the commissioner role.
  72
  73 To start the rendezvous, the controller must get the commissioning information
  74 from the CHIP device. The data payload is encoded within a QR code, printed to
  75 the UART console, and shared using an NFC tag. For security reasons, you must
  76 start NFC tag emulation manually after powering up the device by pressing
  77 **Button 4**.
  78
  79 #### Thread provisioning
  80
  81 Last part of the rendezvous procedure, the provisioning operation involves
  82 sending the Thread network credentials from the CHIP controller to the CHIP
  83 device. As a result, device is able to join the Thread network and communicate
  84 with other Thread devices in the network.
  85
  86 <hr>
  87
  88 <a name="requirements"></a>
  89
  90 ## Requirements
  91
  92 The application requires the nRF Connect SDK v1.5.0 to work correctly.
  93
  94 <a name="supported_devices"></a>
  95
  96 ### Supported devices
  97
  98 The example supports building and running on the following devices:
  99
 100 | Hardware platform                                                                         | Build target               | Platform image                                                                                                                                      |
 101 | ----------------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
 102 | [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_top-view-small.jpg" alt="nRF52840 DK"/></details> |
 103 | [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_top-view-small.jpg" alt="nRF5340 DK"/></details>    |
 104
 105 <hr>
 106
 107 <a name="device-ui"></a>
 108
 109 ## Device UI
 110
 111 This section lists the User Interface elements that you can use to control and
 112 monitor the state of the device. These correspond to PCB components on the
 113 platform image.
 114
 115 **LED 1** shows the overall state of the device and its connectivity. The
 116 following states are possible:
 117
 118 -   _Short Flash On (50 ms on/950 ms off)_ &mdash; The device is in the
 119     unprovisioned (unpaired) state and is waiting for a commissioning
 120     application to connect.
 121
 122 -   _Rapid Even Flashing (100 ms on/100 ms off)_ &mdash; The device is in the
 123     unprovisioned state and a commissioning application is connected through
 124     Bluetooth LE.
 125
 126 -   _Short Flash Off (950ms on/50ms off)_ &mdash; The device is fully
 127     provisioned, but does not yet have full Thread network or service
 128     connectivity.
 129
 130 -   _Solid On_ &mdash; The device is fully provisioned and has full Thread
 131     network and service connectivity.
 132
 133 **LED 2** simulates the lock bolt and shows the state of the lock. The following
 134 states are possible:
 135
 136 -   _Solid On_ &mdash; The bolt is extended and the door is locked.
 137
 138 -   _Off_ &mdash; The bolt is retracted and the door is unlocked.
 139
 140 -   _Rapid Even Flashing (100 ms on/100 ms off during 2 s)_ &mdash; The
 141     simulated bolt is in motion from one position to another.
 142
 143 **Button 1** can be used for the following purposes:
 144
 145 -   _Pressed for 6 s_ &mdash; Initiates the factory reset of the device.
 146     Releasing the button within the 6-second window cancels the factory reset
 147     procedure. **LEDs 1-4** blink in unison when the factory reset procedure is
 148     initiated.
 149
 150 -   _Pressed for less than 3 s_ &mdash; Initiates the OTA software update
 151     process. This feature is not currently supported.
 152
 153 **Button 2** &mdash; Pressing the button once changes the lock state to the
 154 opposite one.
 155
 156 **Button 3** &mdash; Pressing the button once starts the Thread networking in
 157 the test mode using the default configuration.
 158
 159 **Button 4** &mdash; Pressing the button once starts the NFC tag emulation and
 160 enables Bluetooth LE advertising for the predefined period of time.
 161
 162 **SEGGER J-Link USB port** can be used to get logs from the device or
 163 communicate with it using the
 164 [command line interface](../../../docs/guides/nrfconnect_examples_cli.md).
 165
 166 **NFC port with antenna attached** can be used to start the
 167 [rendezvous](#bluetooth-le-rendezvous) by providing the commissioning
 168 information from the CHIP device in a data payload that can be shared using NFC.
 169
 170 <hr>
 171
 172 ## Setting up the environment
 173
 174 Before building the example, check out the CHIP repository and sync submodules
 175 using the following command:
 176
 177         $ git submodule update --init
 178
 179 The example requires the nRF Connect SDK v1.5.0. You can either install it along
 180 with the related tools directly on your system or use a Docker image that has
 181 the tools pre-installed.
 182
 183 If you are a macOS user, you won't be able to use the Docker container to flash
 184 the application onto a Nordic development kit due to
 185 [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container).
 186 Use the [native shell](#using-native-shell) for building instead.
 187
 188 ### Using Docker container for setup
 189
 190 To use the Docker container for setup, complete the following steps:
 191
 192 1.  If you do not have the nRF Connect SDK installed yet, create a directory for
 193     it by running the following command:
 194
 195         $ mkdir ~/nrfconnect
 196
 197 2.  Download the latest version of the nRF Connect SDK Docker image by running
 198     the following command:
 199
 200         $ docker pull nordicsemi/nrfconnect-chip
 201
 202 3.  Start Docker with the downloaded image by running the following command,
 203     customized to your needs as described below:
 204
 205          $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \
 206              -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip
 207
 208     In this command:
 209
 210     -   _~/nrfconnect_ can be replaced with an absolute path to the nRF Connect
 211         SDK source directory.
 212     -   _~/connectedhomeip_ must be replaced with an absolute path to the CHIP
 213         source directory.
 214     -   _-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:_ rmw"\*
 215         parameters can be omitted if you are not planning to flash the example
 216         onto hardware. These parameters give the container access to USB devices
 217         connected to your computer such as the nRF52840 DK.
 218     -   _--rm_ can be omitted if you do not want the container to be
 219         auto-removed when you exit the container shell session.
 220     -   _-e RUNAS=\$(id -u)_ is needed to start the container session as the
 221         current user instead of root.
 222
 223 4.  Check out or update the nRF Connect SDK to the recommended `v1.5.0` version
 224     by running the following command in the Docker container:
 225
 226          $ setup --ncs v1.5.0
 227          /var/ncs repository is empty. Do you wish to check out nRF Connect SDK sources [v1.5.0]? [Y/N] y
 228          ...
 229          /var/chip repository is initialized, skipping...
 230
 231 Now you can proceed with the [Building](#building) instruction.
 232
 233 ### Using native shell for setup
 234
 235 To use the native shell for setup, complete the following steps:
 236
 237 1.  Download and install the following additional software:
 238
 239     -   [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools)
 240     -   [GN meta-build system](https://gn.googlesource.com/gn/)
 241
 242 2.  Depending on whether you have the nRF Connect SDK installed:
 243
 244     -   Follow the
 245         [guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_assistant.html#)
 246         in the nRF Connect SDK documentation to install the nRF Connect SDK
 247         v1.5.0. Since command-line tools will be used for building the example,
 248         installing SEGGER Embedded Studio is not required.
 249
 250     -   If you have an older version of the SDK installed, use the following
 251         commands to update it to the recommended version. Replace
 252         _nrfconnect-dir_ with the path to your nRF Connect SDK installation
 253         directory.
 254
 255                $ cd nrfconnect-dir/nrf
 256                $ git fetch origin
 257                $ git checkout v1.5.0
 258                $ west update
 259
 260 3.  Initialize environment variables referred to by the CHIP and the nRF Connect
 261     SDK build scripts. Replace _nrfconnect-dir_ with the path to your nRF
 262     Connect SDK installation directory, and _toolchain-dir_ with the path to GNU
 263     Arm Embedded Toolchain.
 264
 265          $ source nrfconnect-dir/zephyr/zephyr-env.sh
 266          $ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
 267          $ export GNUARMEMB_TOOLCHAIN_PATH=toolchain-dir
 268
 269 Now you can proceed with the [Building](#building) instruction.
 270
 271 <hr>
 272
 273 <a name="building"></a>
 274
 275 ## Building
 276
 277 Complete the following steps, regardless of the method used for setting up the
 278 environment:
 279
 280 1.  Navigate to the example's directory:
 281
 282         $ cd examples/lock-app/nrfconnect
 283
 284 2.  Run the following command to build the example, with _build-target_ replaced
 285     with the build target name of the Nordic Semiconductor's kit you own, for
 286     example `nrf52840dk_nrf52840`:
 287
 288          $ west build -b build-target
 289
 290     You only need to specify the build target on the first build. See
 291     [Requirements](#requirements) for the build target names of compatible kits.
 292
 293 The output `zephyr.hex` file will be available in the `build/zephyr/` directory.
 294
 295 ### Removing build artifacts
 296
 297 If you're planning to build the example for a different kit or make changes to
 298 the configuration, remove all build artifacts before building. To do so, use the
 299 following command:
 300
 301     $ rm -r build
 302
 303 ### Building with release configuration
 304
 305 To build the example with release configuration that disables the diagnostic
 306 features like logs and command-line interface, run the following command:
 307
 308     $ west build -b build-target -- -DOVERLAY_CONFIG=third_party/connectedhomeip/config/nrfconnect/app/release.conf
 309
 310 Remember to replace _build-target_ with the build target name of the Nordic
 311 Semiconductor's kit you own.
 312
 313 <hr>
 314
 315 <a name="configuring"></a>
 316
 317 ## Configuring the example
 318
 319 The Zephyr ecosystem is based on Kconfig files and the settings can be modified
 320 using the menuconfig utility.
 321
 322 To open the menuconfig utility, run the following command from the example
 323 directory:
 324
 325     $ west build -b build-target -t menuconfig
 326
 327 Remember to replace _build-target_ with the build target name of the Nordic
 328 Semiconductor's kit you own.
 329
 330 Changes done with menuconfig will be lost if the `build` directory is deleted.
 331 To make them persistent, save the configuration options in the `prj.conf` file.
 332 For more information, see the
 333 [Configuring nRF Connect SDK examples](../../../docs/guides/nrfconnect_examples_configuration.md)
 334 page.
 335
 336 <hr>
 337
 338 <a name="flashing"></a>
 339
 340 ## Flashing and debugging
 341
 342 To flash the application to the device, use the west tool and run the following
 343 command from the example directory:
 344
 345         $ west flash
 346
 347 If you have multiple development kits connected, west will prompt you to pick
 348 the correct one.
 349
 350 To debug the application on target, run the following command from the example
 351 directory:
 352
 353         $ west debug
 354
 355 <hr>
 356
 357 ## Testing the example
 358
 359 Check the [CLI tutorial](../../../docs/guides/nrfconnect_examples_cli.md) to
 360 learn how to use command-line interface of the application.
 361
 362 ### Testing using CHIPTool
 363
 364 Read the
 365 [Android commissioning guide](../../../docs/guides/nrfconnect_android_commissioning.md)
 366 to see how to use [CHIPTool](../../../src/android/CHIPTool/README.md) for
 367 Android smartphones to commission and control the application within a
 368 CHIP-enabled Thread network.