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

sudo apt-get update
sudo apt-get upgrade

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

sudo raspi-config

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 :

sudo apt-get install build-essential git-core libi2c-dev i2c-tools lm-sensors

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

root@raspberrypi:~# ls /dev/i2c*
root@raspberrypi:~# ls /dev/spi*
/dev/spidev0.0  /dev/spidev0.1

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 :

git clone https://github.com/hallard/ArduiPi_OLED

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

cd ArduiPi_OLED
sudo make

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 :

sudo make

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

./oled_demo --help

You will see help and OLED supported

root@raspberrypi:~/ArduiPi_OLED/examples# ./oled_demo -h
Usage is: ./oled_demo --oled type [options]
  --<o>led type
OLED type are:
  0 Adafruit SPI 128x32
  1 Adafruit SPI 128x64
  2 Adafruit I2C 128x32
  3 Adafruit I2C 128x64
  4 Seeed I2C 128x64
  5 Seeed I2C 96x96
  6 SH1106 I2C 128x64
Options are:
  --<v>erbose  : speak more to user
<?> indicates the equivalent short option.
Short options are prefixed by "-" instead of by "--".
Example :
./oled_demo -o 1 use a Adafruit SPI 128x64 OLED

./oled_demo -o 4 -v use a Seeed I2C 128x64 OLED being verbose

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

./oled_demo --verbose --oled 0

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

./oled_demo --verbose --oled 3

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

./oled_demo --verbose --oled 6

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




You can discuss about this article or other project using the community forum