docs/guides/nxp_k32w_android_commissioning.md

   1 # Commissioning NXP K32W using Android CHIPTool
   2
   3 This article describes how to use
   4 [CHIPTool](../../src/android/CHIPTool/README.md) for Android smartphones to
   5 commission an NXP K32W061 DK6 running
   6 [NXP K32W Lock/Light Example Application](../../examples/lock-light-app/k32w/README.md)
   7 onto a CHIP-enabled Thread network.
   8
   9 <hr>
  10
  11 -   [Overview](#overview)
  12 -   [Requirements](#requirements)
  13 -   [Building and programming OpenThread RCP firmware](#building-rcp-firmware)
  14 -   [Configuring PC as Thread Border Router](#configuring-pc)
  15 -   [Building and programming NXP K32W Lock/Light Example Application](#building-example)
  16 -   [Building and installing Android CHIPTool](#building-chiptool)
  17 -   [Forming a Thread network on the Border Router](#form-thread)
  18 -   [Preparing accessory device](#preparing-accessory)
  19 -   [Commissioning accessory device](#commissioning-accessory)
  20 -   [Sending CHIP commands](#sending-chip-commands)
  21
  22 <hr>
  23
  24 <a name="overview"></a>
  25
  26 ## Overview
  27
  28 The commissioning process is composed of the following main stages:
  29
  30 -   K32W061 (CHIP accessory) device is put in BLE advertisment mode by pressing
  31     the USERINTERFACE button;
  32 -   CHIPTool discovers the CHIP accessory over BLE;
  33 -   CHIPTool establishes a secure channel with the accessory using a SPAKE2+
  34     handshake;
  35 -   CHIP tool sends Thread provisioning data over the secure channel;
  36 -   The accessory device joins a CHIP-enabled Thread network using the provided
  37     Thread credentials.
  38
  39 Bluetooth LE is only used during the commissioning phase. Afterwards, only the
  40 IP connectivity between the smartphone and the accessory device is needed to
  41 send operational messages. Since a typical smartphone does not have a Thread
  42 radio built-in, extra effort is needed to prepare a fully-fledged testing
  43 environment. This page describes how to build a Thread Border Router using a PC
  44 with a spare Wi-Fi card and an
  45 [OpenThread Radio Co-Processor](https://openthread.io/platforms/co-processor)
  46 device.
  47
  48 The following diagram shows the connectivity between network components required
  49 to allow communication between devices running the CHIPTool and Lock/Light
  50 applications:
  51
  52 ![nxp_hw_connectivity](../../examples/platform/k32w/doc/images/nxp_hw_connectivity.JPG)
  53
  54 <hr>
  55
  56 <a name="requirements"></a>
  57
  58 ## Requirements
  59
  60 You need the following hardware and software to build a Thread Border Router:
  61
  62 -   2 K32W061 DK6 boards
  63
  64     -   One K32W061 DK6 is needed to run
  65         [OpenThread Radio Co-Processor](https://openthread.io/platforms/co-processor)
  66         firmware and can be replaced with another compatible device like K32W061
  67         Dongle.
  68
  69 -   Smartphone compatible with Android 8.0 or later
  70 -   PC with the following characteristics:
  71
  72     -   Software: Ubuntu 20.04
  73     -   Hardware: A spare Wi-Fi card (WiFi driver needs to support AP mode).
  74
  75 While this page references Ubuntu 20.04, all the procedures can be completed
  76 using other popular operating systems.
  77
  78 <hr>
  79
  80 <a name="building-rcp-firmware"></a>
  81
  82 ## Building and programming OpenThread RCP firmware
  83
  84 OpenThread RCP firmware is required to allow the PC to communicate with Thread
  85 devices. Run the commands mentioned in the following steps to build and program
  86 the RCP firmware onto an K32W061 DK6:
  87
  88 1.  Clone the OpenThread repository into the current directory (we recommand
  89     using commit ced158e65a00dd5394c04548b7b187d3a3f11eef):
  90
  91         $ git clone https://github.com/openthread/openthread.git
  92
  93 2.  Enter the _openthread_ directory:
  94
  95         $ cd openthread
  96
  97 3.  Install OpenThread dependencies:
  98
  99         $ ./script/bootstrap
 100
 101 4.  Set up the build environment:
 102
 103         $ ./bootstrap
 104
 105 5.  Build OpenThread for the K32W061 DK6:
 106
 107          $ make -f examples/Makefile-k32w061
 108
 109     This creates an RCP image in the `bin/ot-rcp` directory.
 110
 111 6.  Program the RCP firmware using the official
 112     [OpenThread Flash Instructions](https://github.com/openthread/openthread/blob/master/examples/platforms/k32w/k32w061/README.md#flash-binaries).
 113
 114 7.  Plug-in the K32W061 DK6 to the PC.
 115
 116 <hr>
 117
 118 <a name="configuring-pc"></a>
 119
 120 ## Configuring PC as a Thread Border Router
 121
 122 To make your PC work as a Thread Border Router, complete the following tasks:
 123
 124 1.  Set up Thread Border Router package by following steps
 125     [3,4,5](https://openthread.io/guides/border-router/build) from the official
 126     documentation. Use NETWORK_MANAGER=0 as the Wi-Fi AP will be set manually at
 127     the next step. Also, we recommend using commit
 128     83babaf236cad8471be28185d8d4351d37564919 for ot-br-posix repository.
 129 2.  Configure the Wi-Fi AP
 130
 131     -   Install the required package:
 132
 133               $ sudo apt-get install hostapd
 134
 135     -   Configure hostapd (create new file and add content):
 136
 137               $ sudo vim /etc/hostapd/hostapd.conf
 138
 139               interface=wlan0
 140               driver=nl80211
 141               ssid=OT-BR
 142               hw_mode=g
 143               channel=7
 144               wmm_enabled=0
 145               macaddr_acl=0
 146               auth_algs=1
 147               ignore_broadcast_ssid=0
 148               wpa=2
 149               wpa_passphrase=12345678
 150               wpa_key_mgmt=WPA-PSK
 151               wpa_pairwise=TKIP
 152               rsn_pairwise=CCMP
 153
 154     -   We need to tell hostapd to use our config file by editing the main
 155         hostapd configuration file. Change the line that starts with
 156         #DAEMON_CONF (remember to remove #):
 157          \$ sudo vim /etc/default/hostapd
 158
 159               DAEMON_CONF="/etc/hostapd/hostapd.conf"
 160
 161     -   Start hostapd:
 162
 163               $ sudo systemctl unmask hostapd
 164               $ sudo systemctl enable hostapd
 165
 166 3.  Configure Dnsmasq
 167
 168     -   Install the required package:
 169
 170               $ sudo apt-get install dnsmasq
 171
 172     -   Make a backup of the default config file:
 173
 174               $ sudo cp /etc/dnsmasq.conf /etc/dnsmasq.conf.org
 175
 176     -   Set the DHCP range:
 177
 178               $ sudo vim /etc/dnsmasq.conf
 179
 180               interface=wlan0
 181               dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h
 182
 183     -   On System startup, dnsmasq will not wait for wlan0 interface to
 184         initialize and will fail. We need to tell systemd to launch it after
 185         networks get ready, so we will modify dnsmasq service file by specifing
 186         the initialization order under the _After=_ and _Wants=_ sections:
 187
 188               $ sudo vim /lib/systemd/system/dnsmasq.service
 189
 190               [Unit]
 191               ...
 192               After=... network-online.target
 193               Wants=... network-online.target
 194
 195     -   Force systemd to avoid using port 53 (used by dnsmasqd service):
 196
 197               $ sudo vim /etc/systemd/resolved.conf
 198
 199               DNSStubListener=no
 200
 201 4.  Configure static IP for the Wi-Fi AP interface
 202
 203     -   Modify the cloud-init file and add content to it (use spaces, not tabs,
 204         USE THE ):
 205
 206             $ sudo vim /etc/netplan/50-cloud-init.yaml
 207
 208             wlan0:
 209                 dhcp4: false
 210                 addresses:
 211                 - 192.168.4.1/24
 212
 213     -   The final configuration file should like like this (pay attention to the
 214         spacing used):
 215
 216               network:
 217                   version: 2
 218                   ethernets:
 219                       eth0:
 220                            dhcp4: true
 221                            optional: true
 222                       wlan0:
 223                            dhcp4: false
 224                            addresses:
 225                            - 192.168.4.1/24
 226
 227 5)  Set up RADVD
 228
 229     -   Install required package:
 230
 231         \$ sudo apt-get install radvd
 232
 233     -   Configure RADVD for distributing the prefix _fd11:33_::/64 to the
 234         devices connected to the AP, while announcing them that is also has a
 235         route to _fd11:22::/64_
 236          \$ sudo vim /etc/radvd.conf
 237
 238               interface wlan0 {
 239                  AdvManagedFlag on;
 240                  AdvSendAdvert on;
 241                  MinRtrAdvInterval 30;
 242                  MaxRtrAdvInterval 60;
 243                  prefix fd11:33::1/64 {
 244                     AdvOnLink on;
 245                     AdvAutonomous on;
 246                     AdvRouterAddr on;
 247                  };
 248                  route fd11:22::/64 {
 249                  };
 250               };
 251
 252
 253     -   Enable radvd service:
 254          $ sudo chmod u=rw,g=r,o=r /etc/radvd.conf
 255             $ sudo systemctl enable
 256         radvd.service
 257
 258 6.  Configure routing:
 259
 260     -   Create a configuration file for setting the routing behavior (forward
 261         between Thread and Wi-Fi AP interfaces):
 262
 263               $ sudo vim configurations.sh
 264
 265               #!/bin/bash
 266               sudo iptables -A FORWARD -i wlan0 -o wpan0 -j ACCEPT
 267               sudo iptables -A FORWARD -i wpan0 -o wlan0 -j ACCEPT
 268
 269
 270     -   Set the executable bit for the above file:
 271
 272               $ sudo chmod +x configurations.sh
 273
 274     -   Configure the above script to be run each time the PC is restarted using
 275         a systemd service configuration (change the path for _ExecStart_):
 276
 277               $ sudo vim /etc/systemd/system/br.service
 278
 279               [Unit]
 280               Description=Job
 281
 282               [Service]
 283               ExecStart=/home/replace_with_real_path/configurations.sh
 284               Type=oneshot
 285               RemainAfterExit=yes
 286
 287               [Install]
 288               WantedBy=multi-user.target
 289
 290
 291     -   Then run:
 292
 293               $ sudo systemctl daemon-reload
 294               $ sudo systemctl enable br.service
 295
 296 7.  As a quick checkpoint, restart the PC and make sure that the mobile phone
 297     can connect to the _OT-BR_ AP (password: 12345678). Also, check that it gets
 298     assigned an IPv4 address in the range _192.168.4.0/24_ and an IPV6 address
 299     with the prefix _fd11:33::/64_. Commands for debugging possible issues with
 300     the services:
 301
 302         $ sudo service hostapd status
 303         $ sudo service dnsmasq status
 304         $ sudo service radvd status
 305         $ sudo service br status
 306
 307 <hr>
 308
 309 <a name="building-example"></a>
 310
 311 ## Building and programming NXP K32W Lock/Light Example Application
 312
 313 See
 314 [NXP K32W Lock Example Application README](../../examples/lock-app/k32w/README.md)
 315 to learn how to build and program the lock example onto an K32W061 DK6.
 316
 317 See
 318 [NXP K32W Light Example Application README](../../examples/lighting-app/k32w/README.md)
 319 to learn how to build and program the light example onto an K32W061 DK6.
 320
 321 <hr>
 322
 323 <a name="building-chiptool"></a>
 324
 325 ## Building and installing Android CHIPTool
 326
 327 To build the CHIPTool application for your smartphone, read
 328 [Android CHIPTool README](../../src/android/CHIPTool/README.md).
 329
 330 After building, install the application by completing the following steps:
 331
 332 1.  Install the Android Debug Bridge (adb) package by running the following
 333     command:
 334
 335         $ sudo apt install android-tools-adb
 336
 337 2.  Enable _USB debugging_ on the smartphone. See the
 338     [Configure on-device developer options](https://developer.android.com/studio/debug/dev-options)
 339     guide on the Android Studio hub for detailed information.
 340 3.  If the _Install via USB_ option is supported for your Android version, turn
 341     it on.
 342 4.  Plug the smartphone into an USB port on your PC.
 343 5.  Run the following command to install the application, with _chip-dir_
 344     replaced with the path to the CHIP source directory:
 345
 346         $ adb install -r chip-dir/src/android/CHIPTool/app/build/outputs/apk/debug/app-debug.apk
 347
 348 6.  Navigate to settings on your smartphone and grant _Camera_ and _Location_
 349     permissions to CHIPTool.
 350
 351 CHIPTool is now ready to be used for commissioning.
 352
 353 <hr>
 354
 355 <a name="form-thread"></a>
 356
 357 ## Forming a Thread network on the Border Router
 358
 359 1.  On the mobile phone connect to the _OT-BR_ Wi-Fi network.
 360
 361 2.  Open a browser and type the IP address 192.168.4.1. The Thread Border Router
 362     Web Management page will open.
 363
 364 3.  Navigate to the _Form_ tab then push the _Form_ button using the default
 365     parameters:
 366     ![nxp_form_nwk](../../examples/platform/k32w/doc/images/form_web.JPG)
 367
 368 4.  The message _Form operation is successful_ should be display after a few
 369     seconds.
 370
 371 5.  In case you ever want to reset these parameters issue this command from the
 372     border router shell:
 373
 374         $ sudo ot-ctl factoryreset
 375
 376 6.  Info: For debugging the Border Router, _ot-ctl_ offers an entry point to
 377     [Thread CLI Commands](https://github.com/openthread/openthread/blob/master/src/cli/README.md).
 378
 379 7.  In case there is any issue with the Web GUI check the logs on the Border
 380     Router side / restart the daemon:
 381
 382         $ sudo service otbr-web status
 383
 384     In case the status is not _leader_ then restart the service:
 385
 386         $ sudo service otbr-web restart
 387
 388 ## Preparing accessory device
 389
 390 To prepare the accessory device for commissioning, complete the following steps:
 391
 392 1.  Make sure that JP4 and JP7 jumpers are in leftmost position and a mini-USB
 393     cable is connected between the LPC connector and PC
 394     ![nxp_connectors](../../examples/platform/k32w/doc/images/k32w-dk6-connectors.jpg)
 395
 396 2.  Use a terminal emulator (e.g.: Putty) to connect to the UART console of the
 397     accessory device. Use a baudrate of 115200.
 398
 399     This will grant you access to the application logs.
 400
 401 3.  Push _Button SW2_ on the accessory device and wait 6s for factory reset of
 402     the device.
 403 4.  Find a message similar to the following one in the application logs:
 404
 405         I: 666[SVR] Copy/paste the below URL in a browser to see the QR Code:
 406                 https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3AI34DV%2A-00%200C9SS0
 407
 408 5.  Open the URL in a web browser to have the commissioning QR code generated.
 409
 410 <hr>
 411
 412 <a name="commissioning-accessory"></a>
 413
 414 ## Commissioning accessory device
 415
 416 To commission the accessory device onto the Thread network created in the
 417 [Forming Thread network](#Forming-a-Thread-network) section, complete the
 418 following steps:
 419
 420 1. Enable _Bluetooth_ and _Location_ services on your smartphone;
 421 2. Connect the smartphone to _OT-BR_ WiFi network;
 422 3. Open the CHIPTool application on your smartphone;
 423 4. Push the USERINTERFACE button on the K32W board. This will start the BLE
 424    advertising process;
 425 5. Tap the _PROVISION CHIP DEVICE WITH THREAD_ button and scan the commissioning
 426    QR code. Several notifications will appear, informing you of commissioning
 427    progress with scanning, connection, and pairing. At the end of this process,
 428    the Thread network settings screen appears.
 429
 430     ![chiptool_main_screen](../../examples/platform/k32w/doc/images/chiptool_main_screen.png)
 431
 432 6. In the Thread network settings screen, use the default settings and tap the
 433    _SAVE NETWORK_ button to send a Thread provisioning message to the accessory
 434    device. You will see the "Network provisioning completed" message when the
 435    accessory device successfully joins the Thread network.
 436
 437     ![chiptool_credentials](../../examples/platform/k32w/doc/images/thread_credentials.png)
 438
 439 <hr>
 440
 441 <a name="sending-commands"></a>
 442
 443 ## Sending CHIP commands
 444
 445 1. Once the device is commissioned, the below screen appears. This means that
 446    the provisioning is completed successfully and you are connected to the
 447    device.
 448
 449     ![on_off_cluster.png](../../examples/platform/k32w/doc/images/on_off_cluster.png)
 450
 451 2. Verify that the text box on the screen is not empty and contains the IPv6
 452    address of the accessory device.
 453 3. Tap the following buttons to change the lock/light state:
 454
 455     - _ON_ and _OFF_ buttons lock/turn on and unlock/turn off the door/light
 456       bulb, respectively.
 457     - _TOGGLE_ changes the lock/light state to the opposite.
 458
 459 The _LED D3_ on the device turns on or off based on the changes of the
 460 lock/light state.