Wyświetlacz OLED SSD1306 - tekst

0.96″ OLED SSD1306 display and Raspberry Pi

Quick and visually compelling projects don’t come easy ? Naaah, just like last time – let’s get on a very nice and easy project – attaching display onto Raspberry Pi. As we were chating on the Malinowe Pi Group, Hubert Wu pointed me to a OLED 128×64 display, monochrome. With a quite decent resolution of 128×64 and based on OLED technology this is a nice 0.96 inch display. Well, my first computer was running at Hi-Res of 640×400 and monochrome too. Priced at $3-$5 pops-up as: ”0.96″ I2C IIC Serial 128X64” in popular stores and is clearly based on original Adafruit SSD1306 – which would be my first choice!

Wyświetlacz OLED SSD1306 - grafika
A OLED SSD1306 display

What will you need?


  • git, python-devel, python-pip (installable under Raspbian on RPi)
  • Library with examples from Adafruit: Adafruit_Python_SSD1306


  • Raspberry Pi – 1B, 1A, 2B, 3B – any will do with installed Raspbian (mini Raspbian is OK)
  • Adafriud OLED SSD 1306 or compatible


This external display connected to RPi (and which is independent from HDMI or Composite video outputs), is very useful for small projects – and for me – when need to know what the IP address is 🙂


First let’s connect power – VCC and GND to 3,3 and GND on RPi, then SDA and SCL to GPIO0 (GPIO 2 @ RPi B+, 2 i 3) and GPIO1 (GPIO 3 @ RPi B+, 2 i 3):

OLED SSD1306 display - connecting to RPi...
OLED SSD1306 display – connecting to RPi…

The wiring is quite simple and all pins are adjacent (well we omit GPIO4!). During first wiring attempt i mixed up VCC and GND! RPi greeted me with low light on it’s green LED, but all was fine after proper wiring. This is the view from the display:

OLED SSD1306 - wiring
OLED SSD1306 – wiring


On the software side we are going to turn on the I2C (GPIOO or GPIO2 and GPIO1 or GPIO3) in our RPi, by means of running raspi-config, then – (Advanced Options->I2C).
After reboot – we should install the software, but first – let’s update the system:

Next the software:

Then the RPi.GPIO:

Now – let’s get via git the Adafruit library with examples:


Let’s find out if this works…

Now edit the shapes.py and find the line that tells it to use the I2C version of the display:

This is correct, add “#’ at the begging of the other lines that define the ‘disp‘ variable

Wow, it works! There’re more examples – a very nice – animate.py and image.py, just don’t forget to edit them to use the proper definition of the ‘disp’.
As bonus – we can use our own fonts (TTF format) – i.e.: 16pix height:

Wyświetlacz OLED SSD1306 - tekst
OLED SSD1306 – own font/text

The image.py allows you to display monochrome picture in PPM – use GIMP to save and use dithering to get acceptable results:

Wyświetlacz OLED SSD1306 - grafika
OLED SSD1306 – graphics

Well, as you see – the input characteristics of the image matters, but at leas you can see the logo

Now all that is left is to use python or bash to display IP address of you RPi!

Wyświetlacz OLED SSD1306 - tekst
OLED SSD1306 – text

  • Michiel van Hoorn

    Hi Lukasz, great write-up. I has some error message regarding the i2c bus. After changing the i2c_bus=0 it worked fine. Thanks!

    • Łukasz C. Jokiel


  • Ab Mughal

    Hi, this is really helpful, I manage to run the shaps.py. I’m trying to change the GPIO pins to connect at different pins on raspberry pi. how would i change.

  • “Ekran” word on LCD is also a Turkish word. It means “screen” in Turkish 😀 Greetz!

    • Łukasz C. Jokiel

      Coincidence? I think not :D, thanks!

  • Reuben Bocarro

    Hi. i getting a bit of an error here after i try to run the image.py file after editing.
    the terminal displays this message:
    import error no module named adafruit_pureIO.smbus