Search

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, PocketBeagle and PocketBeagle 2 boards. This page details how to get started using device tree overlays with Bela.

Table of contents

  1. On Bela Gem and PocketBeagle 2
    1. Make a backup of your environment
    2. Finding available device tree overlays
    3. Loading a device tree overlay
  2. On legacy Bela boards
    1. Finding available device tree overlays
    2. Make a backup of your environment
    3. Loading a device tree overlay
      1. Image v0.3.4 or above
      2. Image v0.3.3 or earlier
    4. config-pin

On Bela Gem and PocketBeagle 2

Make a backup of your environment

The /boot/firmware folder on Gem is a mountpoint for /dev/mmcblk1p1, a FAT32 partition on your SD card. For modifying which device tree overlays are loaded, we will be editing the file /boot/firmware/extlinux/extlinux.conf and it is appropriate to make a backup copy of it first. Make the copy in the same folder, so if things go wrong and the board cannot boot, you can insert the SD card on the host and access both the modified and backup file: To make the copy, do:

cp /boot/firmware/extlinux/extlinux.conf /boot/firmware/extlinux/extlinux.conf.bak

Finding available device tree overlays

You can list the available overlays running on your Bela Gem board with this command:

$ ls /boot/firmware/overlays/PB2*

Unfortunately, you won’t see many entries, possibly just PB2-BELA.dtbo, the base overlay for making the Gem capes work on the PB2. This is because the ecosystem of device tree overlays for the PB2 is still very limited. So, you most likely have to write your own device tree overlay. To do so, go to /opt/source/dtb-6.12-Beagle, make copy an existing device tree overlay that you will use as a template and start editing. For instance, if you want to create an overlay for using UART4 on P1.20(Rx) and P2.20(Tx), you’d do:

cd /opt/source/dtb-6.12-Beagle
cp src/arm64/overlays/PB2-BELA.dtso src/arm64/overlays/PB2-UART4.dtso

Then you should edit the file to make it behave as desired. To build and test the file, you can simply run make from the dtb-6.12-Beagle folder. The dtc device tree compiler’s build error are not very informative, so it may require quite a bit of trial and error to get things to work. Once you have something that builds, you can verify that there are not missing symbols once it’s applied on top of the base device tree with:

make && fdtoverlay -vvv -o /dev/null -i /boot/firmware/ti/k3-am6232-pocketbeagle2.dtb /opt/source/dtb-6.12-Beagle/src/arm64/overlays/PB2-BELA.dtbo && echo OK || echo "ERROR: missing symbols"

Once you have a file that you want to test, run ./build_n_install.sh which will build it into a file called PB2-UART4.dtbo and install it in the /boot/firmware/overlays folder.

Loading a device tree overlay

Device tree overlays are loaded at boot following the directives in /boot/firmware/extlinux/extlinux.conf. Once you’ve made a backup of the file as explained above, open this file in a text editor. Find the section that starts with

label microSD (default)

whose content should look like this:

    kernel /Image.gz
    append console=ttyS2,115200n8 earlycon=ns16550a,mmio32,0x02860000 root=/dev/mmcblk1p3 ro rootfstype=ext4 fsck.repair=yes resume=/dev/mmcblk1p2 rootwait net.ifnames=0
    fdtdir /
    fdtoverlays /overlays/PB2-BELA.dtbo /overlays/PB2-I2C-GPIO.dtbo
    #initrd /initrd.img

Here, append to the fdtoverlays line your overlay, nothing that this is the path from within /boot/firmware/. If you’ve followed the procedure above, your overlay will be in /boot/firmware/overlays/PB2-UART4.dtbo and here you should write in /overlays/PB2-UART4.dtbo. For more context on the operation of this file, see the BeagleBoard documentation. Save the file and reboot.

If you have a UART adapter (e.g.: the Raspberry Pi Debug Probe SC0889, or a cable adapter to your favourite UART adapter) connected to the PB2’s UART port, you can monitor u-boot’s output during boot to see if the overlay is successfully found and loaded. Once Linux is booted, you won’t be able to see whether the overlay was loaded, but you should be able to determine that by observing its effects, e.g.:

  • did you change pinmux values? They should show up in the files pointed to by the $PINS variable
  • did you enable a device? It should show up in /dev/ and possibly elsewhere.

On legacy Bela boards

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 (or in the console at the bottom of the IDE):

$ grep "Bela image" /etc/motd

Image v0.3.4 or above

When you connect the board to your computer, or when you put the SD card in an SD card reader, a partition called BELABOOT will show up in your disk devices. Make a local backup copy of the file uEnv.txt from that partition to use in case something goes wrong: an error in this file may prevent your board from booting.

Now that you have made a backup, open uEnv.txt from the BELABOOT partition in a text editor: there are these two lines there

uboot_overlay_addr2=/lib/firmware/BB-BELA-00A0.dtbo
uboot_overlay_addr3=/lib/firmware/BB-BELA-CTAG-SPI-00A0.dtbo

you can add more overlays by adding more lines after these, with a different addrX number. To load the overlay we previously identified, add:

uboot_overlay_addr4=/lib/firmware/BB-UART4-00A0.dtbo

The number X in uboot_overlay_addrX determines in what order the overlays are loaded.

Save the file and remember to eject the storage device safely, then gracefully reboot Bela and it should work.

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 or in the console at the bottom of the Bela IDE:

$ 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