Cape manager is back baby!

cape manager
For BeagleBone Black the cape manager has been missing or somewhat broken since 3-odd-8 or something, but with Linux kernel 4.1, it's back in business (a part of mainline kernel)! That means you no longer have to recompile the whole device tree in order to enable or disable an IP core slash peripheral, instead you can simply compile the overlay and fix the device tree in the running kernel. This simplifies development and there are also some good tools and a repo for pushing these changes out.

What it does
Without cape manager, you basically have one single device tree blog that is loaded when the kernel starts. If you want to change which peripherals are enabled, you need to recompile the device and reboot. With cape manager, you can choose to change parts of the device tree in a running kernel. This enables loading cape-specific overlays based on the cape that is attached (read from the EEPROM of the cape) or via command line to enable a specific peripheral or mux the pins to a specific function. This is what the Adafruit BBIO library does behind the scenes.

Get started with cape manager
Start with a fresh Debian distro. The official Debain image form March should do.
Install the newest kernel:

apt-cache search linux-image

Pick one of the latest, for instance "linux-image-4.1.1-bone10":

apt-get install linux-image-4.1.1-bone10

Clone the device tree overlay repository:

cd /usr/src
git clone

Follow the instructions on how to use upgrade and use the cape manager from there. The instructions are good, basically:
- Upgrade the DTC
- compile the overlays.

Tools for checking your work
The cape manager is now located in a more static location in the sys fs than before. The new location is:

cat /sys/devices/platform/bone_capemgr/slots

To see which capes are loaded, cat it.
If you are working on pin-muxing there are a couple of files that can be useful to cat:

cat /sys/kernel/debug/pinctrl/44e10800.pinmux/pins

This file will give you the pin number, the adress of the pin in physical memory and to which function it has been muxed (1 to 7). It will also tell you if it is set up as input/output in the case of GPIO (function 7) and if it has pull-up or pull-down.
Another useful sysfs file is this:

cat /sys/kernel/debug/pinctrl/44e10800.pinmux/pingroups

This can be used to check that a pin has been claimed in the overlay. Very useful for making sure that the groups you add to the am33xx_pinmux node are actually set up as you want them to be.

Helpful #define files
A while back I posted a table with the mapping from the headers exposing the different pins on the BeagleBone to the physical address of the pins. For a while now there has been a header file defining this mapping and providing user friendly names that can be used for pin muxing. By adding the following includes to the header of your device tree overlay source files, you can use the pin names from the exposed headers verbatim:

#include <dt-bindings/board/am335x-bbw-bbb-base.h>
#include <dt-bindings/pinctrl/am33xx.h>

Instead of writing

    dallas_w1_pins: pinmux_dallas_w1_pins {
        pinctrl-single,pins = < 0x150 0x37 // Dallas 1W >;

You can now write

    dallas_w1_pins: pinmux_dallas_w1_pins {
        pinctrl-single,pins = < BONE_P9_22 (INPUT_EN | PIN_PULLUP | MUX_MODE7) >;

so this saves you from having to look up the pins in a table.

caveats in porting old overlays
A while back I ported the patches for the cape manager to a kernel 3.12 for use in an Angstrom based distro. If you want to port an old cape from the kernel 3.8 era, you will notice that there are a couple of changes. Most importantly that the GPIO banks used to go from 1 to 4, but now go from 0 to 3. Also, the UARTs/serials go from 0 to 6 to match /dev/ttyO* in the file system. You can see this by peeking into the am33xx.dtsi (device tree source inclue file) in the mainline kernel repository:

Elias Bakken

  • Corrado

    I'm trying to use cape manager on ubuntu 14.04.
    I succeeded with kernel 3.8 but now I'm facing a lot of difficulties with 4.1.
    although I'm able to compile the dts sourse with dtc command and I can echo without problems into /sys/devices/platform...........slots the dtbo file i created, my program is not working, it cannot comunicate with i2cbus or spi interface.
    In 3.8 version I had to disable HDMI cape but here I cannot even see it (maybe I have to disable it some other way).
    However I would kindly ask you for some help as my dts files were working fine with 3.8 version, now I need to update the system version to support a particular wifi dongle that I have here, but as I update to 4.1, I cannot use my dtbo files, (devices in /dev are created but I cannot read or write correctly to them).
    Thanks in advance!

  • Corrado

    I just wanted to add that with 3.8 kernel version my program is working fine too :)

  • Daniel

    Awesome news!

  • Rick Mann

    Great! Now, how to get the PRU uio devices to show up?

    1. bo911

      As I tried out, I came back to statically activate the PRU's and their pru - pins in fast mode via devicetree, so then
      the uio_pruss are automatically loaded.

  • sophana

    I'm new to beaglebone.
    This so complicated!

    I'm just trying to use uart1 and uart2 and test them loopback
    I installed the overlays

    root@beaglebone:~# echo 'BB-UART1' > /sys/devices/platform/bone_capemgr/slots
    root@beaglebone:~# dmesg | tail
    [ 29.341789] using random host ethernet address
    [ 29.341881] g_ether gadget: Ethernet Gadget, version: Memorial Day 2008
    [ 29.341895] g_ether gadget: g_ether ready
    [ 32.470276] IPv6: ADDRCONF(NETDEV_UP): usb0: link is not ready
    [ 32.716356] random: nonblocking pool is initialized
    [ 51.070305] bone_capemgr bone_capemgr: part_number 'BB-UART1', version 'N/A'
    [ 51.070345] bone_capemgr bone_capemgr: slot #4: override
    [ 51.070363] bone_capemgr bone_capemgr: Using override eeprom data at slot 4
    [ 51.070381] bone_capemgr bone_capemgr: slot #4: 'Override Board Name,00A0,Override Manuf,BB-UART1'
    [ 51.073083] bone_capemgr bone_capemgr: slot #4: dtbo 'BB-UART1-00A0.dtbo' loaded; overlay id #0

    root@beaglebone:~# cat /sys/devices/platform/bone_capemgr/slots
    0: PF---- -1
    1: PF---- -1
    2: PF---- -1
    3: PF---- -1
    4: P-O-L- 0 Override Board Name,00A0,Override Manuf,BB-UART1

    root@beaglebone:~# grep uart /sys/kernel/debug/pinctrl/44e10800.pinmux/pingroups
    group: pinmux_uart0_pins
    root@beaglebone:~# grep 980 /sys/kernel/debug/pinctrl/44e10800.pinmux/pins
    pin 96 (44e10980.0) 00000037 pinctrl-single

    uart pins seem not muxed correctly. minicom do work, but nothing transmited through the uarts.


  • sophana

    I finaly found.
    It was a bug in kernel 4.1.17-ti-rt-r44
    upgrading go 4.1.17-ti-rt-r46 fixed the problem!

    1. TamusJRoyce

      /media/BEAGLEBONE/env.txt and /boot/uBoot/uEnv.txt has moved to /etc/default/capemgr (file which may not exist). It also has a new syntax. Add "CAPE=BB-SPI-01,BB-UART1,BB-UART2,BB-UART4" to get main ports working. Then reboot.

      This did it for me. Per and

      1. Ali

        It works for me thanks

  • BeagleBone Black GPIO Benchmark – Code and Life

    […] came with Debian Jessie, it took a while to realize the “bonemanager” directory had moved to a new place. After this, I was able to use Derek Molloy’s very helpful, but still quite complex 45 minute […]

  • Riko

    I tried to change mux on port pin. The overlay is loaded. But the pin mux is not changing. It s Linux 4.4. Is there a bug? Thx

Leave a Reply

Your email address will not be published. Required fields are marked *