Introduction

In this module we will learn about the Thread Border Router. What is a border router? How does the border router facilitate secure joining? How does the border router enable device to device and device to cloud communication? This tutorial will give you an overview of the workings of a border router and get you started with one based on BeagleBone Black and the SimpleLink™ Ecosystem.

In this lab we will be working with a BeagleBone Black, a WiFi router, and a few LaunchPads to create a working Thread Network. The first two tasks will be to setup the BeagleBone Black and setup the LaunchPads. In the next three tasks, we will look at; forming a Thread network with the border router, securely joining an example application into the Thread Network, and interacting with the example application.

This tutorial will take about three hours to complete and requires basic understanding of the Linux runtime and BeagleBone Black Development (see the Prerequisites section for details).

Prerequisites

BeagleBone Black Getting Started

It is highly recommended that you read and get familiar with the BeagleBone Black documentation. Specifically the getting started guide available here.

Other SimpleLink Academy Labs

You should be familiar with building and programming Thread Examples explained in the Thread CLI Project Zero.

Software

• CCS version 11.2 or later with support for CC13xx/CC26xx devices installed

• SimpleLink CC13xx / CC26xx SDK (6.20)

• Serial terminal program, such as:

  • PuTTY
  • Tera Term
  • RealTerm
  • Windows PowerShell

• SD card programmer, such as:

  • Etcher
  • Win32DiskImager

• Archival tool, such as:

  • tar
  • 7-Zip

Hardware

• 2x LaunchPads of either

  • SimpleLink CC26X2R1 LaunchPads, or
  • SimpleLink CC1352R1 LaunchPads, or
  • SimpleLink CC1352P-2 LaunchPads, or
  • SimpleLink CC2652RB LaunchPads, or
  • SimpleLink CC1352P7 Launchpad

• 1x BeagleBone Black

• 1x uSD Card with minimum 8 GB storage

• 1x WiFi Router

Recommended Reading

It is recommended to familiarize yourself with the Thread Specification.

It is recommended to read the TI-OpenThread User's Guide alongside this lab for details and further information.

Overview

In this section we give an overview of the Thread Border Router and its function within the Thread Network.

About the Thread Border Router

A Thread Border Router is a Thread Network's connection to the outside world. A Border Router offers an off-mesh route for addressing packets. This allows a Thread Device connected to a Thread Network to communicate with an adjacent IPv6 network. In this way the Border Router facilitates device to device and device to cloud communication.

A Thread Border Router will also offer management and control functionality for a Thread Network as well as the ability to form a network. It is not necessary to start a Thread Network with a Border Router. But, since the Border Router offers a user interface and an avenue for secure Commissioning, a Border Router is the natural starting place for a user.

A Thread Border Router also offers a mechanism to discover the Thread Network. The Border Router does this Through mDNS advertisements. This is the mechanism through which a Thread Commissioning Application discovers a Thread Network.

About Commissioning

Commissioning is the act of joining an untrusted device into a Thread Network by securely authenticating the device and disseminating the network information.

All communication on a Thread Network is secured with ENC-MIC-32. However, communication off-mesh does not benefit from the same level of security and may be transported over unsecured links. This also means that a new, untrusted, Thread device must be securely given the keys to talk with other Thread devices on the network. Thread uses DTLS with EC-JPAKE to secure connections over untrusted links when adding devices into the Thread network.

On the off-mesh side, a Commissioner discovers a Thread Network through mDNS and creates a secure connection with the Border Agent. The pass-phrase for this DTLS connection is the Border Router's administrator password, setup when the Border Router was configured. The Commissioner uses this secure tunnel to send messages to the Border Agent. The Border Agent then relays the messages onto the Thread Network. In this fashion, the Commissioner petitions the Leader to become the Active Commissioner and add its prospective joiners to the commissioning dataset.

On the Thread side, a Joiner discovers the network by sending a Discovery Request broadcast on all possible channels. If the joiner is in the Active Commissioning Dataset a router for our network will respond with a Discovery Response message, this router is called the Joiner Router. Once the Joiner has discovered the Thread Network, it will begin a DTLS connection to the Active Commissioner using its PSK. This DTLS connection is proxied through the Joiner Router and Border Router if necessary. If this DTLS session is established, the Commissioner instructs the Joiner Router to securely give the Joiner the Thread Master Key.

After the commissioning process, the Joiner has been securely added to the network and can form links with other Thread devices on the network. Some important things to note; no messages were sent unencrypted, no hard coded keys were used, the Joiner's PSK was only on the Commissioner, and the network key was only sent between the Joiner Router and the Joiner with a one time link key.

