Guide for I2C OLED Display with Arduino

This article shows how to use the SSD1306 0.96 inch I2C OLED display with the Arduino. We’ll show you some features of the OLED display, how to wire it to the Arduino board, and how to write text to the display. Lastly, we’ll build a project example that displays temperature and humidity readings.

Introducing the 0.96 inch OLED display

The organic light-emitting diode (OLED) display that we’ll use in this tutorial is the SSD1306 model: a monocolor, 0.96-inch display with 128×64 pixels as shown in the following figure.

Build 25 cool Arduino projects with our course even with no prior experience DOWNLOAD »

Build 25 cool Arduino projects with our course even with no prior experience DOWNLOAD »

The OLED display doesn’t require backlight, which results in a very nice contrast in dark environments. Additionally, its pixels consume energy only when they are on, so the OLED display consumes less power when compared with other displays.

The model we’re using here has only four pins and communicates with the Arduino using I2C communication protocol. There are models that come with an extra RESET pin. There are also other OLED displays that communicate using SPI communication.

Pin wiring

Because the OLED display uses I2C communication protocol, wiring is very simple. You just need to connect to the Arduino Uno I2C pins as shown in the table below.

Pin Wiring to Arduino Uno
Vin 5V
GND GND
SCL A5
SDA A4

If you’re using a different Arduino board, make sure you check the correct I2C pins:

  • Nano: SDA (A4); SCL(A5);
  • MEGA: SDA (20); SCL(21);
  • Leonardo: SDA (20); SCL(21);

Libraries

To control the OLED display you need the “adafruit_GFX.h” and the “adafruit_SSD1306.h” libraries. Follow the next instructions to install those libraries.

Installing the adafruit_GFX library

  1. Click here to download the adafruit GFX library. You should have a .zip folder in your Downloads folder
  2. Unzip the .zip folder and you should get Adafruit-GFX-Library-master folder
  3. Rename your folder from Adafruit-GFX-Library-master to Adafruit_GFX_Library (you really need ro replace those “-” by “_”)
  4. Move the Adafruit_GFX_Library folder to your Arduino IDE installation libraries folder

Installing the adafruit_SSD1306 library

  1. Click here to download the adafruit_SSD1306 library. You should have a .zip folder in your Downloads folder
  2. Unzip the .zip folder and you should get Adafruit-GFX-Library-master folder
  3. Rename your folder from Adafruit_SSD1306-master to Adafruit_SSD1306
  4. Move the Adafruit_SSD1306 folder to your Arduino IDE installation libraries folder
  5. Finally, re-open your Arduino IDE

Tips for writing text using these libraries

Here’s some functions that will help you handle the OLED display library to write text or draw simple graphics.

  • display.clearDisplay() – all pixels are off
  • display.drawPixel(x,y, color) – plot a pixel in the x,y coordinates
  • display.setTextSize(n) – set the font size, supports sizes from 1 to 8
  • display.setCursor(x,y) – set the coordinates to start writing text
  • display.print(“message”) – print the characters at location x,y

Display Temperature and Humidity in the OLED Display with Arduino

In this section we’ll build a project that displays temperature and humidity readings on the OLED display. We’ll get temperature and humidity using the DHT11 temperature and humidity sensor. If you’re not familiar with the DHT11 sensor, read the following article:

Parts required

To complete this project you need the following components:

You can use the preceding links or go directly to MakerAdvisor.com/tools to find all the parts for your projects at the best price!

Schematic

Assemble the circuit by following the next schematic diagram.

display-dht11-oled_bb

Note: if you’re using a module with a DHT sensor, it normally comes with only three pins. The pins should be labeled so that you know how to wire them. Additionally, many of these modules already come with an internal pull up resistor, so you don’t need to add one to the circuit.

Code

Before proceeding, make sure you have installed the“adafruit_GFX.h” and the “adafruit_SSD1306.h” libraries to control the OLED display. For this project you also need two libraries to read from the DHT sensor: the DHT library and the Adafruit_Sensor library.

Installing the DHT library

To read from the DHT sensor, you must have the DHT library installed. If you don’t have the DHT library installed, follow the instructions below:

Download our Free eBooks and Resources

  1. Click here to download the DHT-sensor-library. You should have a .zip folder in your Downloads folder
  2. Unzip the .zip folder and you should get DHT-sensor-library-master folder
  3. Rename your folder from DHT-sensor-library-master to DHT
  4. Move the DHT folder to your Arduino IDE installation libraries folder

