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 Configuring external Thread Commissioning.

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

use the standard Ethernet cable with an RJ-45 plug;
use a built-in Wi-Fi module.

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

nRF52840 Development Kit
nRF52840 Dongle
nRF52811 Development Kit

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 on GitHub.

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:

Raspberry Pi 3 B or Raspberry Pi 3 B+
One of the following boards:
- nRF52840 DK
- nRF52840 Dongle
- nRF52811 DK
microSD card (4 GB or larger) with SD card adapter
microUSB power supply for Raspberry Pi
microUSB to USB cable for connecting the Development Kit to the Raspberry Pi
Computer running the Windows operating system with an SD card slot or an SD-microSD USB adapter
Note
Windows is used in this procedure, but Linux and macOS operating systems are also supported.
Optionally, you can also use:
EXPLORE-NFC-WW Raspberry Pi shield – required for running the Thread NFC MeshCoP Example
Additional nRF52840 Development Kit for Border Router testing – a client that can connect to the Internet using the Border Router
Android Device for external commissioning testing

Required software

Make sure you install the following software:

Win32 Disk Imager
nrfjprog – available in nRF5x-Command-Line-Tools-Win32 from the nRF52840 product website
Terminal client with serial connection support, such as PuTTy
Border Router Raspberry Pi image available from nRF5 SDK for Thread web page – RaspPi_OT_Border_Router_Demo_v3.1.0-1.alpha.img
NCP/RCP example located at <InstallFolder>/examples/thread/ncp
CLI example located at <InstallFolder>/examples/thread/cli

Setup procedure

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

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

Insert the microSD card into your computer.
Start the Win32 Disk Imager.

Win32 Disk Imager
In the Image File field, point to RaspPi_OT_Border_Router_Demo_v3.1.0-1.alpha.img.
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.
Click Write.
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.
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

Connect the nRF52840 Development Kit to the computer and power it on.
Open the command line terminal.
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:

Insert the nRF52840 Dongle into an USB port.
Press the reset button to enter the DFU mode. The LD2 LED starts blinking red.
Launch nRF Connect for Desktop and start the Programmer application.
From the list of devices, select Nordic Semiconductor DFU Bootloader.
Click Add HEX file and select the correct firmware for the dongle.
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.
Click Write to flash the firmware.
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

Connect the nRF52811 Development Kit to the computer and power it on.
Open the command line terminal.
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:

UART
USB
SPI

See the following subsections for details.

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

All these options can be used with either Network Co-Processor (NCP) or Radio Co-Processor (RCP). The wpantund.conf file contains several predefined configurations for NCP or RCP usage with all transport options. To use any of these configurations, uncomment the related section of the file.

The Border Router image comes with the prebuilt Thread stack (ot-ncp) for the POSIX platforms installed, which allows for controlling the RCP firmware running on a less powerful SoC. Together, they form the fully fledged NCP.

Configuring and 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/RCP application acting as an SPI slave and the Border Router as the SPI master device. To set up this configuration:

Connect physically the SPI pins of the Border Router and the Development Kit (nRF52840 or nRF52811) that is hosting the NCP/RCP application.
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:

MOSI (Master Out Slave In)
MISO (Master In Slave Out)
SCK (Serial Clock)
CSN (Slave Select)
optionally: INT (Interrupt)

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, see the following schematic that 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 40 (GPIO21)	P0.30

Default pin configuration

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.

Connecting the Co-Processor over SPI

After completing the configuration, to connect the Co-Processor over SPI:

Disable the automatic detection of NFC shields on the Border Router:
- Log in to the Border Router and type the following command:
  sudo chmod a-x /etc/ncp_state_notifier/dispatcher.d/50-ncp_commissioner_enabler
Disable the jlink_config service that searches and configures J-Link connections and can affect the initialization time of the wpantund daemon:
- Log in to the Border Router and type the following command:
  sudo systemctl disable jlink_config
