OLED I2C Display Arduino Tutorial

Created on: 17 October 2017

How to connect and program the Geekcreit 0.96 inch 4 pin white I2C OLED module with Arduino. OLED display based on a SSD1306 OLED driver IC.

In this tutorial a 0.96 inch monochrome OLED display from Geekcreit is connected or interfaced to an Arduino. Libraries are then installed and some example programs run which show how to use the display in an Arduino sketch.

The display connects to Arduino using only four wires – two for power and two for data, making the wiring very simple. The data connection is I2C (I²C, IIC or Inter-Integrated Circuit). This interface is sometimes called TWI (Two Wire Interface).

At the very lowest level, the Arduino Wire library is used to communicate with the display. Libraries are available that make it easy to start using the display right away to display text and graphics. These libraries are installed in this tutorial.

How to connect the Geekcreit 0.96 Inch 4 pin white I2C OLED module 12864 to Arduino
How to connect the Geekcreit 0.96 Inch 4 pin white I2C OLED module to Arduino

How to Connect the Geekcreit 0.96 Inch I2C OLED Display to Arduino

The first and most important thing to note is that some of the displays may have the GND and VCC power pins swapped around. Check your display to make sure that it is the same as the image below. If the pins are swapped, make sure to change the connections to the Arduino – OLED VCC connects to 5V on the Arduino, OLED GND to GND on the Arduino.

Caution! Make sure that you connect the power pins correctly. Some modules have GND and VCC swapped around. Don't blow up your display!

Also make sure that your display is 5V compatible as this one is.

Geekcreit 0.96 Inch OLED Display I2C/TWI Pinout
Geekcreit 0.96 Inch OLED Display I2C/TWI Pinout

Arduino Uno OLED Wiring

The image below shows how to connect the Geekcreit 0.96 inch OLED I2C display to Arduino. Pin connections are as follows for wiring the OLED display to an Arduino Uno.

  • OLED GND – Arduino GND
  • OLED VCC – Arduino 5V
  • OLED SCL – Arduino Uno A5
  • OLED SDA – Arduino Uno A4
How to Connect the Geekcreit 0.96 Inch OLED I2C Display to Arduino - Wiring Diagram
How to Connect the Geekcreit 0.96 Inch OLED I2C Display to Arduino – Wiring Diagram

Arduino MEGA 2560 OLED Wiring

Pin connections for wiring an Arduino MEGA 2560 to the OLED display are as follows.

  • OLED GND – Arduino GND
  • OLED VCC – Arduino 5V
  • OLED SCL – Arduino MEGA 2560 pin 21
  • OLED SDA – Arduino MEGA 2560 pin 20

Arduino OLED I²C Libraries for SSD1306 and Graphics Functions

Two Arduino libraries must be installed to start using the display. The SSD1306 driver library is used to initialize the display and provide low level display functions. The GFX library provides graphics functions for displaying text, drawing lines and circles, etc. Both these libraries are available from Adafruit.

Install the SSD1306 Driver Library

Download the Adafruit_SSD1306 library which is saved to your computer in a file called Adafruit_SSD1306-master.zip.

Copy the Adafruit_SSD1306-master folder from the downloaded zipped file into the Arduino libraries folder. This folder is usually found at Documents → Arduino → libraries on Windows systems. On Linux it is usually found at home folder → Arduino → libraries.

Finally in the Arduino library folder, rename the Adafruit_SSD1306-master folder to Adafruit_SSD1306.

Install the GFX Library

Download the Adafruit_GFX library which is saved to your computer in a file called Adafruit-GFX-Library-master.zip.

Copy the Adafruit-GFX-Library-master folder from the downloaded zipped file to the Arduino library folder as done for the SSD1306 driver above.

In the Arduino library folder rename the Adafruit-GFX-Library-master folder to Adafruit_GFX.

Verifying the Library Installation

After installing the libraries, your Arduino library folder should look as follows.

Arduino Library Folder with New Libraries Installed
Arduino Library Folder with New Libraries Installed

The contents of the two library folders should look as follows, with the SSD1306 driver library folder on the left and GFX library on the right.

Adafruit SSD1306 and GFX Library Folders
Adafruit SSD1306 and GFX Library Folders

Finding the OLED Libraries in Arduino

If the Arduino IDE was open during the library installation, close it first and then restart it.

