nRF5 SDK for Thread and Zigbee v3.0.0
Thread Border Router

Table of Contents

Thread Border Router serves as a gateway between the Internet and the Thread network. The Border Router is intended for development purposes, to enable developers to connect their Thread network to the Internet during the development phase. It also supports the Thread native commissioning procedure by using NFC to initiate the process. The Border Agent functionality is also supported, which allows for performing an external commissioning procedure as described in Commissioning.

There are two ways of connecting the Thread Border Router to the Internet:

The Border Router consists of Raspberry Pi 3 B and one of the following Nordic boards:

Optionally, it can also include the NFC reader shield from NXP Semiconductors. This component is used for the Thread native commissioning, but it is not required for connecting a Thread network to the Internet.

Both the nRF52840 DK and the dongle act as connectivity chips running the Thread NCP/RCP Example application. The nRF52811 DK is capable of running only the RCP variant of the Thread NCP/RCP Example application. Both DKs and the dongle communicate with Raspberry Pi using the Spinel protocol.

Raspberry Pi firmware is based on Raspbian (distribution 2019-02-12) and contains several deamons for controlling the NCP (or RCP) and the NFC reader shield, such as wpantund and NFC Reader Library for Linux available at NFC shield vendor website. Due to license limitations, NFC Reader Library is distributed as a binary embedded in the Thread Border Router Raspberry Pi firmware image. For more information regarding the Nordic OpenThread Border Router build, refer to README.md.

For your convenience, this SDK provides pre-built, ready-to-use binary images for Raspberry Pi and the Development Kit (nRF52840 DK and Dongle, and nRF52811 DK). The binary image intended for the Border Router is distributed under a license that is provided together with the Border Router image file. The EXPLORE_NFC_WW license applies if you use the Border Router feature to natively commission nodes using NFC. Licenses can be found in the package containing the Border Router binary image.

Required hardware

Make sure you have the following hardware:

Required software

Make sure you install the following software:

Setup procedure

Complete the following steps to set up the Border Router solution.

Step 1: Flashing the Raspberry Pi image to the microSD card

  1. Insert the microSD card into your computer.
  2. Start the Win32 Disk Imager.
    br_disk_imager.png
    Win32 Disk Imager
  3. In the Image File field, point to RaspPi_OT_Border_Router_Demo_v2.0.0-1.alpha.img.
  4. In the Device field, select a device that corresponds to the microSD memory card that you connected to the computer.
    Warning
    If you choose an incorrect device, you may overwrite a partition on your computer or another device. Verify your choice by checking the letter mapped to the microSD card in My Computer.
  5. Click Write.
  6. After the image has been flashed, safely remove the microSD card from your computer: right-click the USB symbol in the taskbar and click Eject on the volume that represents the SD card.
  7. Insert the microSD card into your Raspberry Pi.

Step 2: Flashing the Co-Processor

The procedure to complete in this step depends on the board you are using.

Option A: Flashing the Network Co-Processor to the nRF52480 Development Kit

  1. Connect the nRF52840 Development Kit to the computer and power it on.
  2. Open the command line terminal.
  3. Run the following command:
    nrfjprog --chiperase --family NRF52 --program <InstallFolder>/examples/thread/ncp/ftd/uart/hex/nrf52840_xxaa_pca10056.hex
    Note
    You can also use either the USB CDC version or the SPI version of the NCP/RCP example. However, if the USB version is selected, you must use the native nRF USB port. To set up the SPI version, refer to Step 3: Connecting the Co-Processor with the Raspberry Pi.

Option B: Flashing the Network Co-Processor to the nRF52480 Dongle

The HEX file to be used for programming the nRF52840 Dongle is: <InstallFolder>/examples/thread/ncp/ftd/usb/hex/nrf52840_xxaa_mbr_pca10059.hex.

To flash the firmware on the dongle:

  1. Insert the nRF52840 Dongle into an USB port.
  2. Press the reset button to enter the DFU mode. The LD2 LED starts blinking red.
  3. Launch nRF Connect for Desktop and start the Programmer application.
  4. From the list of devices, select Nordic Semiconductor DFU Bootloader.
  5. Click Add HEX file and select the correct firmware for the dongle.
  6. Ensure that the beginning of the address of the firmware image is 0x00001000. If a wrong hex file is selected, the MBR section might be overwritten.
  7. Click Write to flash the firmware.
  8. Remove the dongle from USB port and insert it again. Do not press the Reset button.

