Guide For I2C OLED Display With Arduino

7/21/2020 Guide for I2C OLED Display with Arduino | Random Nerd Tutorials
 Menu 
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 connect it to the Arduino board, and how to write text, draw shapes and
display bitmap images. Lastly, we’ll build a project example that displays temperature and humidity readings.
Introducing the 0.96 inch OLED display

https://randomnerdtutorials.com/guide-for-oled-display-with-arduino/ 1/99
The organic light-emitting diode (OLED) display that we’ll use in this tutorial is the SSD1306 model: a
 Menu 
monocolor, 0.96-inch display with 128×64 pixels as shown in the following gure.
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  Menu 
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 di erent 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);
 Menu 
Libraries
To control the OLED display you need the adafruit_SSD1306.h and the adafruit_GFX.h libraries. Follow the
next instructions to install those libraries.
1. Open your Arduino IDE and go to Sketch > Include Library > Manage Libraries. The Library Manager
 Menu 
should open.
2. Type “SSD1306” in the search box and install the SSD1306 library from Adafruit.
3. After installing the SSD1306 library from Adafruit, type “GFX” in the search box and install the library.
 Menu 
4. After installing the libraries, restart 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 o

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

 Menu 
display.display() – call this method for the changes to make e ect
Testing the OLED Display

After wiring the OLED display to the Arduino and installing all required libraries, you can use one example
from the library to see if everything is working properly.
In your Arduino IDE, go to File > Examples > Adafruit SSD1306 and select the example for the display you’re
using.
 Menu 
The following code should load:
/*********
Complete project details at https://randomnerdtutorials com
Complete project details at https://randomnerdtutorials.com
 Menu 
This is an example for our Monochrome OLEDs based on SSD1306 drivers. Pick one up today in the adafruit s
This example is for a 128x32 pixel display using I2C to communicate 3 pins are required to interface (two
Adafruit invests time and resources providing this open source code, please support Adafruit and open-sou
Written by Limor Fried/Ladyada for Adafruit Industries, with contributions from the open source community
*********/
#include <SPI.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#define SCREEN_WIDTH 128 // OLED display width, in pixels

#define SCREEN_HEIGHT 64 // OLED display height, in pixels
// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

#define OLED_RESET -1 // Reset pin # (or -1 if sharing Arduino reset pin)
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
#define NUMFLAKES 10 // Number of snowflakes in the animation example
#define LOGO_HEIGHT 16
#define LOGO_WIDTH 16
static const unsigned char PROGMEM logo_bmp[] =
View raw code

 Menu 
If your OLED doesn’t have a RESET pin, you should set the OLED_RESET variable to -1 as shown below:
#define OLED_RESET -1 // Reset pin # (or -1 if sharing Arduino reset pin)
Upload the code to your Arduino board. Don’t forget to select the right board and COM port in the Tools
menu.
You should get a series of di erent animations in the OLED as shown in the following short video.
Write Text – OLED Display  Menu 
The Adafruit library for the OLED display comes with several functions to write text. In this section, you’ll learn
how to write and scroll text using the library functions.
“Hello, world!” OLED Display

The following sketch displays Hello, world! message in the OLED display.
/*********
Rui Santos
*********/
#include <Wire.h>


Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);
void setup() {
Serial.begin(115200);
if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3D for 128x64

 Menu 
Serial.println(F("SSD1306 allocation failed"));
for(;;);
}
delay(2000);
display.clearDisplay();
display.setTextSize(1);
display setTextColor(WHITE);
View raw code
After uploading the code, this is what you’ll get in your OLED:
Let’s take a quick look on how the code works.

 Menu 
If your OLED display is not showing anything:
Check that the OLED display is properly wired to the Arduino

Double-check the OLED display I2C address: with the OLED connected to the Arduino, upload this code
and check the I2C address in the Serial Monitor
You should change the OLED address in the following line, if necessary. In our case, the address is 0x3C.
if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
Importing libraries
 Menu 
First, you need to import the necessary libraries. The Wire library to use I2C and the Adafruit libraries to
write to the display: Adafruit_GFX and Adafruit_SSD1306 .
#include <Wire.h>
Initialize the OLED display
Then, you de ne your OLED width and height. In this example, we’re using a 128×64 OLED display. If you’re
using other sizes, you can change that in the SCREEN_WIDTH , and SCREEN_HEIGHT variables.

Then, initialize a display object with the width and height de ned earlier with I2C communication protocol (
&Wire ).
The (-1) parameter means that your OLED display doesn’t have a RESET pin. If your OLED display does have a
RESET pin, it should be connected to a GPIO. In that case, you should pass the GPIO number as a parameter.
In the setup() , initialize the Serial Monitor at a baud raute of 115200 for debugging purposes.
 Menu 