About Interfaces

The Border Router is configured to bridge its available interfaces by default. This allows for a device on the Thread Network to natively communicate with adjacent IPv6 devices or to the cloud. By default the on-mesh prefix used by the Border Router is fd11:22::/64. This is in the ULA IPv6 prefix block (fc00::/7), specifically the Probabilistically Unique prefix (fd00::/8). These addresses should not be routed on the larger internet, and most wide area routers will refuse to forward traffic with these addresses as a source or destination. Keep this in mind when trying to connect with the Internet.

For this lab we will assume that you do not have an ISP that issues IPv6 addresses, or you do not wish to connect these devices to your network just yet. We will have the BeagleBone Black issue router advertisements on its Ethernet interface for the prefix fd11::33::/64 to allow other devices to configure ULAs routable to the Thread Network.

Task 1 – Setup the BeagleBone Black

Setup Debian

1. Download the Debian image from the BeagleBoard website.

   • For this guide the bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz image is used, however, any newer image should work just fine.

2. Unzip the image with tar or 7-Zip.

3. Write the image to your uSD Card using Etcher or Win32 Disk Imager. Consult the BeagleBoard Getting Started page for more information on updating the uSD Card image.

4. Connect the BeagleBone Black to your Wi-Fi router with an Ethernet Cable. Make sure to connect the BeagleBone Black to a LAN port, not the WAN port.

5. Insert the programmed uSD Card into the BeagleBone Black and boot the device.

   Booting from the uSD Card

   The BeagleBone Black is configured to attempt to boot from the AM335x internal storage. We want to boot from the uSD card instead. To force booting from the uSD card, hold the boot button when applying power to the BeagleBone Black.

   

6. Connect to the BeagleBone Black using SSH or through the UART port. The username for logging on is debian with the password temppwd.

   Connecting with SSH

   The BeagleBone Black will request to have the IP address 192.168.7.2. Depending on how your router is configured, the BeagleBone Black may show up on a different IP address, the most reliable way to find the BBB's location is to log-in to your router and look at the DHCP table.

   Once you have discovered the BeagleBone Black's IP address, use PuTTY to connect to the BBB over SSH. By selecting SSH and inputting the Host Name (or IP address) in the basic options.

   On connection your SSH client will prompt you to save the RSA key of the new server. PuTTY displays this as "WARNING - POTENTIAL SECURITY BREACH!". Accept the new RSA key.

   Don't forget to make sure that your computer is connected to the same Wi-Fi router as the BeagleBone Black.

   Connecting with Serial

   The BeagleBone Black has a UART header labeled J1. You can connect to this terminal with a USB-to-UART.

   

Expand the Image

The Debian image for the BeagleBone Black is most likely 3Gb large, this is not enough to build the border router source code. We will assume that you have an 8Gb or larger uSD Card for this guide.

sudo /opt/scripts/tools/grow_partition.sh

Reboot the BeagleBone Black to ensure the file-system has changed.

sudo shutdown -r now

This may close your SSH session, wait until the BeagleBone is back up to reconnect.

Clone the border router repository

The source-code for the border router is hosted on a Git repository.

Check your connectivity by using the command wget -O /dev/null https://github.com. The output of that command should have the phrase HTTP request sent, awaiting response... 200 OK, if it does not you may have to setup your proxies.

if true
then
    http_proxy=http://your_proxy.domain.com:80
    https_proxy=https://your_proxy.domain.com:80
    ftp_proxy=https://your_proxy.domain.com:80
    no_proxy=domain.com

    export http_proxy
    export https_proxy
    export ftp_proxy
    export no_proxy
fi

Defaults env_keep="http_proxy https_proxy ftp_proxy no_proxy"

Clone the OpenThread border router repository with git.

debian@beaglebone:~$ git clone https://github.com/openthread/ot-br-posix.git
Cloning into 'ot-br-posix'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (39/39), done.
remote: Total 5267 (delta 13), reused 25 (delta 6), pack-reused 5220
Receiving objects: 100% (5267/5267), 24.60 MiB | 1.86 MiB/s, done.
Resolving deltas: 100% (2380/2380), done.

   cd ot-br-posix
   git checkout 84b7b2fda3005a6b8eb83262884ecf78d2a82b21

Build the border router

These scripts will build and setup the border router on your BeagleBone Black. The following instructions will execute the commands within a script command. Wrapping the commands in a script call saves the output to a file, this is helpful if you want to look at the output later on. You can remove the script call if you don't care about the log.