Option C: Flashing the Radio Co-Processor to the nRF52811 Development Kit

  1. Connect the nRF52811 Development Kit to the computer and power it on.
  2. Open the command line terminal.
  3. Run the following command:
    nrfjprog --chiperase --family NRF52 --program <InstallFolder>/examples/thread/ncp/radio/uart/hex/nrf52811_xxaa_pca10068_nrf52811.hex
    Note
    You can also use also the SPI version of the NCP/RCP example. To set up the SPI version, refer to Step 3: Connecting the Co-Processor with the Raspberry Pi.

Step 3: Connecting the Co-Processor with the Raspberry Pi

You can connect both the Network and the Radio Co-Processor by using the following options:

See the following subsections for details.

Note
nRF52811-based Radio Co-Processor does not support native USB.

Connecting the Co-Processor over SPI

Both the Network Co-Processor and the Radio Co-Processor can be connected to the Border Router over the SPI protocol with the NCP application acting as an SPI slave and the Border Router as the SPI master device. To set up this configuration:

  1. Connect physically the SPI pins of the Border Router and the Development Kit (nRF52840 or nRF52811) that is hosting the NCP/RCP application.
  2. Enable and properly configure the SPI peripheral on the Border Router.
Warning
Due to the single-SPI transfer size limitation, do not use the engineering version A of the nRF52840 chip for the NCP application with SPI support.

Connecting SPI pins

To establish an SPI connection, the following pins must be connected:

The INT pin is optional, but the lack of it significantly reduces the performance of communication. The Raspberry Pi has predefined the SPI pins that can be found in its datasheet. The SPI pins on the Development Kit (nRF52840 or nRF52811) can be configured when building the example. The default configuration can be found in the following table. As an example, a schematic created with Fritzing is also shown, which uses the default configuration.

SPI pin Raspberry Pi pin nRF52840 or nRF52811 pin
MOSI pin 19 (GPIO10) P0.04
MISO pin 21 (GPIO09) P0.28
SCK pin 23 (GPIO11) P0.03
CSN pin 26 (GPIO07) P0.29
INT pin 22 (GPIO25) P0.30
Default pin configuration
br_ncp_spi.png
Connecting NCP or RCP to the Border Router over SPI

Configuring the Border Router SPI

The SPI peripheral is enabled by default on the Border Router. You can verify this by checking that the /dev/spidev0.0 and /dev/spidev0.1 devices are visible.

When the NCP or the RCP is connected with the SPI to the Border Router, complete the following actions:

In this example, it is assumed that spi-hdlc-adapter and OpenThread POSIX App are installed in /usr/bin/ and that the INT pin is connected to GPIO25 on the Raspberry Pi. The ot-ncp is the Thread stack capable of running on POSIX systems. Together with the RCP firmware running on the less powerfull SoC it forms the fully fledged NCP that communicates with the wpantund. The spi-hdlc-adapter is a tool that is used to perform communication between wpantund and NCP over the SPI transport.

Connecting the Co-Processor over UART

Connect the J-Link microUSB port of the Development Kit (nRF52840 or nRF52811) to the Raspberry Pi USB port.

Connecting the Co-Processor over USB

Connect the native USB port of the nRF52840 Development Kit (the one on the side) or the nRF52840 Dongle to the Raspberry Pi USB port.

Step 4: Starting the Border Router

  1. Connect the Raspberry Pi with an Ethernet cable or through WiFi to your switch or router that provides the IPv4 or the IPv6 connectivity with the DHCP or the DHCPv6 service, respectively.
  2. Power on the nRF52840.
  3. Connect the microUSB power supply to the Raspberry Pi. The Border Router starts booting. Depending on your microSD card speed, the Border Router should be fully operational within two minutes.
    br_start.png
    Starting the Border Router

Thread Settings

The following are the default settings of the Border Router.

Radio Channel: 11
PAN ID: 0xABCD
Network Master Key: 0x00112233445566778899AABBCCDDEEFF
Mesh-Local Prefix: FDDE:AD00:BEEF::/64
NAT64 Prefix: 64:FF9B::/96
PSKc: 123456