Initialize the OLED display with the begin() method as follows:
Serial.println("SSD1306 allocation failed");
for(;;); // Don't proceed, loop forever
}
This snippet also prints a message on the Serial Monitor, in case we’re not able to connect to the display.
In case you’re using a di erent OLED display, you may need to change the OLED address. In our case, the
address is 0x3C .
If this address doesn’t work, you can run an I2C scanner sketch to nd your OLED address. You can nd the
I2C scanner sketch here.
After initializing the display, add a two second delay, so that the OLED has enough time to initialize before
 Menu 
writing text:
delay(2000);
Clear display, set font size, color and write text
After initializing the display, clear the display bu er with the clearDisplay() method:
Before writing text, you need to set the text size, color and where the text will be displayed in the OLED.
Set the font size using the setTextSize() method:
Set the font color with the setTextColor() method:
display.setTextColor(WHITE);
WHITE sets white font and black background.
De ne the position where the text starts using the setCursor(x,y) method. In this case, we’re setting the
 Menu 
text to start at the (0,10) coordinates.
display.setCursor(0,10);
Finally, you can send the text to the display using the println() method, as follows:
display.println("Hello, world!");
Then, you need to call the display() method to actually display the text on the screen.
display.display();
Scrolling Text
The Adafruit OLED library provides useful methods to easily scroll text.
startscrollright(0x00, 0x0F) : scroll text from left to right
startscrollleft(0x00, 0x0F) : scroll text from right to left
startscrolldiagright(0x00, 0x07) : scroll text from left bottom corner to right upper corner
startscrolldiagleft(0x00, 0x07) : scroll text from right bottom corner to left upper corner
The following sketch implements those methods.

 Menu 
/*********
Rui Santos
*********/
#include <Wire.h>


void setup() {

for(;;);
}
delay(2000);
 Menu 
display setTextColor(WHITE);
View raw code
The text scrolls as shown in the following short video.
Using Other Fonts – OLED Display

The Adafruit GFX library allows us to use some alternate fonts besides the built-in fonts. It allows you to chose
between Serif, Sans, and Mono. Each font is available in bold, italic and in di erent sizes.
The sizes are set by the actual font. So, the setTextSize() method doesn’t work with these fonts. The fonts
 Menu 
are available in 9, 12, 18 and 24 point sizes and also contain 7-bit characters (ASCII codes) (described as 7b in
the font name).
You can chose from the next selection of fonts:
FreeMono12pt7b.h FreeSansBoldOblique12pt7b.h
FreeMonoBold12pt7b.h FreeSansOblique12pt7b.h
FreeMonoBoldOblique12pt7b.h FreeSerif12pt7b.h
FreeMonoOblique12pt7b.h FreeSerifBold12pt7b.h
FreeSans12pt7b.h FreeSerifBoldItalic12pt7b.h
FreeSansBold12pt7b.h FreeSerifItalic12pt7b.h
The fonts that work better with the OLED display are the 9 and 12 points size.
 Menu 
To use one of those fonts, rst you need to include it in your sketch, for example:
#include <Fonts/FreeSerif12pt7b.h>
Next, you just need to use the setFont() method and pass as argument, the speci ed font:
display.setFont(&FreeSerif12pt7b);
After specifying the font, all methods to write text will use that font. To get back to use the original font, you
just need to call the setFont() method with no arguments:
display.setFont();
Upload the next sketch to your board:
/*********
Rui Santos
*********/
#include <Wire.h>
 Menu 
#include <Fonts/FreeSerif9pt7b.h>


void setup() {
for(;;);
}
delay(2000);
display.setFont(&FreeSerif9pt7b);
View raw code
Now, your display prints the “Hello, world!” message in FreeSerif font.
 Menu 
Draw Shapes in the OLED Display

The Adafruit OLED library provides useful methods to draw pixels, lines and shapes. Let’s take a quick look at
those methods.
Draw a pixel
 Menu 
To draw a pixel in the OLED display, you can use the drawPixel(x, y, color) method that accepts as
arguments the x and y coordinates where the pixel appears, and color. For example:
display.drawPixel(64, 32, WHITE);
Draw a line
 Menu 
Use the drawLine(x1, y1, x2, y2, color) method to create a line. The (x1, y1) coordinates indicate the
start of the line, and the (x2, y2) coordinates indicates where the line ends. For example:
display.drawLine(0, 0, 127, 20, WHITE);
Draw a rectangle
 Menu 
The drawRect(x, y, width, height, color) provides an easy way to draw a rectangle. The (x, y)
coordinates indicate the top left corner of the rectangle. Then, you need to specify the width, height and
color:
display.drawRect(10, 10, 50, 30, WHITE);
You can use the fillRect(x, y, width, height, color) to draw a lled rectangle. This method accepts
the same arguments as drawRect() .
 Menu 
The library also provides methods to displays rectangles with round corners: drawRoundRect() and
fillRoundRect() . These methods accepts the same arguments as previous methods plus the radius of the
corner. For example:
display.drawRoundRect(10, 10, 30, 50, 2, WHITE);
 Menu 
