Page 1 of 1

OLED Display 128x64 python library

Posted: Sat Mar 28, 2015 7:36 am
by blavery
I have posted a python library for that ubiquitous 0.96 inch 128x64 OLED display (eBay about $5).

This is a common library suiting both Raspberry Pi and Virtual-GPIO.
TC04400_4.JPG (46.34 KiB) Viewed 28338 times
This OLED display is the monochrome 4-pin type (I2C), not the SPI ones (identify by more pins). Typically about $5 on eBay from LOTS of suppliers. Count the PCB pins and read the advert carefully - don't necessarily trust the eBay headline! The subtlely of IIC versus SPI is a bit much for some sellers.

There are some "two-colour" ones, but these are simply a different (fixed) colour for the top 16 pixel lines.

Interfacing is trivial, and they seem to work fine on 3.3V and 5V. On arduino (V-GPIO) the arduino's high-value pullups seem to work OK without anything added.

The text, font, image and graphic work is handled by the PIL python module(s), and ttf font files from anywhere work fine, at any scaling. 1-bit BMP or PNG images can be displayed.

This library has been evolved from R Hull's very fine library at If you simply want to use it on Raspberry Pi, Hull's version may well suit you better.

Re: OLED Display 128x64 python library

Posted: Mon Jun 01, 2015 6:04 am
by blavery
Hmmm, there seem to be several issues here. Firstly let me state my raspbian image used for testing is an update-update-update of an early image 7 Jan 2014, updated repeatedly through to current! It has collected smbus and PIL etc along the way. The point of that is, installing packages now just might give different results. But here goes ...

1. Do you have python-smbus (for python2.?) and python3-smbus (for python3) both installed? "name 'SMBus' is not defined" suggests a problem here. (I looked today at a fresh Raspbian of 5/5/2015. It shows python3-smbus not in the repository. An apt-get update/upgrade to today, and python3-smbus then reappears!)

2. To my understanding, the ageing PIL library has been available for python2 on Raspberry Pi (I installed it some while back) but the newer clone PILLOW has been slower in coming to Pi. I see from here ... illow.html that PILLOW should be installable, but today my attempts have not yet succeeded. You seem to have one or other installed, or you should have seen "name PIL is not defined" errors. I probably installed PIL by a "pip" install, because it is (at least now) not in the repository. Until I find a drama-free installation for PILLOW then this oled library may not be so useful.

3. I didn't state it in my first posts, but this library was implemented on python (2) not python3, or at least not verified against python3. From experience porting some other projects, the error "Third argument must be a list" is a typical difference in getting python2 data stuff equally happy on python3. If I get a PIL/PILLOW version working here on python3 I should amend the code for python3.