In the Arduino IDE, find the libraries under the Sketch → Include Library menu from the top menu bar. When the mouse cursor is hovered above the Include Library menu item, the new libraries can be found on the pop-out menu. In Windows the libraries appeared under "Contributed libraries" near the top of the pop-out menu on my system. On my Linux computer the libraries appeared under the "Recommended libraries" section of the pop-out menu near the bottom.

Modifying the SSD1306 Driver

The SSD1306 driver isn't set up for the Geekcreit OLED display by default. The display size must be changed in the driver before it can be used. If it is not changed, an error message will appear when attempting to verify the example sketch (see the section below) in the Arduino IDE:
#error ("Height incorrect, please fix Adafruit_SSD1306.h!");

Open the Adafruit_SSD1306 folder that was just installed in the Arduino libraries folder. Find Adafruit_SSD1306.h and open it in a text editor. Scroll down the file to find the section with the header SSD1306 Displays or search for for this term in the text editor to find it quickly. Comment out #define SSD1306_128_32 and uncomment #define SSD1306_128_64 so that the code in this section looks as follows.

/*=========================================================================
    SSD1306 Displays
    -----------------------------------------------------------------------
    The driver is used in multiple displays (128x64, 128x32, etc.).
    Select the appropriate display below to create an appropriately
    sized framebuffer, etc.

    SSD1306_128_64  128x64 pixel display

    SSD1306_128_32  128x32 pixel display

    SSD1306_96_16

    -----------------------------------------------------------------------*/
   #define SSD1306_128_64
//   #define SSD1306_128_32
//   #define SSD1306_96_16
/*=========================================================================*/

Save the file after making the changes.

Running the Adafruit Example Sketch

If the libraries for the display were installed correctly, example programs for the display will be found in the Arduino IDE under File → Examples → Adafruit SSD1306 – open the ssd1306_128x64_i2c sketch under this menu.

The I²C address must be changed in this sketch in order for it to work with the Geekcreit display. Change the address from 0x3D to 0x3C as shown in the code below. This address is not 0x78 or 0x7A as printed on the back of the OLED board.

void setup()   {                
  Serial.begin(9600);

  // by default, we'll generate the high voltage from the 3.3v line internally! (neat!)
  //display.begin(SSD1306_SWITCHCAPVCC, 0x3D);  // initialize with the I2C addr 0x3D (for the 128x64)
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);  // changed this to 0x3C to make it work
  // init done

As shown above, the address was changed to 0x3C in display.begin(). The original line of code is shown above it and is commented out.

After making the changes, the sketch can be uploaded to the Arduino. When building the sketch for an Arduino Uno the IDE will display a low memory warning message, but the sketch will still run.

If the changes to the driver and example sketch were made correctly and the OLED display is wired to the Arduino correctly, the sketch should start running. The example program starts by showing the Adafruit logo, it then turns on a single pixel. Various graphics and text functions are then displayed.

Quick Start Programming Tips

This section of the tutorial shows how to quickly start using the I2C OLED display with the Adafruit libraries. A quick start Arduino template sketch, text display demo and various graphics functions follow.

Arduino Sketch Template File

The template file below can be used to quickly start new OLED projects. It includes the necessary header files and initialization code for the display. Copy the code and use it as a basis for starting new OLED display projects.

/*-------------------------------------------------------------------------------------
 * Template file for 4-pin I2C OLED display, e.g. from Geekcreit
 * using Adafruit SSD1306 driver and GFX libraries.
 * Tutorial:
 * https://startingelectronics.org/tutorials/arduino/modules/OLED-128x64-I2C-display/
 *-------------------------------------------------------------------------------------*/
#include <Wire.h>
#include <Adafruit_SSD1306.h>
#include <Adafruit_GFX.h>

// OLED display TWI address
#define OLED_ADDR   0x3C

// reset pin not used on 4-pin OLED module
Adafruit_SSD1306 display(-1);  // -1 = no reset pin

// 128 x 64 pixel display
#if (SSD1306_LCDHEIGHT != 64)
#error("Height incorrect, please fix Adafruit_SSD1306.h!");
#endif

void setup() {
  // initialize and clear display
  display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR);
  display.clearDisplay();
  display.display();

  
}

void loop() {
  // put your main code here, to run repeatedly:

}

Text "Hello World" and Pixel Demo Program

