Device tree overlays
Make your own custom device trees with Bela
Device tree overlays allow you to change the functions assigned to the pins on the BeagleBone and PocketBeagle boards. This page details how to get started using device tree overlays with Bela. (If you want to learn more about device tree overlays, we’ve found this page to be a particularly good starting point.)
In these examples, we are running commands on our Bela board via the command line. You can run commands on Bela’s command line by ssh‘ing into your Bela board, or by typing them into the console in the IDE.
Table of contents
Finding available device tree overlays
You can list the available overlays running on your Bela board with this command:
$ ls /lib/firmware
In the example below, we will use the overlay /lib/firmware/BB-UART4-00A0.dtbo. Note that you will not be able to load any arbitrary device tree overlay – some pins are used and “owned” by Bela as they are needed for the cape to work properly, and control of these pins is not available.
Make a backup of your environment
A partition called BELABOOT appears when you connect Bela to your computer, or put the Bela SD card in your SD card reader. Before starting, save a copy of the file uEnv.txt in BELABOOT on your computer in case something goes wrong. (An error in this file may prevent your board from booting.)
Loading a device tree overlay
To load a device tree overlay on Bela, we must first know which version of the Bela image is running on the board.
Find the current version using this command on Bela’s command line:
$ grep "Bela image" /etc/motd
Image v0.3.4 or above
Open the file uEnv.txt that is in the BELABOOT partition (not the backup copy).
To do this, use this command in your laptop’s terminal:
$ nano /Volumes/BELABOOT/uEnv.txt
Add the following line to the uEnv.txt file:
uboot_overlay_addr2=/lib/firmware/BB-BELA-B2.dtbo
The number X in uboot_overlay_addrX determines in what order the overlays are loaded.
Note that you can add more overlays by adding more lines with a different addrX number, such as:
uboot_overlay_addr3=/lib/firmware/BB-UART4-00A0.dtbo
Exit Nano using Ctrl + X and press Y to save your changes. Eject the device safely, and reboot.
Image v0.3.3 or earlier
On earlier Bela images, you will need to run the following command in a terminal to load the overlay at runtime:
$ echo BB-UART4 > $SLOTS
Note that we are not using the full path to the overlay file, but only the filename without the last 10 characters (-XXXX.dtbo). Though this method works on Bela, it doesn’t work on Bela Mini.
The variable $SLOTS is defined in /root/.bashrc, and references/sys/devices/platform/bone_capemgr/slots for images starting from v0.3.0, or /sys/devices/bone_capemgr.?/slots for earlier images.
config-pin
config-pin is a utility available since Bela v0.3.0 that sets the function of individual pins at runtime.
This is useful for running a pin as a GPIO, as opposed to toggling multiple pins at once or enabling a peripheral. It can also be used as a full replacement for a device tree overlay, although you will have to configure each pin individually.
On Bela Mini, config-pin works out of the box. On Bela, you have to load the /lib/firmware/cape-universalh-00A0.dtbo overlay (using one of the techniques above) first and you also need an updated BB-BELA-00A0.dtbo, as generated by this branch.
With config-pin, you can set the function of a single pin with a command on Bela’s command line:
$ config-pin P2.17 gpio
You can find out more about how to use config-pin by running config-pin --help.
Here is an example on how to use config-pin to apply some settings at startup: https://gist.github.com/pdp7/d4770a6ba17e666848796bf5cfd0caee