Connectivity

You can choose one of the following connectivity options (both enabled by default):

Testing with nRF52840 DK - NCP

To test the Border Router, you can use another node with command line interface (CLI) and ping the Google DNS server 8.8.8.8.

  1. Flash another nRF52840 Development Kit with nrfjprog, as described in Thread CLI Example. This time, use the following command.
    nrfjprog --chiperase --family NRF52 --program <InstallFolder>/examples/thread/cli/ftd/uart/hex/nrf52840_xxaa_pca10056.hex --reset
  2. Start a terminal emulator like PuTTY and connect to the used COM port with the following UART settings:
    • Baud rate: 115200
    • 8 data bits
    • 1 stop bit
    • No parity
    • HW flow control: RTS/CTS
    Note
    RTS/CTS based flow control is enabled on all examples that provide the command line interface.
    To find the particular COM port to connect to, open the Device Manager. The COM port number is displayed in the Ports (COM & LPT) tab next to the J-Link CDC UART Port.
    1. PuTTy must be configured in two steps. First, in the Session tab, set the the Serial line, Speed, and Connection Type values.
      br_putty_settings_1.png
      First step of PuTTY configuration
    2. Then, in the Connection -> Serial tab, set the remaining parameters, that is Data bits, Stop Bits, and Flow control.
      br_putty_settings_2.png
      Second step of PuTTy configuration
  3. After the console window appears, press Enter. If the prompt mark ">" appears, the serial connection has been established. When a command is executed successfully, ">Done" is reported.
  4. Run the following commands.
    panid 0xabcd
    ifconfig up
    thread start
    state
    ping 64:ff9b::0808:0808
    After running the command, the following result appears:
    8 bytes from 64:ff9b:0:0:0:0:808:808: icmp_seq=1 hlim=56 time=55ms
    Note
    In the command, 0808:0808 is in fact the Google DNS server address "8.8.8.8" in hex representation. In that way, you can reach any IPv4 cloud by replacing last 32 bits of an IPv6 address with a correctly encoded IPv4 address.
  5. Obtain the addresses of the connected node by typing ipaddr.
    > ipaddr
    2001:db8:dead:beef:98ba:8f31:fc05:6919
    fd11:22:0:0:b85d:8ff4:3011:3797
    fdde:ad00:beef:0:bebd:ae25:a6c7:a0b5
    fdde:ad00:beef:0:0:ff:fe00:b001
    fe80:0:0:0:a4aa:fd14:d403:89d6
    Done
    Note
    There can be more IPv6 addresses assigned to the interface. It depends on the configuration of the routers on the link from which the Border Router gets IPv6 prefixes. If IPv6 connectivity is present, the device obtains the global IPv6 address starting with a 2000::/3 prefix (in this example, 2001:db8:dead:beef:98ba:8f31:fc05:6919). This address can be used to reach the node from any IPv6-connected device. The simplest test is to ping this address from a computer connected to the IPv6 network.
  6. You can use DNS to resolve the native IPv6 address of the given host name in the following way.
    > dns resolve ipv6.google.com
    > DNS response for ipv6.google.com - [2a00:1450:401b:802:0:0:0:200e] TTL: 299
    > ping 2a00:1450:401b:802:0:0:0:200e
    > 8 bytes from 2a00:1450:401b:802:0:0:0:200e: icmp_seq=2 hlim=55 time=42ms

If the host does not have IPv6 connectivity, a Thread device may still connect with a IPv4 cloud utilizing the NAT64 and DNS64 protocols. To obtain a a translated IPv6 address, you must specify the DNS resolver fdaa:bb:1::1 which is running on the Thread Border Router, as shown below.

> dns resolve ipv4.google.com
> DNS response for ipv4.google.com - Error 25
> dns resolve ipv4.google.com fdaa:bb:1::1
> DNS response for ipv4.google.com - [64:ff9b:0:0:0:0:d83a:d5ee] TTL: 300
> ping 64:ff9b:0:0:0:0:d83a:d5ee
> 8 bytes from 64:ff9b:0:0:0:0:d83a:d5ee: icmp_seq=3 hlim=50 time=87ms