Python3. Hmmm. Sometimes "windows" or "VHS", even "blueray" or "26-pin GPIO" could be judged not tech-best, but nevertheless market-best. Put that another way: each company should be run by the entrepreneur, not the engineer. (I'm an engineer!)

In the meantime, the lib_oled96 library as posted should work if you can get PIL and smbus onto python2.

Re: OLED Display 128x64 python library

Posted: Mon Jun 01, 2015 10:02 am
by blavery
Well in that case it's mainly an issue of an instruction or two that need python2 -> python3 tweaks. (probably more precisely coercing the various data arriving at lines 56 / 63 into correct list format.)

I'm not in a position immediately to check it out. Got a few things happening around here just now. I'll post a python3 fix as soon as I can.

Re: OLED Display 128x64 python library

Posted: Mon Jun 01, 2015 9:05 pm
by FTrevorGowen
FWIW, I've been working on 'C' demo. code for the yellow/blue version of the display (my blue only one proved faulty and I'm awaiting a replacement). As a by-product I've generated (to-date) two column/row based, 8x8 character font files - one a "rotated" version of "font.h" provided with wiringPi** and the other, a similarily rotated version of the font used for the "Jupiter Ace". If they may be of interest and can be adapted for use with the Python library drop me a P.M. (Although the demo. suite is available from within my webpages, they're due for an update later this week and IIRC only the first font is there at the moment).
** As shown here (both will be shown when I've had chance to update): ... SSD1306.29

Re: OLED Display 128x64 python library

Posted: Tue Jun 02, 2015 12:36 pm
by FTrevorGowen
supra wrote:@bleavry, FTrevorGowen.
I just google and found out that the driver SSD1306 doesn't work under RPI+Python3
Interesting - I wonder if there's a related issue to the one I found using 'C' (I'm not a Python programmer so can't comment directly) : Normally, for I2C comns., I either use 'C' system calls to i2cset etc.** (slow) or wiringPi's I2C ('C') library. Due to the requirements of the SSD1306 controller I ended up using @joan's pigpio library instead (see this thread for more info:
viewtopic.php?f=44&t=108564 ) which supports more SMBus transfer methods. (I'm not using any "SSD1306 driver" as such and my 'C' code prepares & sends SSD1306 commands and data at a fairly low-level).
** Am I correct in thinking that Python has similar support?

Re: OLED Display 128x64 python library

Posted: Thu Jun 04, 2015 5:18 am
by blavery
I indicated earlier there appeared to be three or more issues.
Here are the answers that I found:
I start with a fresh Raspbian image 5/5/2015 from the foundation's download page.
I used a RPi(1)-B hardware.

1. I2C issues
I find no way to get i2c to appear as a device ("ls /dev") using raspi-config and the device tree system.
(spi yes, i2c no.)
I reverted to the "old" way, ie including these 2 entries in the file /etc/modules:
Now I correctly see i2c-1 as a device.

2. SMBus
You need to install python-smbus for python and python3-smbus for python3.
But the Raspbian image of 5/5/2015 is missing python3-smbus.
After an "apt-get update" (even without upgrades) then python3-smbus reappears and can be installed.

3. Pillow
Need to "apt-get install python-dev python-setuptools".
Then Pillow can be installed for python: "sudo easy_install Pillow". Takes quite a while.
Need also to "apt-get install python3-dev python3-setuptools"
Then Pillow can be installed for python3: "sudo easy_install3 Pillow".
Now the PIL error messages disappear.

4. oled96 code compatibility with python3
a. "Third argument must be a list of integers" error.
Python3 integer division is different from python. Add int() into line 34 of the lib_ file:
self.pages = int(self.height / 8)
b. "xrange" not a python3 function. Replace xrange with simply range in 3 lib_ lines 73, 92, 96.

Now the oled works correctly on both python and python3.

I will correct the github version shortly.

Re: OLED Display 128x64 python library

Posted: Thu Jun 04, 2015 7:42 am
by joan

As far as I am aware you still need to load the i2c-dev module as device tree only seems to load i2c-bcm2708.

Re: OLED Display 128x64 python library

Posted: Thu Jun 04, 2015 9:28 am
by blavery
Thanks Joan,
A hybrid?
So if I put i2c-dev in modules file, and then use device tree otherwise, it should go?
I'll try it later.

Re: OLED Display 128x64 python library

Posted: Thu Jun 04, 2015 9:37 am
by FTrevorGowen
joan wrote:@blavery
As far as I am aware you still need to load the i2c-dev module as device tree only seems to load i2c-bcm2708.
Although that is about to (has now?) change :) :

Re: OLED Display 128x64 python library

Posted: Thu Jun 04, 2015 12:38 pm
by blavery
As I knew you would be,
you are right.
... i2c-dev in modules, then use devicetree settings.

Re: OLED Display 128x64 python library

Posted: Sat Jun 06, 2015 11:43 pm
by blavery
You could cross-check on the (updated yesterday) README at github:
for how to get SMBus working on both python and python3.
Maybe that might help?

Re: OLED Display 128x64 python library

Posted: Sun Jun 07, 2015 10:43 am
by blavery

"I am using 1.3" oled instead of 0.96". Doesn't is matter or not?"
Of course it ... matters. They use different driver chips (0.96" SSD1306 / 1.3" looks like SSD1106?? SH1106?? -- I suspect very similar chip, but probably not identical, and certainly not checked by me.) All bets are off.
The device my code refers to is clearly stated in first post above.

"Can you make resolution bigger? I changed to 10."

"self.pages = int(self.height / 10)"
Pls refer to SSD1306 documentation:
Page 25.
"The GDDRAM is a bit mapped static RAM holding the bit pattern to be displayed. The size of the RAM is
128 x 64 bits and the RAM is divided into eight pages, from PAGE0 to PAGE7"
The correct code at line 34 is:
"self.pages = int(self.height / 8)"

Re: OLED Display 128x64 python library

Posted: Mon Jun 08, 2015 2:57 am
by blavery
That's good news.
And you ought to find a way to post up the working code of your project using that oled device so others can benefit too. :-)

Re: OLED Display 128x64 python library

Posted: Sat Sep 10, 2016 10:04 pm
by bugiroff
I know this is kinda an old thread, but I picked up one of these off eBay for less than a buck. After installing the python-smbus file, this works great for python 2.7 with Raspbian Jesse. I did have to look up which pins to use (pin 3 is SDA and pin 5 is SCL) but after that, things work great.

Re: OLED Display 128x64 python library

Posted: Wed Mar 08, 2017 6:57 am
by tatoosh
Thanks for the code. It worked out of the box for me!

Re: OLED Display 128x64 python library

Posted: Mon Mar 20, 2017 9:05 pm
by wga22
Can anyone help me with ideas of why I can get this LED to work fine with python libraries (per instructions here), but not with node (
I suppose that rules out the hardware/os issues mentioned in this thread?