OpenThread Border Router Build and Configuration

View source on GitHub

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 RCP design.

Configure Platform

Configure a supported hardware platform:

Build and flash RCP

OTBR runs on an RCP design. Select a supported OpenThread platform to use as an RCP and follow the building and flashing instructions for that platform.

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.

Install OTBR

OTBR communicates with the RCP via spinel. To install OTBR on the configured hardware platform, complete the following steps.

Clone the OTBR repository:

git clone https://github.com/openthread/ot-br-posix

Install dependencies

The default configuration enables BORDER_ROUTING for most platforms. For a complete list of OTBR default flags, refer to platform examples on GitHub. Select your platform, then click default, if available.

  • Default usage:

    cd ot-br-posix
    ./script/bootstrap
    
  • BeagleBone Black with Network Manager (optional):

    cd ot-br-posix
    NETWORK_MANAGER=1 NETWORK_MANAGER_WIFI=1 ./script/bootstrap
    

Compile and install OTBR

  • Default usage. The setup script enables Border Routing by default. To enable Border Routing, specify your platform's Ethernet or Wi-Fi interface:

    Use Ethernet:

    INFRA_IF_NAME=eth0 ./script/setup
    

    Use Wi-Fi:

    INFRA_IF_NAME=wlan0 ./script/setup
    
  • BeagleBone Black. Use Network Manager (optional):

    NETWORK_MANAGER=1 NETWORK_MANAGER_WIFI=1 ./script/setup
    

Attach and configure RCP device

Attach the flashed RCP device to the Border Router platform via USB.

To configure the RCP device's serial port in otbr-agent, first, determine the serial port name for the RCP device by checking /dev:

ls /dev/tty*

Next, check your otbr-agent settings.

cd /etc/default
cat otbr-agent

The otbr-agent configuration file contains your Thread interface name, Ethernet or Wi-Fi interface name, and RCP serial port name.

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

Not all devices attach with the same serial port name. The most common port names are ttyACM* and ttyUSB*. Refer to the documentation for your device to determine the expected serial port name.

If required, update the otbr-agent configuration file. For example, for a Wi-Fi interface and a serial port name of ttyUSB0:

OTBR_AGENT_OPTS="-I wpan0 -B wlan0 spinel+hdlc+uart:///dev/ttyUSB0 trel://wlan0"

To update an Ethernet interface:

OTBR_AGENT_OPTS="-I wpan0 -B eth0 spinel+hdlc+uart:///dev/ttyUSB0 trel://eth0"

Power cycle the Border Router. If using the BeagleBone Black platform, remember to hold down the BOOT button while doing so.

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:

  • mdns.service
  • otbr-agent.service
  • otbr-web.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
             ├─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
  # enabled  ├─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
  # enabled  ├─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
  # enabled  ├─mdns.service
             │ └─725 /usr/sbin/mdnsd
             ├─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 RPi is in a degraded state, some other service has failed to start. Check to see which:

sudo systemctl --failed

You can also check each service individually:

sudo service mdns status
sudo service otbr-agent status
sudo service otbr-web status

otbr-web is enabled by default for most platforms. If otbr-web is not installed, try passing the WEB_GUI flag:

WEB_GUI=1 ./script/bootstrap
INFRA_IF_NAME=wlan0 WEB_GUI=1 ./script/setup

Verify RCP

Verify that the RCP is in the correct state:

sudo ot-ctl state

ot-ctl is a command line utility provided with OTBR. It is used to communicate with the Thread PAN interface (default is wpan0) that otbr-agent is bound to in the RCP design.

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

disabled

If the output is OpenThread daemon is not running, troubleshoot with the following:

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

    ls /dev/ttyUSB*
    /dev/ttyUSB0
    
  4. Reset the RCP with sudo ot-ctl reset.

Check the RCP status again with sudo ot-ctl state.