Installing the Adafruit_Sensor library

To use the DHT temperature and humidity sensor, you also need to install the Adafruit_Sensor library. Follow the next steps to install the library in your Arduino IDE:

  1. Click here to download the Adafruit_Sensor library. You should have a .zip folder in your Downloads folder
  2. Unzip the .zip folder and you should get Adafruit_Sensor-master folder
  3. Rename your folder from Adafruit_Sensor-master to Adafruit_Sensor
  4. Move the Adafruit_Sensor folder to your Arduino IDE installation libraries folder
  5. Finally, re-open your Arduino IDE

After installing all the necessary libraries, you can upload the following code.

/*
 * Random Nerd Tutorials - Rui Santos 
 * Complete Project Details https://randomnerdtutorials.com
 */
 
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <DHT.h>

#define DHTPIN 2
#define DHTTYPE DHT11
#define OLED_RESET 4
Adafruit_SSD1306 display(OLED_RESET);

// Initialize DHT sensor
DHT dht(DHTPIN, DHTTYPE);

void setup() {
  Wire.begin();
  dht.begin();
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);// initialize with the I2C addr 0x3C
}

void displayTempHumid(){
  delay(2000);
  // Reading temperature or humidity takes about 250 milliseconds!
  // Sensor readings may also be up to 2 seconds 'old' (its a very slow sensor)
  float h = dht.readHumidity();
  // Read temperature as Celsius
  float t = dht.readTemperature();
  // Read temperature as Fahrenheit
  float f = dht.readTemperature(true);

  // Check if any reads failed and exit early (to try again).
  if (isnan(h) || isnan(t) || isnan(f)) {
    display.clearDisplay(); // clearing the display
    display.setTextColor(WHITE); //setting the color
    display.setTextSize(1); //set the font size
    display.setCursor(5,0); //set the cursor coordinates
    display.print("Failed to read from DHT sensor!");
    return;
  }
  display.clearDisplay();
  display.setTextColor(WHITE);
  display.setTextSize(1);
  display.setCursor(0,0);
  display.print("Humidity: "); 
  display.print(h);
  display.print(" %\t");
  display.setCursor(0,10);
  display.print("Temperature: "); 
  display.print(t);
  display.print(" C"); 
  display.setCursor(0,20);
  display.print("Temperature: "); 
  display.print(f);
  display.print(" F"); 
}
void loop() {
  displayTempHumid();
  display.display();
}

View raw code

How the Code Works

Read this section if you want to learn how the code works. Otherwise, you can skip to the “Demonstration” section.

Include libraries

You need to include the necessary libraries to write to the OLED display: the Adafruit_GFX and the Adafruit_SSD1306. You also need to include the Wire library for I2C communication.

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

Include the DHT library to read from the DHT11 sensor.

#include <DHT.h>

Define pins and objects

Define the pin the DHT11 is connected to (digital pin 2) and define the DHT sensor type (DHT11).

#define DHTPIN 2 
#define DHTTYPE DHT11 // DHT 11

Even though our OLED display doesn’t have a RESET pin, we need to initialize it to make the library work:

#define OLED_RESET 4
Adafruit_SSD1306 display(OLED_RESET);

Create a DHT object called dht with the settings you’ve specific earlier (pin and type).

DHT dht(DHTPIN, DHTTYPE);

setup()

In the setup(), initialize I2C communication:

Wire.begin();

Initialize the DHT sensor:

dht.begin(); // initialize dht

And finally, initialize the OLED display:

display.begin(SSD1306_SWITCHCAPVCC, 0x3C);

displayTempHumid() function

Then, we create a displayTempHumid() function that reads temperature and humidity and displays the results on the OLED display. This function is then called in the loop().

The following lines read the temperature in Celsius, the temperature in Fahrenheit, and the humidity. The readings are saved on the h, t, and f variables.

float h = dht.readHumidity();
// Read temperature as Celsius
float t = dht.readTemperature();
// Read temperature as Fahrenheit
float f = dht.readTemperature(true)

Note: To learn more about how to use the DHT11/DHT22 temperature and humidity sensor with the Arduino read our DHT11/DHT22 guide.

There is an if statement that checks if the sensor fails to get the readings.