Error 25 indicates that there is no IPv6 address returned as the ipv4.google.com does not have any.

Thread Border Router Wi-Fi usage and configuration

In a typical use case, it is assumed that no additional communication interface is present. In such scenario, Thread Border Router starts in Access Point mode, advertising its own Wi-Fi network called "BorderRouter-AP". A user connects to this network and chooses a local Wi-Fi network for the Thread Border Router to connect to.

After each reboot, the Border Router enables Access Point mode and advertises the "BorderRouter-AP" network.

When the Access Point is enabled, the following steps are required to connect the Thread Border Router to the specified Wi-Fi network in a client mode.

  1. Connect to the Nordic Thread Border Router Wi-Fi network.
    SSID: BorderRouter-AP
    Password: 12345678
  2. Open an SSH client and connect to the address 10.42.0.1.
    Username: pi
    Password: raspberry
  3. Enter the following command to get a list of available Wi-Fi networks.
    pi@raspberrypi:~$ sudo iwlist scan | grep SSID
    lo Interface doesn't support scanning.
    wpan0 Interface doesn't support scanning.
    ESSID:"Linksys"
    ESSID:"TS_WiFi_2_4_GHz"
    eth0 Interface doesn't support scanning.
    nat64 Interface doesn't support scanning.
  4. Enter the following command to connect to the selected Wi-Fi network.
    pi@raspberrypi:~$ wifi_connect <SSID> [password]
    Note
    password is an optional parameter that must be provided if the selected network is protected by WPA-PSK encryption.
    From now on, the Access Point provided by the Thread Border Router is no longer available. The SSH connection is terminated. Thread Border Router is now connected to the selected Network and obtains its IPv4 and IPv6 addresses using DHCP and DHCPv6 respectively.

If connecting to the selected Wi-Fi network fails, the Border Router enables the Access Point again.

Running MQTT-SN Gateway on Thread Border Router

The MQTT-SN Gateway used in the Thread MQTT-SN Example can be run on the Thread Border Router.

The MQTT-SN Gateway is enabled by default.

With this option enabled, MQTT-SN Gateway starts automatically once you reboot the Raspberry Pi. The gateway has already been configured to work correctly with the Thread MQTT-SN Example.

Optionally, you can also disable the MQTT-SN Gateway. To do so, run the following command.

sudo systemctl disable paho-mqttsn-gateway.service

Configuration of the MQTT Broker

The configuration file for the Paho MQTT-SN Gateway is located in /etc/paho-mqtt-sn-gateway.conf. By default, the IPv4 address of the Eclipse IoT MQTT Broker is used. You may want to use another MQTT Broker. To do that, modify the BrokerName and BrokerPortNo variables in the configuration file.

Note
You need to type the IPv4 address of the MQTT Broker. The host name representation is currently not supported.

Commissioning

The Nordic Border Router, which is based on the OpenThread Border Router (OTBR), supports both native and external commissioning.

This guide describes external Thread Commissioning with the use of the Thread App for Android.

Note
During commissioning, the Thread Commissioner never gains possession of the network master key.

This guide details how to use the Thread Commissioning App to commission the Nordic CLI example device onto the Thread Network.

Forming the Thread network

Precondition
  1. Make sure that the EXPLORE-NFC shield is not connected to the Raspberry Pi. Raspberry Pi must be powered off when you disconnect the shield.
  2. Prepare the Border Router as described in Setup procedure.
  3. Flash an nRF52840 Development Kit with the CLI example. You can use either the UART or the USB version.
    nrfjprog --chiperase --family NRF52 --reset --program <InstallFolder>/examples/thread/cli/ftd/uart/hex/nrf52840_xxaa_pca10056.hex
  4. Once the Joiner device is ready, obtain its IEEE EUI-64. To do this, use the eui64 command in the OpenThread CLI.
    > eui64
    14def7d76bbd2876
    Done
  5. Download and install the Thread Commissioning App that supports the external commissioning. It is available only for Android devices in the Google Play Store.

