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...

Installation

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.

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

cd Gooligum-Adafruit_Python_SSD1306
sudo python setup.py 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 ./ITEAD-OLED_shapes.py

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 ./ITEAD-OLED_image.py

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 ./ITEAD-OLED_animate.py

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.