if (isnan(h) || isnan(t) || isnan(f)) {
    display.clearDisplay(); // clearing the display
    display.setTextColor(WHITE); //setting the color
    display.setTextSize(1); //set the font size
    display.setCursor(5,0); //set the cursor coordinates
    display.print("Failed to read from DHT sensor!");
    return;
}

If the sensor fails to get the readings, we display a message “Failed to read from DHT sensor” on the OLED display. For that, we need to do the following procedures:

Clear the display:

display.clearDisplay();

Set the text color, size, and the coordinates to display the text:

display.setTextColor(WHITE); //setting the color
display.setTextSize(1); //set the font size
display.setCursor(5,0); //set the cursor coordinates

Display the message:

display.print("Failed to read from DHT sensor!");

If we have valid sensor readings, display those readings on the OLED.

display.clearDisplay();
display.setTextColor(WHITE);
display.setTextSize(1);
display.setCursor(0,0);
display.print("Humidity: ");
display.print(h);
display.print(" %\t");
display.setCursor(0,10);
display.print("Temperature: ");
display.print(t);
display.print(" C");
display.setCursor(0,20);
display.print("Temperature: ");
display.print(f);
display.print(" F");

In the loop() we call the displayTempHumid() function to get temperature and humidity readings on the OLED display.

displayTempHumid();

Finally, we use the display() method to update the display.

display.display();

Demonstration

After wiring the circuit and uploading the code, the OLED display shows humidity and temperature (both in Celsius and Fahrenheit) readings. The sensor readings are updated on the display every two seconds.

demonstration

Wrapping Up

The OLED display provides an easy and inexpensive way to display text or graphics using an Arduino. We hope you’ve found this guide and the project example useful.

If you like Arduino, make sure you check all our Arduino resources:

Don’t miss our next tutorials and projects! Make sure you subscribe the RNT blog.

Thanks for reading

January 29, 2019


Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »

Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our weekly newsletter!

33 thoughts on “Guide for I2C OLED Display with Arduino”

  1. Rui
    I could use a little guidance with MULTIPLE OLED displays :-).. I have two OLEDs (.96″ I2C) but with different addresses (03c and 03d). I need to print to one with some fixed data (ie a string) and the other with variable data (ie read.analog(0)..) to make one “large” display. Can’t figure out the arduino code to do this beyond the “display.begin(SSD1306_SWITCHCAPVCC, 0x3D); ” statement. Any ideas suggestions would be greatly appreciated Thanks
    TOM

      • This is a good guide to get you going. To use two displays, you can create two different “display” instances, e.g. displayFixed and displayVariable at the discovered addresses then handle writing the data in code. Another approach would be to create a C++ class that automatically does the Wire scan in the constructor to get the device addresses dynamically and has methods that handle writing to each I2C OLED.

  2. This is a great tutorial. You’ve made the OLED display simple even for me. The examples in the library are too advanced to grasp.

  3. I’d been searching for nearly 3 months that how to properly display the content I want on a OLED screen; came across this site, really helped me in my project. Thanks!

  4. After some sketch issues…I was able to get this working with the OLED .96 display… It works great and I find the display is adequate enough…

    Thanks for the projects!!!

  5. Hi Rui, I finally got my hands on some of these displays. The first one was failed on arrival. the second one worked for 2 days and failed, I now have a third one received today and it works but IDK for how long. I’m wondering if others are having a high failure rate with these. I bought mine from several different ebay vendors. The first one never illuminated, but I could see data and clock on the SDA & SCL lines. The second one worked on both 3.3v and 5v as the listing stated, but failed. The one I have now I plan to run from a pro mini 3.3v version just to see if it lasts longer. But all 3 vendors stated in their listings that they should run on either 3.3 or 5 volts. Any thoughts?

  6. I’m new to all this. When I put in the code I get an error message. fatal error: vector: No such file or directory. I downloaded the libraries. Thanks for your time!

  7. Thanks for the free Downloads.I want to Donate you but the link i found doesnt work.
    Please send me your Adresse that I can Donate you with PayPal.
    You now lot from this Electronic and programming Stuff.Yor little Sister i like
    to see so much as well.
    Nice Regards from Germany

  8. M. Rui,

    I learn lots and want to learn more . how i will create a Number writing by LED or square? need more books. all the time on online, its make problem of my eyes. soooooooooo, what you kind suggestion

Leave a Comment

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.