The command script script.log -c 'bash ./script.sh' will save the output of the script script.sh to the file script.log. The equivalent command without saving the console output would be ./script.sh.

Bootstrap

This bootstrap script will download and install the necessary dependencies using apt and sets up the border router code to build.

Run the script/bootstrap script found in the border router repository.

debian@beaglebone:~$ cd ot-br-posix
debian@beaglebone:~/ot-br-posix$ script bootstrap.log -c 'bash ./script/bootstrap'

The bootstrap step downloads all the dependencies, checks the BeagleBone Black's environment, and builds the codebase. This step will take a fair amount of time.

Setup

This setup script will build and install the border router code on the BeagleBone Black.

Run the script/setup script found in the border router repository.

debian@beaglebone:~$ cd ot-br-posix
debian@beaglebone:~/ot-br-posix$ script setup.log -c 'bash INFRA_IF_NAME=eth0  ./script/setup'

The setup script builds all the necessary source files for your configuration, installs the libraries, and sets up the startup environment. This step will take some time.

Configure the border router

Now we have to configure otbr-agent to connect to the Radio Co-Processor (RCP) LaunchPad.

Add the following lines to /etc/default/otbr-agent and comment out any existing SocketPath configurations.

OTBR_AGENT_OPTS="-I wpan0 -B OTBR_INFRA_IF_NAME spinel+hdlc+uart:///dev/ttyACM0 trel://OTBR_INFRA_IF_NAME"

On the next boot, your BeagleBone Black will be setup to be a Border Router. Don't restart the BBB until you have setup and connected the Radio Co-Processor.

Task 2 – Setup the LaunchPads

This section will instruct you on how to build the RCP and Doorlock example projects, and how to flash them onto a LaunchPad. Read the READMEs that come with the examples to get more information on the specific examples.

The RCP example will be connected to the BeagleBone Black to serve as the border router's Thread interface. The Doorlock example will be commissioned onto the Thread Network.

Import The Projects

1. Open CCS with an empty workspace

2. Open the import dialog by going to Project → Import CCS Projects...

3. Select Browse... next to the Select search-directory: dialog and navigate to the examples directory in the SDK.

4. In Discovered projects: select rcp_<BOARD>_tirtos_<TOOL> and door_lock_<BOARD>_tirtos_<TOOL>, where <BOARD> and <TOOL> are the development board and toolchain you are using.

   • E.g. with a CC26x2R1 LaunchPad and using the TI-CGT toolchain the corresponding projects rcp_ftd_CC26X2R1_LAUNCHXL_tirtos_ccs and door_lock_CC26X2R1_LAUNCHXL_tirtos_ccs are used.

5. Click Finish to import the example projects and library projects.

Build and Program the LaunchPad

First we need to setup the Radio Co-Processor.

1. Select the RCP project in the project explorer on the left.

2. Build the project by clicking the hammer icon on the toolbar, or by selecting to Project → Build Project.

3. Connect a LaunchPad to your computer with a USB cable.

4. Start a debugging session with the RCP project by clicking the green bug icon on the toolbar, or by selecting Run → Debug.

   1. CCS may prompt you to update your emulator. Click the update dialog and watch the console to see if the update is successful. Close the dialog if the update is successful.

   2. CCS may prompt you to select a debugger by the serial number if you have multiple debuggers attached. Select one and remember which LaunchPad CCS programs.

5. Stop the debug session by clicking the red stop icon on the toolbar.

6. Unplug the LaunchPad from your computer.

7. Plug the LaunchPad into the BeagleBone Black with the USB cable.

The RCP is now setup to work with the BeagleBone Black as a border router. We will form a Thread network with this later.

Now we need to setup a Doorlock example to demonstrate the Thread Network.

1. Select the doorlock project in the project explorer on the left.

2. Build the project by clicking the hammer icon on the toolbar, or by selecting to Project → Build Project.

3. Connect the second LaunchPad to your computer with a USB cable.

4. Start a debugging session with the doorlock project by clicking the green bug icon on the toolbar, or by selecting Run → Debug.

   1. CCS may prompt you to update your emulator. Click the update dialog and watch the console to see if the update is successful. Close the dialog if the update is successful.

   2. CCS may prompt you to select a debugger by the serial number if you have multiple debuggers attached. Select one and remember which LaunchPad CCS programs.

