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:
- Verify the Border Router has sufficient power (use the proper external AC adapter).
- Disconnect and reconnect the RCP board to the Border Router platform.
Verify that the RCP serial device is present. For example, if the device should be attached to
/dev/ttyUSB0
:ls /dev/ttyUSB*
/dev/ttyUSB0Reset the RCP with
sudo ot-ctl reset
.
Check the RCP status again with sudo ot-ctl state
.