Device Tree Overlays


I like to develop a new cape for Beaglebone Black and tried to create a Device Tree Overlay for it.

I found a table for the pin definitions. A part of the table is this:

Head_pin $PINS ADDR/OFFSET Name GPIO NO. Mode7

P9_11 28 0x870/070 UART4_RXD 30 gpio0[30]

P9_12 30 0x878/078 GPIO1_28 60 gpio1[28]

P9_13 29 0x874/074 UART4_TXD 31 gpio0[31]

P9_14 18 0x848/048 EHRPWM1A 50 gpio1[18]

P9_15 16 0x840/040 GPIO1_16 48 gpio1[16]

With this information I created the following device tree overlay:


  • This is a template-generated file from BoneScript


compatible = “ti,beaglebone”, “ti,beaglebone-black”;
part_number = “test”;

exclusive-use =
“P9.11”, /* gpio0.30, Pin 30 /
“P9.13”, /
gpio0.31, Pin 31 */

fragment@0 {
target = <&am33xx_pinmux>;
overlay {
foo_pins: foo_pins {
pinctrl-single,pins = <
0x078 0x3F
0x07c 0x3F


fragment@1 {
target = <&pruss>;
overlay {
status = “okay”;
pinctrl-names = “default”;
pinctrl-0 = <&foo_pins>;

To my surprise I had to use the GPIO Numbers 30 and 31 together with the offsets 0x078 and 0x07c to make the GPIO pins P9_11 and P9_13 work as inputs with pullups.
I would have expected, that I have to use the software pins 28 and 29 for the inputs P9_11 and P9_13.

But it would be ok, if it would work for all unused pins of the Beaglebone Black. The problem is, that it doesn´t work for many pins. For example when I try to use the input P9_15 with the GPIO number 48 and the corresponding offset: 48 * 4 = 192 = 0x0c0 the whole overlay does not load correctly. I think this is because $PIN 48 corresponds to P8_37 in the list which is used as a HDMI pin.

Why do I have to use GPIO NO instead of $PIN as I expected?
If I have to use GPIO NO instead of $PIN, then why does this work only for some pins and not for all?

Any help is appreciated. I am running out of ideas!


Derek Molloy has an excellent step by step video.

Just google his name + device tree overlay

Hello Andy,

I recommend to check out libpruio. Using this library you can configure and control GPIOs without device tree overlays. Board pins (ie. HDMI or EMC) are locked by default, so you won’t change things unintentionally. The library also helps to do fast pin control (input and output) and offers some ADC features.

The time to write your device tree overlay is at the end of the software development phase. The overlay only locks the pins used.