Google is committed to advancing racial equity for Black communities. See how.

BeagleBone Black

View source on GitHub

OpenThread Border Router (OTBR) provides support for the BeagleBone Black (BBB) platform.

Hardware requirements:

  • External 5V AC adapter for power
  • An 8 GB or larger microSD card ("uSD card" in this guide)
  • A supported OpenThread platform (such as the TI CC2652) for Thread network connectivity in an RCP design

Steps to enable:

  1. Download and install the OS.
  2. Prepare the Debian Environment for OTBR
  3. Build and install OTBR
  4. Set up a Wi-Fi access point

Download and install the OS

  1. Download the latest Debian IoT image for BeagleBone.
    • The version used for this guide was bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz
  2. Install the OS image on a uSD Card by following the BeagleBone getting started guide.
  3. Boot the BeagleBone and SSH into the device.
    • Connectivity over a local Ethernet based network is recommended.
    • The cloud9 IDE will be disabled later in this guide.
    • This guide will change the state of BeagleBone network interfaces, be aware your secure shell session may disconnect.
    • Modern BeagleBone bootloaders will run from the uSD card by default, but some BeagleBone Black devices may try to boot from the internal eMMC. Make sure to press the BOOT Button in this case.

For more detailed information on the BeagleBone, see the BeagleBoard Support Page.

Prepare the Debian Environment for OTBR

Certain parts of the default BeagleBone Debian image run by default. These may conflict with some parts of the OpenThread Border Router software.

Some packages are running by default on the BeagleBone to enable quick development. These can be found in systemd with the command sudo systemctl list-units --all and sudo systemctl list-sockets --all.

Stop and disable the modules:

sudo systemctl stop bonescript-autorun.service
sudo systemctl stop bonescript.socket
sudo systemctl stop bonescript.service
sudo systemctl stop cloud9.socket
sudo systemctl stop cloud9.service
sudo systemctl stop nodered.service
sudo systemctl disable bonescript-autorun.service
sudo systemctl disable bonescript.socket
sudo systemctl disable bonescript.service
sudo systemctl disable cloud9.socket
sudo systemctl disable cloud9.service
sudo systemctl disable nodered.service
sudo systemctl daemon-reload

Disable advertising the Cloud9 IDE and NodeRED services with Avahi by deleting the service files:

sudo rm /etc/avahi/services/*

The filesystem for the uSD BeagleBone image is limited to 4GB to fit on most uSD cards. Expand the partition to enable usage of the entire storage capacity.

sudo /opt/scripts/tools/grow_partition.sh

You are encouraged to read that helper script to find out how the filesystem is expanded. You will have to reboot the BeagleBone and re-login to use this new filesystem definition.

sudo shutdown -r now

This will close your SSH session.

Once logged back into the BeagleBone, install Network Manager:

sudo apt-get update
sudo apt-get install network-manager

Then disable connman and enable network-manager:

sudo systemctl disable connman
sudo systemctl enable network-manager

If we were to stop connman directly here it would break the SSH session because the network interface is managed by connman. Instead we configure the system to take effect on the next boot. Now reboot the Beaglebone and re-login.

sudo shutdown -r now

Network Manager may not have setup the DNS name servers. Edit resolv.conf with the command sudo vim /etc/resolv.conf and make sure the contents contain the Google DNS and Cloudflare DNS:

nameserver 8.8.8.8
nameserver 1.1.1.1

Restart to make sure Network Manager is setup correctly.

sudo shutdown -r now

The WiLink 8 module does not like to have its MAC address changed at runtime. Network Manager will try to do this when scanning. Edit the NetworkManager.conf with the command sudo vim /etc/NetworkManager/NetworkManager.conf and add the lines below:

[device]
wifi.scan-rand-mac-address=no

The BBONE-GATEWAY-CAPE is not recognized by the BeagleBone by default because of a pin conflict. Add the configuration manually by editing the uEnv.txt with the command sudo vim /boot/uEnv.txt and make sure the following lines match:

#Custom Cape
dtb_overlay=/lib/firmware/BB-GATEWAY-WL1837-00A0.dtbo
#
#Disable auto loading of virtual capes (emmc/video/wireless/adc)
disable_uboot_overlay_emmc=1
disable_uboot_overlay_video=1
disable_uboot_overlay_audio=1
disable_uboot_overlay_wireless=1
disable_uboot_overlay_adc=1

The BeagleBone wilink setup scripts try to use connman by default to enable Wi-Fi AP activity. Edit the default configuration folder with the command sudo vim /etc/default/bb-wl18xx and make sure the variables match below:

TETHER_ENABLED=no
USE_CONNMAN_TETHER=no

Restart to make sure Network Manager can see the new interface.

sudo shutdown -r now

Once logged back in you can run ifconfig or nmcli to see the new wlan interface.

Build and install OTBR

See Build and Configuration for instructions on building and installing OTBR.

Set up a Wi-Fi access point

If your BeagleBone is Wi-Fi enabled and automatic setup of the Wi-Fi access point by Network Manager is skipped, see Wi-Fi Access Point Setup for manual configuration instructions. The guide is written for Raspberry Pi, but most of the configuration steps are applicable to the BeagleBone Debian distribution.