Or a lled round rectangle:
display.fillRoundRect(10, 10, 30, 50, 2, WHITE);
 Menu 
Draw a circle
To draw a circle use the drawCircle(x, y, radius, color) method. The (x,y) coordinates indicate the
 Menu 
center of the circle. You should also pass the radius as an argument. For example:
display.drawCircle(64, 32, 10, WHITE);
In the same way, to build a lled circle, use the fillCircle() method with the same arguments:
display.fillCircle(64, 32, 10, WHITE);
Draw a triangle
 Menu 
Use the the drawTriangle(x1, y1, x2, y2, x3, y3, color) method to build a triangle. This method
accepts as arguments the coordinates of each corner and the color.
display.drawTriangle(10, 10, 55, 20, 5, 40, WHITE);
Use the fillTriangle() method to draw a lled triangle.
display.fillTriangle(10, 10, 55, 20, 5, 40, WHITE);
 Menu 
Invert
The library provides an additional method that you can use with shapes or text: the invertDisplay()
method. Pass true as argument to invert the colors of the screen or false to get back to the original colors.
If you call the following command after de ning the triangle:
display.invertDisplay(true);
You’ll get an inverted triangle as follows:
 Menu 
Code – Draw Shapes

Upload the following sketch that implements each snippet of code we’ve covered previously and goes
through all the shapes.
/*********
Rui Santos
*********/
#include <Wire.h>
#define SCREEN WIDTH 128

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64  Menu 

void setup() {
for(;;);
}
delay(2000); // Pause for 2 seconds
// Clear the buffer
View raw code
Display Bitmap Images in the OLED

You can display 128×64 bitmap monocolor images on the OLED display.
First, use an imaging program to resize a photo or picture and save it as monochrome bitmap. If you’re on a
Windows PC, you can use Paint.
 Menu 
Then, use a Image to C Array converter to convert the image into an array. I’ve used LCD Image Converter.
Run the program and start with a new image. Go to Image > Import and select the bitmap image you’ve
created earlier.
 Menu 
Go to Options > Conversion and in the Prepare tab, select the following options:
Type: Monochrome, Threshold Dither

Main Scan Direction: Top to Bottom
Line Scan Direction: Forward
 Menu 
Go to the Image tab and select the following options:
Split to rows
Block size: 8 bit
Byte order: Little-Endian
 Menu 
