-
Notifications
You must be signed in to change notification settings - Fork 139
Load a device tree overlay
This material has been superseded. Visit learn.bela.io for the maintained version.
Device tree overlays allow to change the functions assigned to the pins on the BeagleBone and PocketBeagle and enable the corresponding peripheral. Plenty of documentation is available elsewhere on what they are and how they work (e.g.: this is a good starting point). This document is an introduction on how to use them with Bela.
You can list the available overlays running on the board:
ls /lib/firmware
in the examples below, we want to load 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.
To load a device tree overlay on Bela, you have to first find out what image you are on. To find out the current image, run
grep "Bela image" /etc/motd
in a terminal on the board, or in the console at the bottom of the IDE.
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 next to them, with a different addrX number, e.g.:
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.
On earlier images, you have to run the following from a terminal to load the overlay at runtime:
echo BB-UART4 > $SLOTS
note that in this case we are not using the full path to the overlay file, but only the filename without the last 10 characters (-XXXX.dtbo). This method also works on any Bela board (not BelaMini).
The variable $SLOTS is defined in /root/.bashrc, and it evaluates to /sys/devices/platform/bone_capemgr/slots for images starting from v0.3.0, or /sys/devices/bone_capemgr.?/slots for earlier images.
config-pin is a utility (available starting from Bela image v0.3.0) to set the function of individual pins at runtime. This is particularly useful when you simply want to use a pin as a GPIO, as opposed to toggling multiple pins at once or enabling a peripheral, but it can also be used as a full replacement for a device tree overlay, although you will have to configure each pin individually. On BelaMini, you can use config-pin out of the box. On Bela, you have to load the /lib/firmware/cape-universala-00A0.dtbo overlay (using one of the techniques above) first in order for config-pin to work.
With config-pin, you can easily set the function of a pin, e.g.:
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