New Adafruit generic OLED display driver for Raspberry PI

After some years of using my SSD1306 library driver on Raspberry Pi, I needed to get it working with the new more and more popular 1.3″ I2C OLED driver that we can find for some bucks on Chinese ebay sellers. Unfortunately these OLED are not using the classic SSD1306 chipset, they use the SH1106 and the library was not working with them. So it’s time to update.

I renamed the library because it can now drive not only SSD1306 chip, the the old library has been superseded by this new one. It does always exist on my github but you are strongly encouraged to use this new one.

 What do you need ?

  • A Raspberry Pi (A+, B+, Rev 2 or Rev 1) with Raspbian, I recommend the Wheezy version
  • A I2C or SPI Adafruit or generic OLED display that have a chipset driver kind of SSD1306, SH1106, SSD1327
  • Wiring cable or better if you do not want to use wire, a ArduiPi Board that contains connectors for Adafruit OLED. This is with this board that the 1st tutorial was made
  • ArduiPi OLED Library Source code located on github
  • Setup correct I2C bus according to Raspberry Pi Revision (1, 2, A+, B+) 


  • You must have development tools installed onto your Raspberry Pi for compiling the driver library and a updated Wheezy distribution is preferable.
  • A good idea to read the excellent Adafruit tutorial about OLED display

Wiring the OLED Display

The SPI display use more pins than the I2C version, has I connected it to a ArduiPi board the connections are already done on the board so nothing to do, but if you want to do it with cable you should do it as following /

  • Connections for SPI
Adafruit SPI DisplayOLED PinPi P1 Header PinRaspberry Pi Pin
3V3 (output, leave unconnected)2
D/C618IO24 (GPIO)
RST (Reset)722IO25 (GPIO)
CS (Chip Select)824CE0 (SPI)
  • Connections for I2C
Adafruit I2C DisplayOLED PinPi P1 Header PinRaspberry Pi Pin
3V3 (output, leave unconnected)2
RST (Reset)422IO25 (GPIO)

Ok done, now go to Raspberry Pi

I am connecting to Pi with ssh, once you’ll on the Pi issue the following commands :

First of all, we need to update the Pi software to the latest, issue

Enable I2C and SPI modules directly with raspi-config tool, issue a

Then go to menu Advanced Option, select SPI and under question ” Would you like the SPI kernel module to be loaded by default ?”, select Yes, Do the same thing for I2C Advanced Option.

As I don’t use monitor or TV connected to Pi, I decreased dedicated video memory, always in raspi-config, go to Advanced Options then Memory Split, then type 16 Mo (the minimal) used for GPU, then select Finish, and select Yes when asked to reboot.


To be able to compile you will need the compiler and some others tools, issue a :

To drive the Raspberry PI I/O ports I decided to use the small and pretty cool library bcm2835 from Mike. I added some features so I included directly in build, you don’t need to install anything. The features added are :

  • Added millis() function
  • Added option to use custom Chip Select Pin PI GPIO instead of only CE0 CE1
  • Done a hack to use CE1 by software as custom CS pin because Pi hardware SPI for CE1 seems not to work (I will investigate on this later)
  • Added function to determine PI revision board
  • Added function to set SPI speed (instead of divider for easier look in code)
  • Rewrited the I2C functions, I was unable to get the included one working, surely I was doing bad things

This bcm2835 mod has been done years ago and I did not updated to new version since, but it still works fine.

Sometimes I2C and SPI modules are not started and thus he cannot start the sample code. The solution to start the modules at startup by adding the two following lines into the file /etc/modules

Reboot, then you MUST see SPI and I2C devices with the following command

Installation of the generic Driver

The Driver is based on Adafruit Arduino library, I ported the code to be able to compile and run on Raspberry Pi but added also some features.

The driver is compiled into a library with all functions, including driving OLED with SPI or I2C and driving 128×32 and 128×64 OLED size. The OLED size and driving mode is now on the new init function of the class, no need to compile with #define

Get all the file from github dedicated repo :

The build install process is in the Makefile, so issue a:

The new build script will compile the library (libArduiPi_OLED*) and install it for you (this is why need sudo) library in /usr/local/lib/ and library headers in /usr/local/include/

Fire the sample test code

Go to the examples folder and issue a :

Plug the OLED on your ArduiPi board (or manually wire), and you’re in,

You will see help and OLED supported

So launch the following command to use a Adafruit SPI 128×32 OLED :

For a I2C 128×64 OLED (such as Adafruit or more and more popular Chinese OLED SSD1306) do a :

For the new 1.3″ SH1106 I2C 128×64 OLED  do a :

Now time to post some picture of course

With generic SH1106 1.3″ OLED

With generic SH1106 1.3″ OLED

With generic SSD1306 0.96" OLED

With generic SSD1306 0.96″ OLED

Adafruit SPI SSD1306 on ArduiPi

Adafruit SPI SSD1306 on ArduiPi

Adafruit I2C SSD1306 on ArduiPi

Adafruit I2C SSD1306 on ArduiPi






  1. Can you add a systeminfo demo ? Like the lcdproc (cpu,mem,storge,net,temperature).


Comments on this topic in community Forums.