Then, click OK. Finally, in the main menu, go to File > Convert. A new le with .c extension should be saved.
That le contains the C array for the image. Open that le with a text editor, and copy the array.
In our case, this is the array that we get:
static const uint8_t image_data_Saraarray[1024] = {

0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff,
 Menu 
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x0a, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x14, 0x9e, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x36, 0x3f, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x6d, 0xff, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0xfb, 0xff, 0x80, 0x1f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x03, 0xd7, 0xff, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x07, 0xef, 0xff, 0x80, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x0f, 0xdf, 0xff, 0x90, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x0f, 0xbf, 0xff, 0xd0, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x1d, 0x7f, 0xff, 0xd0, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x01, 0x1b, 0xff, 0xff, 0xc0, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x02, 0xa7, 0xff, 0xff, 0xc0, 0x07, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x03, 0xff, 0xc0, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff,
View raw code
Copy your array to the sketch. Then, to display the array, use the drawBitmap() method that accepts the
following arguments (x, y, image array, image width, image height, rotation). The (x, y) coordinates de ne
where the image starts to be displayed.

 Menu 
Copy the code below to display your bitmap image in the OLED.
/*********
Rui Santos
*********/
#include <Wire.h>
#define SCREEN_WIDTH 128

#define SCREEN_HEIGHT 64
static const unsigned char PROGMEM image_data_Saraarray[] = {

0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff,
 Menu 
0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff,
0xff 0xff 0xff 0xff 0xff 0xfc 0x00 0x00 0x00 0x00 0x00 0x1f 0xff 0xff 0xff 0xff
View raw code
After uploading the code, this is what we get on the display.
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:
Complete Guide for DHT11/DHT22 Humidity and Temperature Sensor With Arduino
 Menu 
Parts required
To complete this project you need the following components:
0.96 inch OLED display

Arduino – Read Best Arduino Starter Kits
DHT11 or DHT22 temperature and humidity sensor
Breadboard
4.7k Ohm resistor (or 10k Ohm resistor)
Jumper wires
You can use the preceding links or go directly to MakerAdvisor.com/tools to nd all the parts for your projects
at the best price!
Schematic
Assemble the circuit by following the next schematic diagram.
 Menu 
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.
Installing Libraries  Menu 

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 aditional libraries to read from the DHT sensor: the DHT library and the
Adafruit_Sensor library. Follow the next steps to install those libraries
1. Open your Arduino IDE and go to Sketch > Include Library > Manage Libraries. The Library Manager
should open.
2. Search for “DHT” on the Search box and install the DHT library from Adafruit.
3. After installing the DHT library from Adafruit, type “Adafruit Uni ed Sensor” in the search box. Scroll all
 Menu 
the way down to nd the library and install it.
4. Restart your Arduino IDE.
Code
After installing all the necessary libraries, you can upload the following code.
/*********
Rui Santos

 Menu 
*********/
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <DHT.h>


#define DHTPIN 2 // Digital pin connected to the DHT sensor
// Uncomment the type of sensor in use:

#define DHTTYPE DHT11 // DHT 11
//#define DHTTYPE DHT22 // DHT 22 (AM2302)
DHT dht(DHTPIN, DHTTYPE);
void setup() {
View raw code
How the Code Works  Menu 

Read this section if you want to learn how the code works. Otherwise, you can skip to the “Demonstration”
section.
Importing libraries
The code starts by including the necessary libraries. The Wire , Adafruit_GFX and Adafruit_SSD1306 are
used to interface with the OLED display. The Adafruit_Sensor and the DHT libraries are used to interface
with the DHT22 or DHT11 sensors.
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <DHT.h>
Create a display object
Then, de ne your OLED display dimensions. In this case, we’re using a 128×64 pixel display.

Then, initialize a display object with the width and height de ned earlier with I2C communication protocol (
&Wire ).
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);  Menu 
The (-1) parameter means that your OLED display doesn’t have a RESET pin. If your OLED display does have a
RESET pin, it should be connected to a GPIO. In that case, you should pass the GPIO number as a parameter.
Create a DHT object
Then, de ne the DHT sensor type you’re using. If you’re using a DHT11 you don’t need to change anything on
the code. If you’re using another sensor, just uncomment the sensor you’re using and comment the others.
#define DHTTYPE DHT11 // DHT 11

Initialize a DHT sensor object with the pin and type de ned earlier.
DHT dht(DHTPIN, DHTTYPE);
setup()
In the setup() , initialize the serial monitor for debugging purposes.
Initialize the DHT sensor:

 Menu 
dht.begin();
Then, initialize the OLED display.

for(;;);
}
In this case, the address of the OLED display we’re using is 0x3C. If this address doesn’t work, you can run an
I2C scanner sketch to nd your OLED address. You can nd the I2C scanner sketch here.
Add a delay to give time for the display to initialize, clear the display and set the text color to white:
delay(2000);
display.setTextColor(WHITE)
In the loop() is where we read the sensor and display the temperature and humidity on the display.
Get temperature and humidity readings from DHT
The temperature and humidity are saved on the t and h variables, respectively. Reading temperature and
 Menu
humidity is as simple as using the readTemperature() and readHumidity() methods on the dht object. 
float t = dht.readTemperature();
float h = dht.readHumidity();
In case we are not able to get the readings, display an error message:
if (isnan(h) || isnan(t)) {
Serial.println("Failed to read from DHT sensor!");
}
If you get that error message, read our troubleshooting guide: how to x “Failed to read from DHT sensor”.
Display sensor readings on the OLED display
The following lines display the temperature on the OLED display.
display.print("Temperature: ");
display.print(t);
display.print(" ");
 Menu 
display.cp437(true);
display.write(167);
display.print("C");
We use the setTextSize() method to de ne the font size, the setCursor() sets where the text should
start being displayed and the print() method is used to write something on the display.
To print the temperature and humidity you just need to pass their variables to the print() method as
follows:
display.print(t);
The “Temperature” label is displayed in size 1, and the actual reading is displayed in size 2.
To display the º symbol, we use the Code Page 437 font. For that, you need to set the cp437 to true as
follows:
display.cp437(true);
Then, use the write() method to display your chosen character. The º symbol corresponds to character 167.
display.write(167);  Menu 
A similar approach is used to display the humidity:
display.setCursor(0, 35);
display.print("Humidity: ");
display.setCursor(0, 45);
display.print(h);
display.print(" %");
Don’t forget that you need to call display.display() at the end, so that you can actually display something
on the OLED.
display.display();
Demonstration
After wiring the circuit and uploading the code, the OLED display shows the temperature and humidity
readings. The sensor readings are updated every ve seconds.
 Menu 
Troubleshooting
If your DHT sensor fails to get the readings or you get the message “Failed to read from DHT sensor”, read
 Menu 
our DHT Troubleshooting Guide to help you solve that problem.
If you get the “SSD1306 allocation failed” error or if the OLED is not displaying anything in the screen, it can
be one of the following issues:
Wrong I2C address
The I2C address for the OLED display we are using is 0x3C. However, yours may be di erent. So, make sure
you check your display I2C address using an I2C scanner sketch.
SDA and SCL not connected properly
Please make sure that you have the SDA and SCL pins of the OLED display wired correctly.
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:
Arduino Mini Course (Free)

Arduino Step-by-step Projects (course)
60+ Arduino Projects and Tutorials
Free electronics resources and eBooks
Don’t miss our next tutorials and projects! Make sure you subscribe the RNT blog.
Thanks for reading

 Menu 
[eBook] MicroPython Programming with ESP32 and ESP8266
Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython rmware DOWNLOAD
»
Recommended Resources
Build a Home Automation System from Scratch » With Raspberry Pi, ESP8266, Arduino, and Node-RED.
 Menu 
Home Automation using ESP8266 eBook and video course » Build IoT and home automation projects.
Arduino Step-by-Step Projects » Build 25 Arduino projects with our course, even with no prior
experience!
What to Read Next…
 Menu 
Power ESP32/ESP8266 with Solar Panels (includes battery level monitoring)
 Menu 
Telegram: Control ESP32/ESP8266 Outputs (Arduino IDE)
Install uPyCraft IDE – Linux Ubuntu Instructions

 Menu 
ESP32 Deep Sleep with Arduino IDE and Wake Up Sources
 Menu 
ESP32 with DHT11/DHT22 Temperature and Humidity Sensor using Arduino IDE
 Menu 
How to Make Two ESP8266 Talk
Enjoyed this project? Stay updated by subscribing our weekly newsletter!
Your Email Address
 SUBSCRIBE
72 thoughts on “Guide for I2C OLED Display with Arduino”
Steve Tripoli
September 29, 2016 at 4:30 pm
Thanks for the guide.
Reply
Rui Santos
October 2, 2016 at 11:26 am
 Menu 
No problem! Thanks for reading Steve
Reply
John
Awesome Rui, I’ve been looking at these displays with much interest. This looks like fun!
Reply
Rui Santos
They work great, but keep in mind that they are very very small. Thanks!
Reply
 Menu 
cesar marin
muchas gracias por la contribucion. felicitaciones por su labor. siga adelante
Reply
Rui Santos
You’re welcome Cesar!
Reply
Shehu Bello
Very interesting! I appreciate your e ort Mr. Rui.
Reply
 Menu 
Rui Santos
Thanks Shehu!
Reply
Gorki
It is too advanced for me right now, I keep it for when the time is right. It seems very simply explained,
Congratulations
Reply
Rui Santos
Thanks for reading, if you follow each step at a time, you’ll see it’s very easy.  Menu 
Rui
Reply
Tom Evans
December 27, 2016 at 4:41 pm
Rui
I could use a little guidance with MULTIPLE OLED displays :-).. I have two OLEDs (.96″ I2C) but with
di erent addresses (03c and 03d). I need to print to one with some xed data (ie a string) and the
other with variable data (ie read.analog(0)..) to make one “large” display. Can’t gure out the arduino
code to do this beyond the “display.begin(SSD1306_SWITCHCAPVCC, 0x3D); ” statement. Any ideas
suggestions would be greatly appreciated Thanks
TOM
Reply
Rui Santos
 Menu 