The Arduino sketch below sets a pixel at each corner of the screen as shown in the image below. A function is then used to display a line of text on the display as can be seen in the image – a "hello world" program. An explanation of how the program works follows.

Geekcreit 128 x 64 OLED Display Arduino Demo
Geekcreit 128 x 64 OLED Display Arduino Demo

#include <Wire.h>
#include <Adafruit_SSD1306.h>
#include <Adafruit_GFX.h>

// OLED display TWI address
#define OLED_ADDR   0x3C

Adafruit_SSD1306 display(-1);

#if (SSD1306_LCDHEIGHT != 64)
#error("Height incorrect, please fix Adafruit_SSD1306.h!");
#endif

void setup() {
  // initialize and clear display
  display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR);
  display.clearDisplay();
  display.display();

  // display a pixel in each corner of the screen
  display.drawPixel(0, 0, WHITE);
  display.drawPixel(127, 0, WHITE);
  display.drawPixel(0, 63, WHITE);
  display.drawPixel(127, 63, WHITE);

  // display a line of text
  display.setTextSize(1);
  display.setTextColor(WHITE);
  display.setCursor(27,30);
  display.print("Hello, world!");

  // update display with all of the above graphics
  display.display();
}

void loop() {
  // put your main code here, to run repeatedly:

}

Screen Coordinates and Dimensions

After initializing the display, the above sketch then draws a pixel at each extreme of the display by using drawPixel() to place a pixel in each corner of the screen. The first parameter passed to drawPixel() is the screen X coordinate and the second parameter is the screen Y coordinate.

Screen dimensions are 128 by 64 pixels and pixel coordinates start at 0, 0 for the top left pixel. This means that the X coordinates for the screen are from 0 to 127 (not 1 to 128) left to right; and Y coordinates are from 0 to 63 (not 1 to 64) top to bottom.

As can be seen in the sketch and on the display, the corner pixels are at the following coordinates:

  • Top left pixel – x = 0, y = 0.
  • Top right pixel – x = 127, y = 0.
  • Bottom left pixel – x = 0, y = 63.
  • Bottom right pixel – x = 127, y = 63.

How to Write a Line of Text to the Display

Use print() to write a line of text to the display as shown in the above sketch. Before writing text to the display, call setTextSize() and setTextColor(). Because this is a monochrome display, setTextColor() must be passed WHITE for the text to be seen on a black background.

Text that is written to the display is positioned by calling setCursor() to move the invisible cursor to the desired position. X and Y coordinates are passed to setCursor() to move the cursor and start of text to these pixel coordinates.

Basic Principle of Operation of the Graphics Library

All text and graphics are written to buffer memory in the Arduino. Only when display() (display.display() in the above code) is called is the contents of the buffer displayed on the screen. This means that any text and graphical objects such as lines and circles will not appear on the screen until display() is called.

Questions and Answers

Why is -1 Passed to the Adafruit_SSD1306 Constructor?

Adafruit_SSD1306 display(-1);

The number passed to the the Adafruit_SSD1306 constructor as shown in the above code is the number of the Arduino pin used to reset the display for displays that have a reset pin. As the display used in this tutorial does not have a reset pin, -1 is passed to the constructor so that none of the Arduino pins are used as a reset for the display.

Where is the Adafruit Logo Stored that Appears on the Screen?

If the display() function is called without first calling clearDisplay() as shown in the following code, the Adafruit logo appears on the screen. Where does this logo come from?

void setup() {
  display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR);
  display.display();
}

Memory used for the screen buffer is initialized with the Adafruit logo in the Adafruit_SSD1306 driver library. This code is found in the Adafruit_SSD1306.cpp file in the Arduino libraries folder at libraries → Adafruit_SSD1306. The logo consists of hexadecimal code used to initialize the buffer[] array near the top of the Adafruit_SSD1306.cpp file.

Calling clearDisplay() clears the logo from memory allowing new text and graphics to be written to the buffer.

Further Reading

Adafruit have provided a short tutorial on using their GFX library. The tutorial explains more about the coordinate system used for displays and shows how to draw graphics primitives such as lines and circles.

References

Adafruit Arduino SSD1306 and GFX library installation – from Adafruit, the developers of the libraries used in this tutorial. Buy something from their shop if you are able to in order to support their software development such as the libraries used in this tutorial.