Controlling an Adafruit SSD1306 SPI OLED With a Beaglebone Black

What Are We Doing Here?

In an earlier post I described how to use the py-gaugette library to drive an Adafruit 128×32 monochrome OLED display from a Raspberry Pi, and a followup article added high-quality fonts.

I’ve now updated the library to run on the BeagleBone Black and to support Adafruit’s larger 128×64 display.

On the BBB py-gaugette uses Adafruit’s BBIO library for SPI and GPIO access.

Preparing the BeagleBone Black

I started with a fresh Angstrom boot image (the 2013-09-04 eMMC flasher image). After booting from the SD and flashing the eMMC (which takes about 30 minutes), I installed the Adafruit BBIO library following the instructions in their tutorial, which boil down to this:

/usr/bin/ntpdate -b -s -u
opkg update && opkg install python-pip python-setuptools python-smbus
pip install Adafruit_BBIO

Make sure you have flashed your eMMC and rebooted into the eMMC image before you run the above steps. If you are still running the eMMC flasher image when you run opkg to install the library, things get weird. Yep, I did that, not proud.Controlling an Adafruit SSD1306 SPI OLED With a Beaglebone Black

Once you have these packages installed, you might think to look for /dev/spidevX.Y to verify that the SPI drivers are installed. To my surprise they don’t show up until you actually run code that loads the SPI library. The Linux 3.8 kernel uses new and crafty device overlay trees to manage devices. The Adafruit library will automatically load the overlay that creates those devices as necessary, so only if you look at /dev after running the sample code will you see the spidev device files.

Confused? Let me illustrate.

After a reboot there are no spidev devices:

root@beaglebone:~# ls -l /dev/spidev*
ls: cannot access /dev/spidev*: No such file or directory

Run an application that instantiates Adafruit_BBIO.SPI:

python -c “from Adafruit_BBIO.SPI import SPI; SPI(0,0)”

Look again, there they are, it’s magic:

root@beaglebone:~# ls -l /dev/spidev*
crw——- 1 root root 153, 1 Jan 28 02:25 /dev/spidev1.0
crw——- 1 root root 153, 0 Jan 28 02:25 /dev/spidev1.1

Wire It Up

The BBB has two SPI interfaces. I’m using SPI0. If you want to use SPI1 you will need to follow these instructions to disable HDMI first.

BeagleBone Black Signal Colour Adafruit OLED
P9_1 GND black Gnd
P9_3 Vcc red Vin
P9_13 Data/Cmd purple DC
P9_15 Reset white Rst
P9_17 Slave Sel green CS
P9_18 MOSI blue Data
P9_22 Clock yellow Clk

Pins P9_17, P9_18 and P9_22 are fixed by the SPI0 interface. Pins P9_13 and P9_15 are arbitrarily chosen GPIO pins, feel free to use any available pins and pass the appropriate pin name to the constructor.

Porting the Code

Porting gaugette.SSD1306 was straight forward. You can see what was required in this commit.

The only catch getting this running on the BBB was a small bug in SPI_writebytes in the Adafruit_BBIO.SPI module. To refresh the entire 128×64 display we need to transfer 1024 bytes of data. Conveniently Adafruit’s writebytes routine has a maximum transfer size of 1024 bytes.Controlling an Adafruit SSD1306 SPI OLED With a Beaglebone Black Schematic Unfortunately the C code uses an 8-bit counter to store the length, which effectively reduces the maximum transfer size to 255 bytes. For now I’ve worked around that by chunking transfers into 255-byte blocks, and I have filed a bugfix with Adafruit so hopefully we can remove that hack soon.

Update: Adafruit accepted the fix but I will wait until they update the python package currently at 0.0.19 before I remove the workaround.

I can see that maintaining separate branches of py-gaugette for the RPi and BBB is going to be burden, so I’ve now refactored the library to isolate all of the SPI and GPIO dependencies into abstraction classes that will automatically detect the current platform and delegate to the appropriate library. The new classes are gaugette.spi.SPI and gaugette.gpio.GPIO. This change makes all of the gaugette device classes run cross-platform except rgbled, which requires PWM support. I’ll write an abstraction layer for PWM later.


For more detail: Controlling an Adafruit SSD1306 SPI OLED With a Beaglebone Black

About The Author

Ibrar Ayyub

I am an experienced technical writer holding a Master's degree in computer science from BZU Multan, Pakistan University. With a background spanning various industries, particularly in home automation and engineering, I have honed my skills in crafting clear and concise content. Proficient in leveraging infographics and diagrams, I strive to simplify complex concepts for readers. My strength lies in thorough research and presenting information in a structured and logical format.

Follow Us:

Leave a Comment

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

Scroll to Top