Hi Tom,
I’ve never tried that, so I can’t give you a clear explanation of how to make it work without trying
myself.
Thanks and good luck with your project,

Rui
Reply
JayAchTee
July 29, 2018 at 11:47 am
This is a good guide to get you going. To use two displays, you can create two di erent “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.
Reply
Menel
January 19, 2017 at 7:43 am
 Menu 
Very, very interesting !!!!!!!!!
Reply
Rui Santos
January 24, 2017 at 7:12 pm
Thanks for your feedback Menel!
Regards,
Rui
Reply
Harold Lacadie
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.
Reply
 Menu 
Sara Santos
December 21, 2017 at 11:06 am
Hi. We’re glad you’ve enjoyed.

Thanks.
Reply
Steve Fraser
March 7, 2018 at 12:35 pm
Thank you for sharing your time and knowledge with us. I have enjoyed the tutorials and I have
learned quite a bit.
Cheers,
Steve
Reply
 Menu 
Sid Marker
April 23, 2018 at 5:15 am
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!
Reply
Sara Santos
April 23, 2018 at 9:21 am
Hi.
I’m glad you’ve found our content useful.
Good luck with your projects.
Regards,
Sara
Reply
 Menu 
Daniel F
May 11, 2018 at 12:19 am
Thanks for the guide. you are the best!!!!
Reply
Sara Santos
May 13, 2018 at 9:40 am
You’re welcome
Reply
Glenn Anderson
July 19, 2018 at 7:01 am
After some sketch issues…I was able to get this working with the OLED .96 display… It works great and
I nd the display is adequate enough…
Thanks for the projects!!!

 Menu 
Reply
Sara Santos
July 30, 2018 at 10:46 am
Great!
Reply
John
August 8, 2018 at 4:10 am
Hi Rui, I nally got my hands on some of these displays. The rst 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
di erent ebay vendors. The rst 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?
Reply
 Menu 
