OpenThread Border Router Build and Configuration

This guide covers the basic build and configuration of OpenThread Border Router (OTBR). Upon completion of this procedure, you will have an OTBR that functions as a Full Thread Device (FTD) in an NCP design.

Configure Platform

Configure a supported hardware platform:

• BeagleBone Black
• Raspberry Pi 3B

Build and flash NCP

OTBR runs on an NCP design. Select a supported OpenThread platform to use as an NCP, and follow the building and flashing instructions for that platform, using these configuration flags and/or build switches:

For example, to build the CC2538 example platform for use as a Border Router with Commissioning capabilities:

make -f examples/Makefile-cc2538 BORDER_AGENT=1 BORDER_ROUTER=1 COMMISSIONER=1 UDP_FORWARD=1

For an overview of building OpenThread, see the Building Guide.

Specific instructions on building supported platforms with GNU Autotools can be found in each example's platform folder.

Set up the Border Router

OTBR communicates with the NCP via wpantund. On the configured hardware platform:

1. Clone the OTBR repository:

   git clone https://github.com/openthread/borderrouter

2. Install dependencies:

   cd borderrouter
   ./script/bootstrap

3. Compile and install OTBR and wpantund. Note that this setup script uses Network Manager to automatically set up the Wi-Fi access point (AP).
   1. To automatically set up the Wi-Fi AP using Network Manager:

      ./script/setup

   2. To skip the automatic Wi-Fi AP setup and manually do it later without using Network Manager:

      ./script/setup NETWORK_MANAGER=0

4. Attach the flashed NCP device to the Border Router platform via USB.
5. Configure the NCP device's serial port in wpantund:
   1. Determine the serial port name for the NCP device by checking /dev:

      ls /dev/tty*

   2. Add this to /etc/wpantund.conf. For example, for a serial port name of ttyUSB0:

      Config:NCP:SocketPath "/dev/ttyUSB0"

6. Power cycle the Border Router. If using the BeagleBone Black platform, remember to hold down the BOOT button while doing so.
7. The OTBR service should start on boot.

Verify services

Verify that all required services are enabled:

sudo systemctl status

If the setup script was successful, the following services appear in the output:

• avahi-daemon.service
• otbr-agent.service
• otbr-web.service
• wpantund.service

For example:

● raspberrypi
    State: running
     Jobs: 0 queued
   Failed: 0 units
    Since: Thu 1970-01-01 00:00:01 UTC; 47 years 7 months ago
   CGroup: /
           ├─user.slice
           │ └─user-1000.slice
           │   ├─user@1000.service
           │   │ └─init.scope
           │   │   ├─576 /lib/systemd/systemd --user
           │   │   └─580 (sd-pam)
           │   └─session-c1.scope
           │     ├─480 /bin/login --
           │     └─585 -bash
           ├─init.scope
           │ └─1 /sbin/init
           └─system.slice
             ├─systemd-timesyncd.service
             │ └─334 /lib/systemd/systemd-timesyncd
             ├─wpantund.service
             │ └─471 /usr/sbin/wpantund
             ├─dbus.service
             │ └─339 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation
             ├─hciuart.service
             │ └─442 /usr/bin/hciattach /dev/serial1 bcm43xx 921600 noflow -
             ├─ssh.service
             │ └─621 /usr/sbin/sshd -D
             ├─avahi-daemon.service
             │ ├─341 avahi-daemon: running [raspberrypi.local]
             │ └─361 avahi-daemon: chroot helper
             ├─otbr-web.service
             │ └─472 /usr/sbin/otbr-web
             ├─triggerhappy.service
             │ └─354 /usr/sbin/thd --triggers /etc/triggerhappy/triggers.d/ --socket /run/thd.socket --user nobody --deviceglob /dev/input/event*
             ├─systemd-logind.service
             │ └─353 /lib/systemd/systemd-logind
             ├─otbr-agent.service
             │ └─501 /usr/sbin/otbr-agent -I wpan0
             ├─cron.service
             │ └─350 /usr/sbin/cron -f
             ├─systemd-udevd.service
             │ └─154 /lib/systemd/systemd-udevd
             ├─rsyslog.service
             │ └─345 /usr/sbin/rsyslogd -n
             ├─bluetooth.service
             │ └─445 /usr/lib/bluetooth/bluetoothd
             ├─systemd-journald.service
             │ └─136 /lib/systemd/systemd-journald
             └─dhcpcd.service
               ├─409 wpa_supplicant -B -c/etc/wpa_supplicant/wpa_supplicant.conf -iwlan0
               └─466 /sbin/dhcpcd -q -w

If those services are running, but the RPi3B is in a degraded state, some other service has failed to start. Check to see which:

sudo systemctl --failed

If the automatic Wi-Fi AP setup was skipped and the failed service is tayga or dnsmasq, this is normal. If performing a manual setup of the Wi-Fi AP, these services are completely configured as part of the Wi-Fi Access Point Setup covered in the next section.

Verify NCP

Verify that the NCP is in the correct state:

sudo wpanctl status

wpanctl is a command line utility provided with wpantund. It is used to communicate with the wireless PAN interface (default is wpan0) that wpantund is bound to in the NCP design.

If the NCP is successfully running OpenThread and is not a member of a Thread network, the output should be similar to the below:

wpan0 => [
        "NCP:State" => "offline"
        "Daemon:Enabled" => true
        "NCP:Version" => "OPENTHREAD/g4ccc23a5-dirty; NRF52840; Sep 22 2017 10:44:07"
        "Daemon:Version" => "0.08.00d (/033c369; Sep 20 2017 21:06:17)"
        "Config:NCP:DriverName" => "spinel"
        "NCP:HardwareAddress" => [F872DF9CD5AE4DCE]
]

If the NCP:State is uninitialized, troubleshoot with the following:

1. Verify the Border Router has sufficient power (use the proper external AC adapter).
2. Disconnect and reconnect the NCP board to the Border Router platform.
3. Verify that the NCP serial device is present. For example, if the device should be attached to /dev/ttyUSB0:

   ls /dev/ttyUSB*
   /dev/ttyUSB0

4. Reset the NCP with sudo wpanctl reset.

Check the NCP status again with sudo wpanctl status.