the correct way to enable spi ports on the beaglebone black

One of the most important benefits of retirement is the time you have to do what you want to do. While working, I had to divide my time between work (which included commuting), then my obligatory civic responsibilities, followed by my obligatory home chores. Whatever was left I could devote to some personal project. With retirement, that’s been pretty much flipped 180 degrees. I have more time for civic and home chores, and considerable time to devote to projects, or considerable compared to when I had to work for a living.

With all that extra “spare” time I turned my attention to some of the single-board computers I’d been collecting over the past five years. Some of them only got a cursory examination before they were put on the shelf “for some time later.” In the case of the BeagleBoard Rev C, I purchased it August 2014 and wrote about the purchase here ( That was the last I wrote about the BBB at all until today. Before I put it away I briefly powered it up and logged into the Debian default account using the Cloud 9 IDE bundled with the BBB just to make sure it worked.

What’s Good

Let’s get this part out of the way first. The best part of Beagle Bone IMHO is the web-based Cloud 9 IDE built-in service that allows the developer/maker (I hate the ‘maker’ adjective) to begin to work immediately with the BBB. This post’s lead media image shows the latest version of this tool. It follows a classic IDE layout; a long gutter on the left showing work area and files, a top source editor, and a bottom section containing tabbed areas for logging and running one or more shells.

It’s the ability to run a shell in a web page that always impresses me. I’ve seen the same thing with Cockpit running on CentOS7/8. The fact I can do it with the BBB means I don’t need to plug in, at a minimum, a separate monitor and keyboard. The BBB comes with only one USB port, and mine is currently occupied with a tiny WiFi dongle.

The current source code editor is nice as well. Much more than say, gedit, but not as sophisticated as Visual Studio Code. All in all it’s still a great text editor with very good syntax highlighting and reasonable, if minimal, language support in JavaScript and C/C++.

And Now For (Some of) the Complaints

The genesis of this section has been my ongoing attempt to interface a TI 74HC595N 8-bit serial-to-parallel shift register to the BBB’s serial peripheral interface (SPI) port. I was going by the instructions printed in the book “Exploring BeagleBone” by Derek Molloy, chapter 8. The book was published late 2014 with a 2015 copyright notice. I picked it up early 2015, right before I headed to Japan to support a major software installation and training effort. It went on the shelf next to the BBB and just like the BBB it was forgotten in the mad that started in April and didn’t finish until December of that year.

So here I was in retirement, powering up the BBB, and getting to know it and the book again. If you know anything about the book’s chapter 8, it’s all about serial communications, first with I2C and then SPI. I went after the SPI section because I’d already built up some material with 12C and the Raspberry Pi.

So I got the parts and built up a simple circuit to use as my test bed. And that’s when nothing appeared to work. I quickly  discovered that the directions in chapter 8, and supporting information in chapter 6, were all wrong. The OS that shipped on my BBB was Debian. I eventually updated that initial Debian to the latest, but it did nothing to help get anything working. In the end, reading various fora and looking in the code, I discovered how to get it all working.

  1. First disable the HDMI port on the BBB. This is done by editing the file ‘/boot/uEnv.txt’ and uncommenting the line ‘disable_uboot_overlay_video=1’
  2. Reboot the BBB after uncommenting the disable HDMI line.
  3. Use the command config-pin to then configure all the pins for SPI0 and SPI1

As an example for setting up the pins with config-pin, please see the following Bash script. Please note that you’ll need to run the script with sudo.

#!/usr/bin/env bash
# Execute on a BeagleBone Black with no overlays loaded.
# These commands require the default pin configuration in order to work.

# For SPI1, /dev/spidev1.#
config-pin p9_17 spi_cs
config-pin p9_18 spi
config-pin p9_21 spi
config-pin p9_22 spi_sclk

# For SPI0, /dev/spidev2.#
config-pin p9_28 spi_cs
config-pin p9_29 spi
config-pin p9_30 spi
config-pin p9_31 spi_sclk

If you deliberately or accidentally fail to disable the HDMI port, then you’ll see the following errors when trying to enable all pins for SPI0

P9_28 pinmux file not found!
bash: /sys/devices/platform/ocp/ocp*P9_28_pinmux/state: No such file or directory
Cannot write pinmux file: /sys/devices/platform/ocp/ocp*P9_28_pinmux/state
P9_29 pinmux file not found!
bash: /sys/devices/platform/ocp/ocp*P9_29_pinmux/state: No such file or directory
Cannot write pinmux file: /sys/devices/platform/ocp/ocp*P9_29_pinmux/state
P9_31 pinmux file not found!
bash: /sys/devices/platform/ocp/ocp*P9_31_pinmux/state: No such file or directory
Cannot write pinmux file: /sys/devices/platform/ocp/ocp*P9_31_pinmux/state

In Summary

  • If you’re working with either SPI port on the BeagleBone Black, then ignore just about everything in books and across the internet when it comes to configuring the SPI ports.
  • If you enable SPI ports via the firmware overlays with an entry in uEnv.txt, then only SPI1 will work. Any attempt to enable SPI0 will fail with both the config-pin command as well as the SPI0 firmware overlay.
  • If you want to enable both SPI ports then disable HDMI in the uEnv.txt (as documented above), then reboot the BBB. Then use config-pin to configure and enable all the necessary pins.
  • Chapter six in “Exploring BeagleBone” with regards to enabling SPI is totally wrong now. There is no Cape Manager anymore, and no “slots” feature to set up the firmware overlays. The only way to enable them appears to be via uEnv.txt, which must be hand edited before rebooting the BBB.