Leonor
Excuse me, where can i get the libraries for the OLED display??
Reply
Sara Santos
September 17, 2018 at 8:46 am
Hi.
You can nd the libraries in the following links:
– https://github.com/adafruit/Adafruit_SSD1306
– https://github.com/adafruit/Adafruit-GFX-Library
Reply
 Menu 
KG
November 29, 2018 at 1:48 am
I’m new to all this. When I put in the code I get an error message. fatal error: vector: No such le or
directory. I downloaded the libraries. Thanks for your time!
Reply
Sara Santos
Hi Kg.
You also need to install the adafruit sensor library: https://github.com/adafruit/Adafruit_Sensor
If you’re using web editor take a look at this topic: forum.arduino.cc/index.php?
topic=574940.msg3915277#msg3915277
Regards,
Sara
Reply
 Menu 
Dieter Kögler
February 14, 2019 at 11:04 am
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 Stu .Yor little Sister i like
to see so much as well.
Nice Regards from Germany
Reply
Sara Santos
Hi Dieter.
The link should be working ne: https://www.paypal.me/RuiFSantos
The best way to support our work is by getting one of our courses. Besides supporting our work, you
also get access to our exclusive resources to learn more.
You can nd our courses here: https://randomnerdtutorials.com/courses/
Thank you so much for supporting our work and I’m glad that you like our content.
Regards,
Sara
Reply
 Menu 
Nahireen
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
Reply
Sara Santos
February 20, 2019 at 5:11 pm
Hi.
I’m sorry, but I didn’t understand your question.
Regards,
Sara
Reply
 Menu 
Nisaar
April 30, 2019 at 6:58 pm
Nicely explained..Easy to understand..

Thanks
Reply
Rui Santos
May 1, 2019 at 10:41 am
Thanks for reading! I’m glad you found it helpful.
Reply
drake
June 6, 2019 at 7:15 am
 Menu 
i need help with displaying a bitmap image it keeps saying expected primary expression before display
refering to
and i dont know why. help would be appreciated.
Reply
Sara Santos
June 11, 2019 at 9:05 am
Hi.
Can you copy the exact error you’re getting?
Reply
ั
ชชวาลย์ เจียเจริญ
June 8, 2019 at 3:16 pm
your web infor. help me a lot , I can do many topics on OLED eg. scrolling text,Hello world ,draw shape,
Display DHT T ,RH But for display bitmap ,I Can’t get the picture on screen .
I think I have done something wrong on conversion process . the reason is
when I copy saraarray to sketch ,I can get the picture on OLED screen .
 Menu 
How to convert picture to 128×64 with 1024 pixels ?
Reply
Sara Santos
June 8, 2019 at 4:15 pm
Hi.
If you’re using windows, you can open your image in Paint. It has a resize option where you can
resize your image. You can also crop your image so that your have the same dimensions. You can
also try an online image resizer.
You also need to save your picture as monochrome bitmap format.
Regards,
Sara
Reply
chatchwal
June 9, 2019 at 2:58 am
 Menu 
