This is a quick tutorial for our 128x64 and 128x32 pixel monochrome OLED displays. These displays are small, only about 1" diagonal, but very readable due to the high contrast of an OLED display. Each OLED display is made of 128x64 or 128x32 individual white OLEDs, each one is turned on or off by the controller chip. Because the display makes its own light, no backlight is required. This reduces the power required to run the OLED and is why the display has such high contrast; we really like this miniature display for its crispness!
The driver chip, SSD1306 can communicate in multiple ways including I2C, SPI and 8-bit parallel. However, only the 128x64 display has all these interfaces available. For the 128x32 OLED, only SPI is available. Frankly, we prefer SPI since its the most flexible and uses a small number of I/O pins so our example code and wiring diagram will use that.
The OLED and driver require a 3.3V power supply and 3.3V logic levels for communication. The power requirements depend a little on how much of the display is lit but on average the display uses about 20mA from the 3.3V supply. Built into the OLED driver is a simple switch-cap charge pump that turns 3.3v-5v into a high voltage drive for the OLEDs. You can run the entire display off of one 3.3V supply or use 3.3V for the chip power and up to 4.5V for the OLED charge pump or 3.3V for the chip power and a 7-9V supply directly into the OLED high voltage pin.
Unless you have the older v1 128x64 OLED, you can rest assured that your OLED is 5V ready. All 1.3" 128x64 and the small 128x32 SPI and I2C are 5V ready, if you have a v2 0.96" 128x64 OLED with the 5V ready mark on the front, it's also 5V safe. If you have an older 0.96" OLED (see below) you'll need to take extra care when wiring it to a 5V micontroller. The OLED is designed to be 5V compatible so you can power it with 3-5V and the onboard regulator will take care of the rest.
All OLEDs are safe to use with 3.3V logic and power.
Simply connect GND to ground, and Vin to a 3 to 5V power supply. There will be a 3.3V output on the 3Vo pin in case you want a regulated 3.3V supply for something else.
The older 0.96" 128x64 OLED is a little more complex to get running as it is not 5V compatible by default, so you have to provide it with 3.3V power.
VCC is the high voltage OLED pin. If you're using the internal charge pump, this must be left unconnected. If you're not using the charge pump, connect this to a 7-9V DC power supply.
For most users, we suggest connecting VDD and VBAT together to 3.3V and then leaving VCC unconnected.
Using these OLEDs with Arduino sketches requires that two libraries be installed: Adafruit_SSD1306, which handles the low-level communication with the hardware, and Adafruit_GFX, which builds atop this to add graphics functions like lines, circles and text.
Enter “ssd1306” in the search field, locate the Adafruit SSD1306 library and select “Install” (or “Upgrade” if you have an older version). Then repeat the same for “gfx” and the Adafruit GFX library.
If you’re using an earlier version of the Arduino IDE software and need to install libraries manually, or if you’d like to download the library source code to look inside, both of these can be found on Github.
After uncompressing, the folders should be renamed (if necessary) to Adafruit_SSD1306 and Adafruit_GFX. The former should contain the files Adafruit_SSD1306.cpp and Adafruit_SSD1306.h (plus a few extra files). Sometimes unZIPping creates a nested Adafruit_SSD1306 folder within another folder…you don’t want that. The latter should contain Adafruit_GFX.cpp and Adafruit_GFX.h (plus some extra files).
Place both folders in your (home)/Documents/Arduino/Libraries folder. You may need to create the libraries subfolder if its your first library. Restart the Arduino IDE.
After you've finished wiring the display as indicated on the following pages, load the example sketch to demonstrate the capabilities of the library and display.
Before you start wiring, a strip of header must be soldered onto the OLED. It is not possible to "press-fit" the header, it must be attached!
Finish by soldering each of the 8 pins to the 8 pads!
The display can be used with any I2C microcontroller. Because the I2C interface is for 'writing' to the display only, you'll still have to buffer the entire 512 byte frame in the microcontroller RAM - you can't read data from the OLED (even though I2C is a bidirectional protocol).
To start, you'll need to solder the two jumpers on the back of the OLED. Both must be soldered 'closed' for I2C to work!
This matches the example code we have written. Once you get this working, you can try a different Reset pin (you can't change the SDA and SCL pins).
The breakouts are ready for SPI by default, but if you used them for I2C at some point, you'll need to remove the solder jumpers. Use wick or a solder sucker to make sure both are clear!
This matches the example code we have written. Once you get this working, you can try another set of pins.
The 128x32 SPI OLED is very easy to get up and running because it has built in level shifting. First up, take a piece of 0.1" header 8 pins long.
Plug the header long end down into a breadboard and place the OLED on top. Solder the short pins into the OLED PCB.
Finally, connect the pins to your Arduino - GND goes to ground, Vin goes to 5V, DATA to digital 9, CLK to digital 10, D/C to digital 11, RST to digital 13 and finally CS to digital 12.
The 128x32 I2C OLED is very easy to get up and running because it has built in level shifting and regulator. First up, take a piece of 0.1" header 6 pins long.
Solder the short pins into the OLED PCB.
This wiring diagram is only for the older 0.96" OLED that comes with a level shifter chip. If you did not get a level shifter chip, you have a V2.0 so please check out the other wiring tutorial!
The version 1 128x64 OLED runs at 3.3V and does not have a built in level shifter so you'll need to use a level shifting chip to use with a 5V microcontroller. The following will assume that is the case. If you're running a 3.3V microcontroller system, you can skip the level shifter.
We'll assume you want to use this in a breadboard, take a piece of 0.1" header 10 pins long.
Place the header in a breadboard and then place the left hand side of the OLED on top.
We'll be using the internal charge pump so connect VDD and VBAT together (they will connect to 3.3V). GND goes to ground.
Place a CD4050 level shifter chip so pin one is at the top.
Connect pin 10 to D/C pin 12 to CLK (SPI clock) and pin 15 to DAT (SPI data).
Connect pin 2 to RES (reset) and pin 4 to CS (chip select). Pin 1 goes to 3.3V and pin 8 to ground.
You can connect the inputs of the level shifter to any pins you want but in this case we connected digital I/O 13 to pin 3 of the level shifter, 12 to pin 5, 11 to pin 9, 10 to pin 11 and 9 to pin 14. This matches the example code we have written. Once you get this working, you can try another set of pins.
Display does not work on initial power but does work after a reset.
The OLED driver circuit needs a small amount of time to be ready after initial power. If your code tries to write to the display too soon, it may not be ready. It will work on reset since that typically does not cycle power. If you are having this issue, try adding a small amount of delay before trying to write to the OLED.
In Arduino, use delay() to add a few milliseconds before calling oled.begin(). Adjust the amount of delay as needed to see how little you can get away with for your specific setup.
Display is showing burn in on some pixels.
The display can have image burn in for any pixels left on over a long period of time - many days. Try to avoid having the display on constantly for that length of time.
This guide was first published on Jul 29, 2012. It was last updated on 2019-04-22 17:13:43 -0400.