Choose SPI as the transport protocol for wpantund, a daemon managing the Co-Processors:
1. Open the wpantund.conf file available at the /etc/ folder.
2. Find the default NCP:SocketPath configuration section.
3. Edit the configuration to use the RCP or NCP (or both) with the SPI transport:
  - For the NCP, provide path to the HDLC framer binary and, optionally for a better performance, to the interrupt pin:
    Config:NCP:SocketPath "system:/usr/bin/spi-hdlc-adapter -i /sys/class/gpio/gpio21 /dev/spidev0.1"
  - For the RCP, provide the complete set of parameters, including the path to the OpenThread POSIX stack binary:
    Config:NCP:SocketPath "system:/usr/bin/ot-ncp /usr/bin/spi-hdlc-adapter -- '--stdio -i /sys/class/gpio/gpio21 /dev/spidev0.1'"

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 GPIO21 on the Raspberry Pi. 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

Note: It is recommended to disable the automatic detection of NFC shields on the Border Router if the NFC shield is not used. Log in to the Border Router and type the following command:
sudo chmod a-x /etc/ncp_state_notifier/dispatcher.d/50-ncp_commissioner_enabler

Connect the J-Link microUSB port of the Development Kit (nRF52840 or nRF52811) to the Raspberry Pi USB port.
Choose UART as the transport protocol for wpantund, a daemon managing the Co-Processors:
1. Open the wpantund.conf file available at the /etc/ folder.
2. Find the default NCP:SocketPath configuration section. This configuration section is valid for:
  - the NCP configuration:
    Config:NCP:SocketPath "serial:/dev/ttyACM0,raw,b115200,crtscts=1"
  - the RCP configuration:
    Config:NCP:SocketPath "system:/usr/bin/ot-ncp /dev/ttyACM0 115200"

Connecting the Co-Processor over USB

Note: It is recommended to disable the automatic detection of NFC shields on the Border Router if the NFC shield is not used. Log in to the Border Router and type the following command:
sudo chmod a-x /etc/ncp_state_notifier/dispatcher.d/50-ncp_commissioner_enabler

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.
Disable the jlink_config service that searches and configures J-Link connections and can affect the initialization time of the wpantund daemon:
- Log in to the Border Router and type the following command:
  sudo systemctl disable jlink_config
Choose USB as the transport protocol for wpantund, a daemon managing the Co-Processors:
1. Open the wpantund.conf file available at the /etc/ folder.
2. Find the default NCP:SocketPath configuration section. This configuration section is valid for:
  - the NCP configuration:
    Config:NCP:SocketPath "serial:/dev/ttyACM0,raw,b115200,crtscts=1"
  - the RCP configuration:
    Config:NCP:SocketPath "system:/usr/bin/ot-ncp /dev/ttyACM0 115200"

Step 4: Starting the Border Router

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.
Power on the nRF52840.
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.

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

Connectivity

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

NAT64 technology
- This technology is used to enable communication between the IPv6-only Thread network with the pure IPv4 LAN network that the Border Router connects to, as is the case in most applications. In this way, Thread nodes are able to connect to the IPv4 cloud services.
Native IPv6 connection
- This option uses the built-in DHCPv6 client on the Border Router, which is able to receive prefixes from the Ethernet of the WiFi interface. If the received prefix is shorter than 63 bits, the 64-bit long subnet prefix is created and forwarded to the Thread network. In such a situation, devices create one more address based on the forwarded prefix, which allows them to be reached from the Internet (unlike in a pure NAT64 solution).
  Note
  When dealing with the native IPv6 connectivity, make sure you use the DHCPv6 service and not the popular Stateless Address Autoconfiguration (SLAAC) tool. This autoconfig tool will only provide a 64-bit long prefix that is not sufficient to delegate a new 64-bit long prefix for the Thread network.
  Additionally, support for Domain Name System (DNS) resolution is also available. This mechanism is used to translate a host name into a corresponding IP address. It can be used either for translating a domain name into its native IPv6 or for obtaining its IPv4 address and returning IPv6 translated with the DNS64 mechanism.

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.

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
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.
  
  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.
  
  Second step of PuTTy configuration
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.
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.
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.
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.

Connect to the Nordic Thread Border Router Wi-Fi network.
SSID: BorderRouter-AP

Password: 12345678
Open an SSH client and connect to the address 10.42.0.1.
Username: pi

Password: raspberry
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.
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.

Table of Contents