Hi
thank you for your immediate response .
I think may be I do mistakes in photo le to C array conversion and did error in programming .
I use paint program to resize le to 128×64 and convert to C array ,copy code to sketch upload le and
get unexpected display on half part of screen , 4 column of small line .
in program part ,
your program “static const unsigned char PROGMEM image_data_Saraarray[1024] = { ” .
My program “static const uint8_t image_data_ta_eu_1c[400] = {” but I had mark ” // “to cancel this .
Can I have your email address to send conversion le ?
please help me
chat
Reply
Sara Santos
June 11, 2019 at 10:20 am
Hi.
To have your image displayed properly, it should be an array with 1024 size. Yours have 400.
You are probably doing something wrong in the conversion to C array. Are you using the same
program as described in the tutorial? sourceforge.net/projects/lcd-image-converter/ les/
Regards,
Sara
Reply
 Menu 
chatchwal
June 14, 2019 at 8:33 am
Hi
I use same program to convert
in my last conversion I can have 1024 size but the c array look strange
0x empty , 0x empty ,0x empty ,……
I don’t know why .
thanks
chat
Reply
chatchwal
June 14, 2019 at 8:37 am
Hi
I use same program to convert
in my last conversion I can have 1024 size but the c array look strange
0x empty , 0x empty ,0x empty ,……
I don’t know why .
thanks
 Menu 
chat
Reply
Sara Santos
June 14, 2019 at 6:13 pm
I’m sorry, but I don’t know what can be wrong.
Reply
Noman sarwar
July 19, 2019 at 6:11 am
Hi, can I use di erent colors to display the text like “BLUE” or “RED”?
Reply
 Menu 
Sara Santos
July 19, 2019 at 2:53 pm
Hi.
This OLED display is monochrome.
But there are other models that can display colors.
Regards,
Sara
Reply
JOSE GUSTAVO ABREU MURTA

July 28, 2019 at 10:56 pm
Rui e Sara,
Excellent tutorial. Complete and functional!
Thank you very much.
“Excelente tutorial. Completo e funcional!
Muito obrigado.”
Gustavo Murta
Reply
 Menu 
Rui Santos
July 29, 2019 at 3:42 pm
Thanks for reading!
Reply
JOSE GUSTAVO ABREU MURTA

August 17, 2019 at 1:34 am
Caro Rui Santos,

Baseando-me no seu excelente tutorial sobre OLED , desenvolvi um outro tutorial:
Sensor de nível de caixa d’água (Arduino) – sem o !
https://blog.eletrogate.com/sensor-de-nivel-de-caixa-dagua-sem- o/
Muito obrigado pelo compartilhamento do seu conhecimento!

Abraços além mar,
Gustavo Murta (Brasil)
Reply
 Menu 
Harry
Thanks, Rui & Sara! Your examples *always* work for me.
The equivalent examples at Adafruit are using their OLED, which is addressed di erently than just
about everything you’d get from eBay or Ali, and they never once mention changing the I2C address.
You not only warn about di erent addresses, you give us the I2C_scanner tool to gure out which one
we’ve bought. The address on mine didn’t match what’s printed on the bottom silkscreen (nor the
Adafruit default), so I’d have been running in circles with a blank display. VERY well thought-out
demonstrations.
(chuckling) Spell check messed you up: two di erent places above it says ‘monologue’ where you
meant ‘monochrome’.
Reply
Sara Santos
Hi Harry.
Thank you for your nice words.
Were you able to get your display working?

 Menu 
Thanks for telling me about the “monologue”. I haven’t noticed it, but it is xed now.
Regards,
Sara
Reply
Fausto Galanti
Congratulations guys, great tutorial !!

One question: can you use other pins than those set (A4 and A5) for i2c bus communication?
Reply
Sara Santos
September 21, 2019 at 9:36 am
Hi Frausto.
Yes. There are some libraries that do that.
For example: https://github.com/todbot/SoftI2CMaster
Regards,
 Menu 
Sara
Reply
mohammad
thank you!!!
that is very useful
thanks a lot
Reply
Pooja
October 31, 2019 at 5:58 pm
can we scroll text vertically ?
Reply
 Menu 
Sara Santos
November 5, 2019 at 6:31 pm
Yes.
You can do that. But we don’t have the function to do it.
Reply
reza
Hmm can it become colorful?

Can it show a painting with colors?
Reply
Sara Santos
 Menu 
Hi.
This OLED display model only displays black and white.
There are other models that can display colors, but not this one.
Regards,
Sara
Reply
Ron Mason
Great tutorial! Thank you for this.

Is it possible to display the Temperature in Fahrenheit?
Thanks again,
Ron
Reply
Sara Santos
 Menu 
Yes.
To read temperature in Fahrenheit use:
oat f = dht.readTemperature(true);
Regards,
Sara
Reply
Ron Mason
Thank you Sara! Much appreciated!
Ron
Reply
Ron Mason
 Menu 
Hi Sara,
I have one more question and my apologies for asking multiple questions.
I have one of the oled that are yellow and blue. Basically the temperature is displaying half yellow and
half blue. I know this is how these particular models are made, but is there any code I can use that
would possibly shift the letters lower on the screen or eliminate the yellow color in a sketch?
Thanks again,
Ron
Reply
Sara Santos
Hi Ron.
You can place the letter lower on the screen if you choose a di erent place to place the cursor to
start writing the text. Increase the y coordinate.
display.setCursor(x,y)
Regards,
Sara
Reply
 Menu 
dusko
Excellent tutorial–thank you. A small thing: in the picture showing the temperature and humidity, I
think that what is shown is not the degree sign (°), but something called “masculine ordinal indicator”
(ASCII 167). The degree sign is ASCII 248. (In some fonts they look the same.)
Reply
Sara Santos
December 28, 2019 at 11:24 am
Hi.
Yes, I think you’re right.
Thanks for sharing that. We’ll update the tutorial.
Regards,
Sara
Reply
 Menu 
Georg Berthelsen
January 7, 2020 at 2:34 pm
Thanks for a nice tutorial on OLED, but a signi cant section is missing! How do I replace the 0.96 inch
OLED display with a di erent size and controller? There are a great deal of sketches that are only
written for the 0.96 inch OLED display, but how can I replace this display with e.g. and 1.5 inch
128×128 SSD 1327 display?
* Is it necessary to write a new sketch?
* If the same sketch can be used, where should it be corrected and with what values?
* You can use the “Display Temperature and Humidity in the OLED Display with Arduino” sketch as an
example!
With best regards
Georg Berthelsen
Reply
Rohit
February 13, 2020 at 4:32 pm
Really amazing! I am 12 years old and I am able to do this as you explain it so well!
Reply
 Menu 
Sara Santos
That’s great!
Reply
Rodrigo Velazquez
March 22, 2020 at 5:49 am
Great!.
The OLED Display module include pull up resistors for i2c communication?
I’ll use a RTC DS3231 and OLED Display on the ESP32 in the same port i2c.
Reply
Sara Santos
March 22, 2020 at 12:32 pm
Hi Rodrigo.
 Menu 
They include the pull-up resistors for I2C.
You can connect them directly to the ESP32 I2C port. And yes, you can use the same port.
Learn more about I2C with the ESP32: https://randomnerdtutorials.com/esp32-i2c-communication-
arduino-ide/
Regards,
Sara
Reply
Eugenio Veloso E.
May 7, 2020 at 2:33 am
Great tutorial. Very clear and helpful. Step by step. Thanks for the e ort and all the info
Reply
Sara Santos
May 7, 2020 at 9:57 am
Thank you
Reply
 Menu 
Leave a Comment
Name *
Email *
Website
Notify me of follow-up comments by email.
Notify me of new posts by email.
Post Comment
 Menu 
Visit Maker Advisor – Tools and Gear for makers, hobbyists and DIYers »
 Menu 
Home Automation using ESP8266 eBook and video course » Build IoT and home automation projects.
Build a Home Automation System from Scratch » With Raspberry Pi, ESP8266, Arduino, and Node-RED.
 Menu 
About Support Terms Privacy Policy Refunds MakerAdvisor.com Join the Lab
Copyright © 2013-2020 · RandomNerdTutorials.com · All Rights Reserved

Exclusive Member of Mediavine Home

Guide For I2C OLED Display With Arduino - Random Nerd Tutorials

Uploaded by

Guide For I2C OLED Display With Arduino - Random Nerd Tutorials

Uploaded by

7/21/2020 Guide for I2C OLED Display with Arduino | Random Nerd Tutorials

Introducing the 0.96 inch OLED display

Pin wiring  Menu 

Pin Wiring to Arduino Uno

Nano: SDA (A4); SCL (A5);

4. After installing the libraries, restart your Arduino IDE.

Tips for writing text using these libraries

display.clearDisplay() – all pixels are o

display.print(“message”) – print the characters at location x,y

Testing the OLED Display

The following code should load:

#define SCREEN_WIDTH 128 // OLED display width, in pixels

// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

#define NUMFLAKES 10 // Number of snowflakes in the animation example

View raw code

#define OLED_RESET -1 // Reset pin # (or -1 if sharing Arduino reset pin)

Write Text – OLED Display  Menu 

“Hello, world!” OLED Display

#define SCREEN_WIDTH 128 // OLED display width, in pixels

// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3D for 128x64

View raw code

Let’s take a quick look on how the code works.

If your OLED display is not showing anything:

Check that the OLED display is properly wired to the Arduino

Initialize the OLED display

#define SCREEN_WIDTH 128 // OLED display width, in pixels

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

Initialize the OLED display with the begin() method as follows:

Serial.println("SSD1306 allocation failed");

Clear display, set font size, color and write text

Set the font size using the setTextSize() method:

Set the font color with the setTextColor() method:

WHITE sets white font and black background.

startscrollright(0x00, 0x0F) : scroll text from left to right

startscrollleft(0x00, 0x0F) : scroll text from right to left

The following sketch implements those methods.

#define SCREEN_WIDTH 128 // OLED display width, in pixels

// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3D for 128x64

View raw code

The text scrolls as shown in the following short video.

Using Other Fonts – OLED Display

You can chose from the next selection of fonts:

Upload the next sketch to your board:

#define SCREEN_WIDTH 128 // OLED display width, in pixels

// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

View raw code

Draw Shapes in the OLED Display

display.drawPixel(64, 32, WHITE);

display.drawLine(0, 0, 127, 20, WHITE);

display.drawRect(10, 10, 50, 30, WHITE);

display.drawRoundRect(10, 10, 30, 50, 2, WHITE);

Or a lled round rectangle:

display.fillRoundRect(10, 10, 30, 50, 2, WHITE);

display.drawCircle(64, 32, 10, WHITE);

display.fillCircle(64, 32, 10, WHITE);

display.drawTriangle(10, 10, 55, 20, 5, 40, WHITE);

Use the fillTriangle() method to draw a lled triangle.

display.fillTriangle(10, 10, 55, 20, 5, 40, WHITE);

If you call the following command after de ning the triangle:

You’ll get an inverted triangle as follows:

Code – Draw Shapes

#define SCREEN WIDTH 128

// Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)

// Clear the buffer

View raw code

Display Bitmap Images in the OLED

Type: Monochrome, Threshold Dither

Go to the Image tab and select the following options:

In our case, this is the array that we get:

static const uint8_t image_data_Saraarray[1024] = {

View raw code

where the image starts to be displayed.

#define SCREEN_WIDTH 128