Skip to content

Testing Thread variant of lock application (nrf platform)

Jump to bottom
Lukasz Gniadzik edited this page Apr 7, 2021 · 4 revisions

This article describes how to use CHIPTool for Android smartphones to commission a Nordic Semiconductor nRF52840 DK running nRF Connect Lock Example Application onto a CHIP-enabled Thread network. The instructions are also valid for nRF Connect Lighting Example Application.

Overview

The commissioning process is composed of the following main stages:

  • CHIPTool discovers a CHIP accessory device over Bluetooth LE.
  • CHIPTool establishes a secure channel to the device over Bluetooth LE, and sends CHIP operational credentials and Thread provisioning data.
  • The accessory device joins a CHIP-enabled Thread network.

Bluetooth LE is only used during the commissioning phase. Afterwards, only the IP connectivity between the smartphone and the accessory device is needed to send operational messages. Since a typical smartphone does not have a Thread radio built-in, extra effort is needed to prepare a fully-fledged testing environment. This page describes how to build a Thread Border Router using a PC with a spare Wi-Fi card and an OpenThread Radio Co-Processor device.

The following diagram shows the connectivity between network components required to allow communication between devices running the CHIPTool and Lock applications:

               +--------------------+
               |    Smartphone      |
     +---------|  Android CHIPTool  |---------+
     |         +--------------------+         |
     |                                        | Wi-Fi
     |                                        |
     |                                +---------------+  Ethernet  +----------+
     |                                |      PC       |------------| Internet |
     |                                +---------------+            +----------+
     |                                        |
     | Bluetooth LE                           | USB
     |                                        |
     |                                +---------------+
     |                                |  nRF52840 DK  |
     |                                | OpenThread RCP|
     |                                +---------------+
     |                                        |
     |         +--------------------+         | Thread
     |         |    nRF52840 DK     |         |
     +---------|  Lock Application  |---------+
               +--------------------+

Requirements

You need the following hardware and software to build a Thread Border Router:

  • Two nRF52840 DK (PCA10056)

    • One nRF52840 DK is needed to run OpenThread Radio Co-Processor firmware and can be replaced with another compatible device like nRF52840 Dongle.

  • Smartphone compatible with Android 8.0 or later

  • PC with the following characteristics:

    • Software: Ubuntu 20.04 (or higher) and Docker installed
    • Hardware: A spare Wi-Fi card

While this page references Ubuntu Server 20.10 run on RPI 4, all the procedures can be completed using other popular operating systems and regular PC.

Programming OpenThread RCP firmware

OpenThread RCP firmware is required to allow the PC to communicate with Thread devices. Run the commands mentioned in the following steps to build and program the RCP firmware onto an nRF52840 DK:

  1. Download prebuild OpenThread RCP firmware for nrf52830 board:

    $ wget https://github.com/lukgni/lock-app-nrf-resources/main/ot-rcp.hex

  2. Program the RCP firmware:

    $ pyocd flash -t nrf52840 ot-rcp.hex

  3. Connect nrf52840 to the host RCP (Linux Machine)

    Because the OpenThread RCP build enables use of native USB CDC ACM as a serial transport,
    you must use the nRF USB port on the nRF52840 board to communicate with the RCP host
    (Linux machine).

    Detach the Micro-USB end of the USB cable from the debug port of the flashed nRF52840 board,
    then reattach it to the Micro-USB nRF USB port next to the RESET button.
    Set the nRF power source switch to USB.

    nrf52840-native-usb

    Note: When the nRF52840 board is properly connected to a host via the nRF USB port,
    none of the LED indicators light up, even though the board is operational.

  4. Power-cycle the device to apply the changes.

Configuring PC as Thread Border Router

To make your PC work as a Thread Border Router, complete the following tasks:

  1. Form a Thread network using the OpenThread RCP device and configure IPv6 packet routing to the network.
  2. Configure a Wi-Fi hotspot using a spare Wi-Fi card on your PC.

Forming Thread network