5. Open a terminal emulator like PuTTY, Tera Term, or use CCS with Ctrl + Shift + Alt + T and select Serial Terminal.

   1. Discover the COM port for your LaunchPad with Device Manager.

   2. The default settings for this UART are; 115200 Baud, 8 Data bits, No Paraty, 1 Stop bit, and No Flow Control.

      

6. Continue the debug session by clicking the green play button on the toolbar.

You should see something like the following over the serial terminal:

TI Thread Doorlock
Press Enter for Help
<      HELP      >

Device Info: [EUI64] 0x00124b001ca76bd7  [PSKD] DRRLCK1
   Nwk Info: [Network Name] OpenThread  [ExtPanID] 0xdead00beef00cafe
   Nwk Info: [Masterkey] 0x00112233445566778899aabbccddeeff
   Nwk Info: [PAN ID] 0xffff  [Channel] 14  [Short Addr] 0xfffe
  Role Info: [Device Role] Disabled
  Conn Info: [Status] Disabled
   APP Info: [Doorlock State] unlock

If you have an LCD screen connected to your LaunchPad, you will see something like the following on-screen:

pskd:
DRRLCK1
EUI64:
0x00124b0013149681

This information will be useful when commissioning the doorlock into the Thread network later. The commissioner will need to know the EUI64 of the joining device and its PSK.

Task 3 – Start the Border Router

Make sure that the BeagleBone Black and the LaunchPad you programmed with the Radio Co-Processor firmware are connected like the image below:

Restart your BeagleBone Black to make sure that all configurations have taken effect.

The BeagleBone Black will host a web server that can be used to manage the border router. Log into the BeagleBone Black and use the command ifconfig to discover the IPv4 address of the eth0 interface. You could also log into your router to find the DHCP address table.

Navigate to the address of the BeagleBone Black with a web browser. The BeagleBone Black in my network is at address 192.168.2.3. You should see the following home screen:

Click on the Form button in the tray on the left.

Set the parameters of your new network. The defaults are fine to start a network.

Click the FORM button at the bottom of the page to start forming a Thread network.

Your Thread Network is now setup with the Radio Co-Processor as the Leader. If you have a sniffer running, you should see the network being formed.

Task 4 – Commission the Doorlock Example

Plug in the LaunchPad you programmed with the Doorlock example earlier.

In the BeagleBone Black SSH session, run these commands to start the Commissioner and add the Doorlock's EUI64 and PSKd. You should also see confirmations in the console after each command.

> commissioner joiner start
Commissioner: petitioning
Done
Commissioner: active
> commissioner joiner add 00124b001ca76bd7 DRRLCK1
Done
~ Discovery Request from 6223d6f8dabf5ee4: version=3,joiner=1
Commissioner: Joiner start fe071ccb21c2e6a9
Commissioner: Joiner connect fe071ccb21c2e6a9
Commissioner: Joiner finalize fe071ccb21c2e6a9
Commissioner: Joiner end fe071ccb21c2e6a9
Commissioner: Joiner remove fe071ccb21c2e6a9

Task 5 – Interact with the Doorlock example

Now that the Doorlock is joined to the network, you can interact in it the same way which is specified in the Doorlock example README. Specifically, you can start the coap client on the Border Router and get/post to the Doorlock.

For this setup, the IPv6 address of the Doorlock may be found with a ping command on the Border Router:

> ping ff03::1
16 bytes from fdde:ad00:beef:0:147e:a9e2:80c7:8add: icmp_seq=2 hlim=64 time=29ms
1 packets transmitted, 1 packets received. Round-trip min/avg/max = 29/29.0/29 ms.
Done

Then, the coap operations:

> coap start
Done
> coap get fdde:ad00:beef:0:147e:a9e2:80c7:8add /doorlock/lockstate
Done
> coap response from fdde:ad00:beef:0:147e:a9e2:80c7:8add with payload: 756e6c6f636b

In this case, the coap response is in ASCII hex, translating to "unlock"

You may also set the Doorlock with a coap post:

> coap post fdde:ad00:beef:0:147e:a9e2:80c7:8add /doorlock/lockstate con lock
Done
> coap response from fdde:ad00:beef:0:147e:a9e2:80c7:8add with payload: 6c6f636b

In this case, the coap response translates to "lock".

Further Reading

It is recommended that you read the Developing Thread Applications chapter of the TI-OpenThread User's Guide for more information on the software development environment.

Familiarize yourself with the OpenThread APIs.

Consider looking at the RFCs that define UDP (RFC 768) and CoAP (RFC 7959).

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.