How to use ITEAD's 128x64 OLED display for Raspberry Pi (v2.0)

How to use ITEAD's 128x64 OLED display for Raspberry Pi (v2.0)

Tiny monochrome OLED displays, such as the "RPi OLED Add-on" from ITEAD studio, are an inexpensive way to display simple text messages and graphics - your application could print a sensor reading and also display it graphically, for example.

The RPi OLED Add-on, like many of these 0.96" displays, has a resolution of 128x64 pixels - but it also provides a GPIO passthrough connector and brings out the Pi's serial port plus 21 unused GPIO pins (including the SPI pins) out to "electronic brick" connections for makers, so they're ideal for hardware tinkerers.

Just one problem - ITEAD provide limited documentation.  The essential specs, inlcuding schematics are provided, but to get these boards working, there's a lot you need to figure out for yourself.  So here's what you need to do to setup and use these display boards - it's easy when you know how...


To install the hardware, power down your RPi (model A+, B+ or RPi 2), plug the display board into the 40-pin GPIO connector, then apply power to the Pi again.  That's all.  The display should remain clear (black).

Driver software

The RPi OLED Add-on uses a controller compatible with the "industry standard" SSD1306 chip in I2C mode; a number of drivers are already available - we only need to adapt one by changing the "reset" GPIO pin to suit this module.

Adafruit have developed an extensive collection of Python libaries to support their hardware, including SSD1306-compatible OLED modules. Their libraries are open source and it's ok for us to adapt them for use with the RPi OLED Add-on if we attribute the source to Adafruit, keep the same licence, and make our changes available to the open source community.  So we'll use a modified version of one of Adafruit's Python libraries. Why Python? It's popular, accessible and easy for beginners.

[These instructions assume that you're using Raspbian, as it's the operating system recommended by the Raspberry Pi Foundation, and that you're working at the command (shell) prompt. If you want to set up Raspbian, see my guide here.] 

To begin, ensure that Raspbian distribution is up to date, with:

sudo apt-get update
sudo apt-get dist-upgrade

then press 'Enter' to continue, and then reboot with 'sudo reboot'.

You'll need to enable the I2C interface on your Raspberry Pi - see my guide to setting up Raspbian.for instructions on how to do that, if you haven't done so already.

We also need to install some support packages, with:

sudo apt-get install build-essential python-dev python-pip -y
sudo apt-get install python-imaging python-smbus -y


Change directory to somewhere you have write permission ( 'cd ~' to go to your home directory will do), then download the support code:

git clone

Now change into the newly-created directory and run the install script:

cd Gooligum-Adafruit_Python_SSD1306
sudo python install


Example code

The package includes some example programs in the "examples" directory ('cd examples' to go there).

The first shows how to display text and draw basic shapes:

sudo ./

The second example displays an image (a cat pcture).  It inlcudes a comment toward the end of the code that shows how to display any image (in PNG format) on the OLED screen. 

To try it, type:

sudo ./

The final example scolls some text, animated into a sinewave shape, across the display - showing how to display text in a more complex way. The scrolling text is defined toward the middle of the code - it's easy to find and you can change it to your own messge.

To try it, type:

sudo ./

The examples are all reasonably clear, making it straightforward to expand on them, or to pull the routines out to use in your own code.

Good luck!

Posted by David Meiklejohn

Products related to this article

Add to Cart

Related Articles

Setting up a new Raspberry Pi for electronics hobbyists and makers

Installing Raspbian on an RPi and setting it up for electronics / making - with I2C, SPI, SSH and WiFi enabled

2 comments on this article - view comments

0 Comments To "How to use ITEAD's 128x64 OLED display for Raspberry Pi (v2.0)"

Write a comment

Your Name:

Enter the code in the box below:

Your Comment:
Note: HTML is not translated!
Powered By OpenCart
Gooligum Electronics © 2017