To form a Thread network, complete the following steps:

  1. Create an IPv6 network for the OpenThread Border Router (OTBR) container in Docker:

    $ docker network create --ipv6 --subnet 2001:db8:1::/64 -o com.docker.network.bridge.name=otbr0 otbr

  2. Start the OTBR container using the following command. In the last line, provide the device node name of the nRF52840 kit that is running the RCP firmware before :/dev/radio (in this case, the name is /dev/ttyACM0):

    $ docker run -it --rm --privileged --network otbr -p 8080:80 \
        --sysctl "net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1" \
        --volume /dev/ttyACM0:/dev/radio openthread/otbr --radio-url spinel+hdlc+uart:///dev/radio

  3. Open the http://localhost:8080/ address in a web browser.

  4. Click Form in the menu to the left. The network forming creator window appears.

  5. Make sure that the On-Mesh Prefix is set to fd11:22::. This value is used later to configure the IPv6 packet routing.

  6. Click the Form button at the bottom of the window to form a new Thread network using the default settings.

  7. Run the following command to learn which IPv6 address was assigned to the OTBR container in Docker.

     $ docker network inspect otbr | grep IPv6Address

    After checking the output, the address will most likely be 2001:db8:1::2.

  8. To ensure that packets targeting Thread network nodes are routed through the OTBR container in Docker, run the following command, with 2001:db8:1::2 replaced with the actual address obtained in the previous step:

    $ sudo ip -6 route add fd11:22::/64 dev otbr0 via 2001:db8:1::2

Configuring Wi-Fi hotspot

To configure a Wi-Fi hotspot using a spare Wi-Fi card on your PC, complete the following steps:

On Ubuntu Server distribution, nmcli has to be installed first to configure Wi-Fi hotspot.

$ sudo snap install network-manager
$ sudo snap connect network-manager:nmcli

  1. Create Wi-Fi hotspot using nmcli tool:

    $ nmcli con add type wifi ifname wlan0 con-name Hotspot autoconnect yes ssid Hostspot

  2. Setup hotspot IPV4 settings:

    $ nmcli con modify Hotspot 802-11-wireless.mode ap 802-11-wireless.band bg ipv4.method shared

  3. Run the following command to assign a well-known IPv6 address to the hotspot interface:

    $ nmcli connection modify Hotspot ipv6.method manual ipv6.addresses 2001:db8:2::1/64

  4. Run the following command to set hotspot password:

    $ nmcli con modify Hotspot wifi-sec.key-mgmt wpa-psk
$ nmcli con modify Hotspot wifi-sec.psk "<user password>"

  5. Enable created hotspot:

    $ nmcli con up Hotspot

  6. Run the following command to install Routing Advertisement Daemon (radvd), which enables the IPv6 auto-configuration of devices that connect to the hotspot:

    $ sudo apt install radvd

  7. Learn the hotspot interface name by running the following command:

    $ nmcli connection show Hotspot | grep interface-name

  8. Add the following lines into /etc/radvd.conf, with wlo1 replaced with the hotspot interface name obtained in the previous step:

    interface wlo1
{
  MinRtrAdvInterval 3;
  MaxRtrAdvInterval 4;
  AdvSendAdvert on;
  AdvManagedFlag on;
  prefix 2001:db8:2::/64
  {
     AdvValidLifetime 14300;
     AdvPreferredLifetime 14200;
  };
};

  9. Start the radvd service by running the following command:

    $ sudo systemctl start radvd

To automatically start the radvd service on every reboot, run the following command:

$ sudo systemctl enable radvd

If you use Ubuntu 18.04 a DHCP server is not configured automatically when creating a Wi-Fi hotspot. As a result, devices that connect to the hotspot will not be assigned an IPv4 address and may not work properly. To address the problem, install and configure a DHCP server on the hotspot interface. For example, you can use isc-dhcp-server.

Building and programming nRF Connect Lock Example Application

See nRF Connect Lock Example Application README to learn how to build and program the example onto an nRF52840 DK.

Installing Android CHIPTool

Android CHIPTool apk files can downloaded from associated github workflow job:

https://github.com/ARMmbed/connectedhomeip/actions/workflows/android.yaml

or builded manually following below instruction:

https://github.com/ARMmbed/connectedhomeip/wiki/The-easiest-way-to-build-Android-CHIPTool-app

  1. Install the Android Debug Bridge (adb) package by running the following command:

    $ sudo apt install android-tools-adb

  2. Enable USB debugging on the smartphone. See the Configure on-device developer options guide on the Android Studio hub for detailed information.

  3. If the Install via USB option is supported for your Android version, turn it on.

  4. Plug the smartphone into an USB port on your PC.

  5. Run the following command to install the application, with chip-dir replaced with the path to the CHIP source directory:

    $ adb install -r chip-dir/src/android/CHIPTool/app/build/outputs/apk/debug/app-debug.apk

  6. Navigate to settings on your smartphone and grant Camera and Location permissions to CHIPTool.

CHIPTool is now ready to be used for commissioning.

Preparing accessory device

To prepare the accessory device for commissioning, complete the following steps:

  1. Use a terminal emulator to connect to the UART console of the accessory device. For example:

    $ screen /dev/ttyACM0 115200

  2. Hold Button 1 on the accessory device for more than 6 s to trigger the factory reset of the device.

  3. Find a message similar to the following one in the application logs:

    I: 666[SVR] Copy/paste the below URL in a browser to see the QR Code:
        https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3AI34DV%2A-00%200C9SS0

  4. Open the URL in a web browser to have the commissioning QR code generated.

  5. Push Button 4 on the device to start Bluetooth LE advertising.

Commissioning accessory device

To commission the accessory device onto the Thread network created in the Forming Thread network section, complete the following steps:

  1. Enable Bluetooth and Location services on your smartphone.
  2. Connect the smartphone to the Wi-Fi Hotspot created in the Configuring Wi-Fi hotspot section.
  3. Open the CHIPTool application on your smartphone.
  4. Tap the PROVISION CHIP DEVICE WITH THREAD button and scan the commissioning QR code. Several notifications will appear, informing you of commissioning progress with scanning, connection, and pairing. At the end of this process, the Thread network settings screen appears.
  5. In the Thread network settings screen, use the default settings and tap the SAVE NETWORK button to send a Thread provisioning message to the accessory device.

You will see the "Network provisioning completed" message when the accessory device successfully joins the Thread network.

Sending CHIP commands

Once the device is commissioned, the following screen appears:

CHIPTool device control screen

This means that the provisioning is completed successfully and you are connected to the device. Check the connection with the following steps:

  1. Verify that the text box on the screen is not empty and contains the IPv6 address of the accessory device.

  2. Tap the following buttons to change the lock state:

    • ON and OFF buttons lock and unlock the door, respectively.
    • TOGGLE changes the lock state to the opposite.

The LED 2 on the device turns on or off based on the changes of the lock state.

Additionally lock state change will be reported in device logs:

 ...
 I: 494374[SVR] Packet received from UDP:2001:db8:2:0:781d:c598:8290:7356:11097: zu bytes
 D: 494381[ZCL] APS frame processing success!
 I: 494386[ZCL] RX len 3, ep 1, clus 0x 6 
 I: 494389[ZCL]  FC 1 seq 0 cmd 2 payload[
 I: 494393[ZCL] NULL
 I: 494395[ZCL] ]
 I: 494396[ZCL] On/Off set value: 1 2
 I: 494400[ZCL] Toggle on/off from 1 to 0
 D: 494403[ZCL] Measured APS frame size 11
 D: 494407[ZCL] Successfully encoded 11 bytes
 D: 494411[IN] Secure message was encrypted: Msg ID 25
 I: 494416[IN] Sending msg from lu to lu
 I: 494420[IN] Sending secure msg on generic transport
 I: 494425[IN] Secure msg send status 0
 I: 494428[ZCL] T   0:TX (0x6861a) Ucast 0x00x7148f
 I: 494433[ZCL] TX buffer: [
 I: 494435[ZCL] 0hX0hX0hX0hX0hX
 I: 494438[ZCL] ]
 D: 494440[ZCL] Data model processing success!
 I: Unlock Action has been initiated
 I: Unlock Action has been completed
 ...
Clone this wiki locally