docs/guides/nrfconnect_android_commissioning.md

   1 # Commissioning nRF Connect Accessory using Android CHIPTool
   2
   3 This article describes how to use
   4 [CHIPTool](../../src/android/CHIPTool/README.md) for Android smartphones to
   5 commission a Nordic Semiconductor nRF52840 DK running
   6 [nRF Connect Lock Example Application](../../examples/lock-app/nrfconnect/README.md)
   7 onto a CHIP-enabled Thread network. The instructions are also valid for
   8 [nRF Connect Lighting Example Application](../../examples/lighting-app/nrfconnect/README.md).
   9
  10 <hr>
  11
  12 -   [Overview](#overview)
  13 -   [Requirements](#requirements)
  14 -   [Building and programming OpenThread RCP firmware](#building-rcp-firmware)
  15 -   [Configuring PC as Thread Border Router](#configuring-pc)
  16     -   [Forming Thread network](#forming-thread-network)
  17     -   [Configuring Wi-Fi hotspot](#configuring-hotspot)
  18 -   [Building and programming nRF Connect Lock Example Application](#building-example)
  19 -   [Building and installing Android CHIPTool](#building-chiptool)
  20 -   [Preparing accessory device](#preparing-accessory)
  21 -   [Commissioning accessory device](#commissioning-accessory)
  22 -   [Sending CHIP commands](#sending-chip-commands)
  23
  24 <hr>
  25
  26 <a name="overview"></a>
  27
  28 ## Overview
  29
  30 The commissioning process is composed of the following main stages:
  31
  32 -   CHIPTool discovers a CHIP accessory device over Bluetooth LE.
  33 -   CHIPTool establishes a secure channel to the device over Bluetooth LE, and
  34     sends CHIP operational credentials and Thread provisioning data.
  35 -   The accessory device joins a CHIP-enabled Thread network.
  36
  37 Bluetooth LE is only used during the commissioning phase. Afterwards, only the
  38 IP connectivity between the smartphone and the accessory device is needed to
  39 send operational messages. Since a typical smartphone does not have a Thread
  40 radio built-in, extra effort is needed to prepare a fully-fledged testing
  41 environment. This page describes how to build a Thread Border Router using a PC
  42 with a spare Wi-Fi card and an
  43 [OpenThread Radio Co-Processor](https://openthread.io/platforms/co-processor)
  44 device.
  45
  46 The following diagram shows the connectivity between network components required
  47 to allow communication between devices running the CHIPTool and Lock
  48 applications:
  49
  50 ```
  51                +--------------------+
  52                |    Smartphone      |
  53      +---------|  Android CHIPTool  |---------+
  54      |         +--------------------+         |
  55      |                                        | Wi-Fi
  56      |                                        |
  57      |                                +---------------+  Ethernet  +----------+
  58      |                                |      PC       |------------| Internet |
  59      |                                +---------------+            +----------+
  60      |                                        |
  61      | Bluetooth LE                           | USB
  62      |                                        |
  63      |                                +---------------+
  64      |                                |  nRF52840 DK  |
  65      |                                | OpenThread RCP|
  66      |                                +---------------+
  67      |                                        |
  68      |         +--------------------+         | Thread
  69      |         |    nRF52840 DK     |         |
  70      +---------|  Lock Application  |---------+
  71                +--------------------+
  72 ```
  73
  74 <hr>
  75
  76 <a name="requirements"></a>
  77
  78 ## Requirements
  79
  80 You need the following hardware and software to build a Thread Border Router:
  81
  82 -   Two nRF52840 DK (PCA10056)
  83
  84     -   One nRF52840 DK is needed to run
  85         [OpenThread Radio Co-Processor](https://openthread.io/platforms/co-processor)
  86         firmware and can be replaced with another compatible device like
  87         nRF52840 Dongle.
  88
  89 -   Smartphone compatible with Android 8.0 or later
  90 -   PC with the following characteristics:
  91
  92     -   Software: Ubuntu 20.04 and Docker installed
  93     -   Hardware: A spare Wi-Fi card
  94
  95 While this page references Ubuntu 20.04, all the procedures can be completed
  96 using other popular operating systems.
  97
  98 <hr>
  99
 100 <a name="building-rcp-firmware"></a>
 101
 102 ## Building and programming OpenThread RCP firmware
 103
 104 OpenThread RCP firmware is required to allow the PC to communicate with Thread
 105 devices. Run the commands mentioned in the following steps to build and program
 106 the RCP firmware onto an nRF52840 DK:
 107
 108 1.  Download and install the
 109     [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools).
 110 2.  Clone the OpenThread repository into the current directory:
 111
 112         $ git clone https://github.com/openthread/openthread.git
 113
 114 3.  Enter the _openthread_ directory:
 115
 116         $ cd openthread
 117
 118 4.  Install OpenThread dependencies:
 119
 120         $ ./script/bootstrap
 121
 122 5.  Set up the build environment:
 123
 124         $ ./bootstrap
 125
 126 6.  Build OpenThread for the nRF52840 DK:
 127
 128          $ make -f examples/Makefile-nrf52840
 129
 130     This creates an RCP image in the `bin/ot-rcp` directory.
 131
 132 7.  Convert the RCP image to HEX format:
 133
 134         $ arm-none-eabi-objcopy -O ihex output/nrf52840/bin/ot-rcp output/nrf52840/bin/ot-rcp.hex
 135
 136 8.  Program the RCP firmware:
 137
 138         $ nrfjprog --chiperase --program output/nrf52840/bin/ot-rcp.hex --reset
 139
 140 9.  Disable the Mass Storage feature on the device:
 141
 142          $ JLinkExe
 143          J-Link>MSDDisable
 144          Probe configured successfully.
 145          J-Link>exit
 146
 147     This is required, so that the feature
 148     [does not interfere](https://github.com/openthread/openthread/blob/master/examples/platforms/nrf528xx/nrf52840/README.md#mass-storage-device-known-issue)
 149     with core RCP functionalities. The setting remains valid even if you program
 150     another firmware onto the device.
 151
 152 10. Power-cycle the device to apply the changes.
 153
 154 <hr>
 155
 156 <a name="configuring-pc"></a>
 157
 158 ## Configuring PC as Thread Border Router
 159
 160 To make your PC work as a Thread Border Router, complete the following tasks:
 161
 162 1. Form a Thread network using the OpenThread RCP device and configure IPv6
 163    packet routing to the network.
 164 2. Configure a Wi-Fi hotspot using a spare Wi-Fi card on your PC.
 165
 166 <a name="forming-thread-network"></a>
 167
 168 ### Forming Thread network
 169
 170 To form a Thread network, complete the following steps:
 171
 172 1.  Create an IPv6 network for the OpenThread Border Router (OTBR) container in
 173     Docker:
 174
 175         $ docker network create --ipv6 --subnet fd11:db8:1::/64 -o com.docker.network.bridge.name=otbr0 otbr
 176
 177 2.  Start the OTBR container using the following command. In the last line,
 178     provide the device node name of the nRF52840 kit that is running the RCP
 179     firmware before `:/dev/radio` (in this case, the name is _/dev/ttyACM0_):
 180
 181         $ docker run -it --rm --privileged --network otbr -p 8080:80 \
 182                 --sysctl "net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1" \
 183                 --volume /dev/ttyACM0:/dev/radio openthread/otbr --radio-url spinel+hdlc+uart:///dev/radio
 184
 185 3.  Open the `http://localhost:8080/` address in a web browser.
 186 4.  Click **Form** in the menu to the left. The network forming creator window
 187     appears.
 188 5.  Make sure that the On-Mesh Prefix is set to `fd11:22::`. This value is used
 189     later to configure the IPv6 packet routing.
 190 6.  Click the **Form** button at the bottom of the window to form a new Thread
 191     network using the default settings.
 192 7.  Run the following command to learn which IPv6 address was assigned to the
 193     OTBR container in Docker.
 194
 195          $ docker network inspect otbr | grep IPv6Address
 196
 197     After checking the output, the address will most likely be `fd11:db8:1::2`.
 198
 199 8.  To ensure that packets targeting Thread network nodes are routed through the
 200     OTBR container in Docker, run the following command, with _fd11:db8:1::2_
 201     replaced with the actual address obtained in the previous step:
 202
 203         $ sudo ip -6 route add fd11:22::/64 dev otbr0 via fd11:db8:1::2
 204
 205 <a name="configuring-hotspot"></a>
 206
 207 ### Configuring Wi-Fi hotspot
 208
 209 To configure a Wi-Fi hotspot using a spare Wi-Fi card on your PC, complete the
 210 following steps:
 211
 212 1.  Open the Ubuntu settings widget by running the following command:
 213
 214         $ gnome-control-center
 215
 216 2.  Go to the Wi-Fi settings.
 217 3.  Click the three-dot icon at the title bar and select the **Turn On Wi-Fi
 218     Hotspot...** option.
 219 4.  Enter your network name and password and click **Turn On**.
 220 5.  Run the following command to assign a well-known IPv6 address to the hotspot
 221     interface:
 222
 223         $ nmcli connection modify Hotspot ipv6.addresses fd11:db8:2::1/64
 224
 225 6.  Run the following command to install Routing Advertisement Daemon (radvd),
 226     which enables the IPv6 auto-configuration of devices that connect to the
 227     hotspot:
 228
 229         $ sudo apt install radvd
 230
 231 7.  Learn the hotspot interface name by running the following command:
 232
 233         $ nmcli connection show Hotspot | grep interface-name
 234
 235 8.  Add the following lines into `/etc/radvd.conf`, with _wlo1_ replaced with
 236     the hotspot interface name obtained in the previous step:
 237
 238         interface wlo1
 239         {
 240           MinRtrAdvInterval 3;
 241           MaxRtrAdvInterval 4;
 242           AdvSendAdvert on;
 243           AdvManagedFlag on;
 244           prefix fd11:db8:2::/64
 245           {
 246              AdvValidLifetime 14300;
 247              AdvPreferredLifetime 14200;
 248           };
 249         };
 250
 251 9.  Start the radvd service by running the following command:
 252
 253         $ systemctl start radvd
 254
 255 To automatically start the radvd service on every reboot, run the following
 256 command:
 257
 258     $ systemctl enable radvd
 259
 260 > If you use Ubuntu 18.04, a DHCP server is not configured automatically when
 261 > creating a Wi-Fi hotspot. As a result, devices that connect to the hotspot
 262 > will not be assigned an IPv4 address and may not work properly. To address the
 263 > problem, install and configure a DHCP server on the hotspot interface. For
 264 > example, you can use
 265 > [isc-dhcp-server](https://help.ubuntu.com/community/isc-dhcp-server).
 266
 267 <hr>
 268
 269 <a name="building-example"></a>
 270
 271 ## Building and programming nRF Connect Lock Example Application
 272
 273 See
 274 [nRF Connect Lock Example Application README](../../examples/lock-app/nrfconnect/README.md)
 275 to learn how to build and program the example onto an nRF52840 DK.
 276
 277 <hr>
 278
 279 <a name="building-chiptool"></a>
 280
 281 ## Building and installing Android CHIPTool
 282
 283 To build the CHIPTool application for your smartphone, read
 284 [Android CHIPTool README](../../src/android/CHIPTool/README.md).
 285
 286 After building, install the application by completing the following steps:
 287
 288 1.  Install the Android Debug Bridge (adb) package by running the following
 289     command:
 290
 291         $ sudo apt install android-tools-adb
 292
 293 2.  Enable **USB debugging** on the smartphone. See the
 294     [Configure on-device developer options](https://developer.android.com/studio/debug/dev-options)
 295     guide on the Android Studio hub for detailed information.
 296 3.  If the **Install via USB** option is supported for your Android version,
 297     turn it on.
 298 4.  Plug the smartphone into an USB port on your PC.
 299 5.  Run the following command to install the application, with _chip-dir_
 300     replaced with the path to the CHIP source directory:
 301
 302         $ adb install -r chip-dir/src/android/CHIPTool/app/build/outputs/apk/debug/app-debug.apk
 303
 304 6.  Navigate to settings on your smartphone and grant **Camera** and
 305     **Location** permissions to CHIPTool.
 306
 307 CHIPTool is now ready to be used for commissioning.
 308
 309 <hr>
 310
 311 <a name="preparing-accessory"></a>
 312
 313 ## Preparing accessory device
 314
 315 To prepare the accessory device for commissioning, complete the following steps:
 316
 317 1.  Use a terminal emulator to connect to the UART console of the accessory
 318     device. For details, see the
 319     [Using CLI in nRF Connect SDK examples](nrfconnect_examples_cli.md) guide.
 320     This will grant you access to the application logs.
 321 2.  Hold **Button 1** on the accessory device for more than 6 s to trigger the
 322     factory reset of the device.
 323 3.  Find a message similar to the following one in the application logs:
 324
 325         I: 666[SVR] Copy/paste the below URL in a browser to see the QR Code:
 326                 https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3AI34DV%2A-00%200C9SS0
 327
 328 4.  Open the URL in a web browser to have the commissioning QR code generated.
 329 5.  Push **Button 4** on the device to start Bluetooth LE advertising.
 330
 331 <hr>
 332
 333 <a name="commissioning-accessory"></a>
 334
 335 ## Commissioning accessory device
 336
 337 To commission the accessory device onto the Thread network created in the
 338 [Forming Thread network](#Forming-a-Thread-network) section, complete the
 339 following steps:
 340
 341 1. Enable **Bluetooth** and **Location** services on your smartphone.
 342 2. Connect the smartphone to the Wi-Fi Hotspot created in the
 343    [Configuring Wi-Fi hotspot](#Configuring-a-Wi-Fi-hotspot) section.
 344 3. Open the CHIPTool application on your smartphone.
 345 4. Tap the **PROVISION CHIP DEVICE WITH THREAD** button and scan the
 346    commissioning QR code. Several notifications will appear, informing you of
 347    commissioning progress with scanning, connection, and pairing. At the end of
 348    this process, the Thread network settings screen appears.
 349 5. In the Thread network settings screen, use the default settings and tap the
 350    **SAVE NETWORK** button to send a Thread provisioning message to the
 351    accessory device.
 352
 353 You will see the "Network provisioning completed" message when the accessory
 354 device successfully joins the Thread network.
 355
 356 <hr>
 357
 358 <a name="sending-commands"></a>
 359
 360 ## Sending CHIP commands
 361
 362 Once the device is commissioned, the following screen appears:
 363
 364 ![CHIPTool device control screen](../../docs/images/CHIPTool_device_commissioned.jpg)
 365
 366 This means that the provisioning is completed successfully and you are connected
 367 to the device. Check the connection with the following steps:
 368
 369 1. Verify that the text box on the screen is not empty and contains the IPv6
 370    address of the accessory device.
 371 2. Tap the following buttons to change the lock state:
 372
 373     - **ON** and **OFF** buttons lock and unlock the door, respectively.
 374     - **TOGGLE** changes the lock state to the opposite.
 375
 376 The **LED 2** on the device turns on or off based on the changes of the lock
 377 state.