Once the Thread Commissioning App is downloaded and installed:

  1. Start the Thread Commissioning App.
    commissioning_1.png
    Start the app

  2. Tap FIND WI-FI NETWORK and connect the device running the Thread Commissioning App to the Wi-Fi access point.
    commissioning_2.png
    Connect to the Wi-Fi access point

    Note
    The smartphone running the Thread Commissioning App and the Thread Border Router must be connected to the same Local Area Network. In this example, the smartphone is connected to the Access Point on your Thread Border Router. However, you may as well connect the Border Router to your Local Network (either using Wi-Fi or Ethernet) together with your smartphone. In this case, the joining node will be able to connect to the Internet through the Border Router.
  3. Select the target Border Router from the available list. The name is the same as the Thread network created by the OTBR Web GUI. If the same Border Router shows up multiple times with different IPv4 and IPv6 addresses, select the one with the static IPv4 address used for the Wi-Fi access point setup (10.42.0.1 in this case).
    commissioning_3.png
    Select the Border Router to connect to

  4. When prompted for a password, enter the passphrase 123456 (Commissioner Credential). The passphrase 123456 is automatically configured during the autostart procedure. The passphrase may differ if it has been changed in the Form Network section in the web panel.
    commissioning_4.png
    Enter the passphrase

  5. Commission the Joiner. Once connected to the Border Router, the app provides the option to scan a Connect QR Code or enter a Join Passphrase manually.
    commissioning_5.png
    Commission the Joiner

  6. Optional: Generate a QR code.
    commissioning_6.png
    Generate a QR code

    Thread Connect QR Codes are created with the following text string format:
    v=1&&eui=14def7d76bbd2876&&cc=N0RD1C
    In this string, eui is the Joiner device's EUI64 value and cc is the Joiner Credential. Use this text string with an online QR Code generator to create a QR Code for scanning.
    Note
    The Joiner Credential is a device-specific string of all uppercase alphanumeric characters (0-9 and A-Y, excluding I, O, Q, and Z for readability), with a length between 6 and 32 characters.
  7. Scan the QR code or manually enter the EUI64 and Joiner Credential. Scanning the Connect QR Code or manually entering the credentials generates the PSKd, which propagates the steering data through the Thread network.
    commissioning_7.png
    Adding the Joiner to the Thread Network

  8. Start the Joiner. While the app is waiting, enter the OpenThread CLI on the Joiner device and start the Joiner role with the same Joiner Credential:
    > ifconfig up
    Done
    > joiner start N0RD1C
    Done
    Wait a minute for the DTLS handshake to complete between the Commissioner and Joiner.
    >
    Join success!
    commissioning_8.png
    Joiner added to the Network

    The Thread Commissioning App displays an "Added My Thread Product" confirmation message.
    The Joiner has obtained the Thread network credentials and can now join the network.
  9. Join the network. On the Joiner device:
    1. Start the Thread protocol to automatically join the network.
      > thread start
      Done
    2. Check the state after a few moments to confirm. It may initially start as a Child, but within two minutes, it will upgrade to a Router.
      > state
      router
      Done
    3. Check the IPv6 addresses of the device. If the Nordic Border Router is connected to the Internet, the Joiner will have the ability to connect with the outside world. In case there is a native IPv6 connection with prefix equal or shorter than /63 available for the Border Router, it will assign the /64 global pool for the Thread Network. In case of lack of a proper prefix, NAT64 can still be used with the local IPv4 connection.
      > ipaddr
      fdde:ad11:11de:0:0:ff:fe00:9400
      fd11:22:0:0:3a15:3211:2723:dbe1
      fe80:0:0:0:6006:41ca:c822:c337
      fdde:ad11:11de:0:ed8c:1681:24c4:3562

Testing the connectivity

You can test the connectivity between the Joiner device in the Thread network and the Internet by pinging a public IPv4 address.

To reach the IPv4 address from the Thread device, a Well-Known Prefix of 64:ff9b::/96 and an IPv4 address of the destination are used.

Connectivity test example
To ping Google’s DNS 8.8.8.8 from the IPv6 address, append a hexadecimal form of the IPv6 to the Well-Known Prefix resulting in: 64:ff9b::808:808.
Ping this address from the device running the Nordic CLI example (the Joiner):

> ping 64:ff9b::808:808
> 8 bytes from 64:ff9b:0:0:0:0:808:808: icmp_seq=3 hlim=45 time=72ms

Documentation feedback | Developer Zone | Subscribe | Updated