ESP8266 - OLED

This tutorial instructs you how to use ESP8266 with OLED display. In detail, we will learn:

Hardware Preparation

1×ESP8266 NodeMCU
1×Micro USB Cable
1×SSD1306 I2C OLED Display 128x64
1×Jumper Wires
1×(Optional) 5V Power Adapter for ESP8266
1×(Optional) ESP8266 Screw Terminal Adapter

Or you can buy the following sensor kit:

1×DIYables Sensor Kit 30 types, 69 units
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you. We appreciate your support.

Overview of OLED Display

There are various kinds of OLED displays available. The most common-used OLED with ESP8266 is the SSD1306 I2C OLED 128x64 and 128x32 display.

OLED display

I2C OLED Display Pinout

  • GND pin: should be connected to the ground of ESP8266.
  • VCC pin: is the power supply for the display which should be connected to the 3.3V or 5V.
  • SCL pin: is a serial clock pin for I2C interface.
  • SDA pin: is a serial data pin for I2C interface.
OLED pinout

※ NOTE THAT:

  • The pins of an OLED module can differ across manufacturers and module types. It is essential to always refer to the labels printed on the OLED module. Pay attention!
  • This tutorial uses the OLED display that has the SSD1306 I2C driver. We have tested it with the OLED display from DIYables and it works perfectly.

Wiring Diagram

  • Wiring diagram between ESP8266 and OLED 128x64
The wiring diagram between ESP8266 NodeMCU and OLED

This image is created using Fritzing. Click to enlarge image

See more in ESP8266's pinout and how to supply power to the ESP8266 and other components.

  • Wiring diagram between ESP8266 and OLED 128x32
The wiring diagram between ESP8266 NodeMCU and OLED 128x64

This image is created using Fritzing. Click to enlarge image

The wiring table between ESP8266 and OLED display:

OLED Module ESP8266
Vin 3.3V
GND GND
SDA D2 (GPIO4)
SCL D1 (GPIO5)

How To Use OLED with ESP8266

Install SSD1306 OLED library

  • Click to the Libraries icon on the left bar of the Arduino IDE.
  • Search for “SSD1306” and locate the SSD1306 library from Adafruit.
  • Then, press the Install button to complete the installation.
ESP8266 NodeMCU OLED library
  • You will be prompted to install some other library dependencies.
  • To install all of them, click the Install All button.
ESP8266 NodeMCU Adafruit GFX sensor library

How to program for OLED

  • Include the library
#include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h>
  • Specify the dimensions of the OLED screen as 128 x 64.
#define OLED_WIDTH 128 // OLED display width, in pixels #define OLED_HEIGHT 64 // OLED display height, in pixels
  • Specify the dimensions of an OLED display that is 128x32.
#define OLED_WIDTH 128 // OLED display width, in pixels #define OLED_HEIGHT 32 // OLED display height, in pixels
  • Create an object of type SSD1306 OLED.
// declare an SSD1306 display object connected to I2C Adafruit_SSD1306 oled(OLED_WIDTH, OLED_HEIGHT, &Wire, -1);
  • In the setup() function, initiate the OLED display.
// initialize OLED display with address 0x3C for 128x64 if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { Serial.println(F("SSD1306 allocation failed")); while (true); }
  • Then, you can show text, pictures, and create lines...

Going forward, all codes are for OLED 128x64, but it can be adapted to OLED 128x32 by altering the screen size and adjusting coordinates if necessary.

ESP8266 Code - Display Text on OLED

/* * This ESP8266 NodeMCU code was developed by newbiely.com * * This ESP8266 NodeMCU code is made available for public use without any restriction * * For comprehensive instructions and wiring diagrams, please visit: * https://newbiely.com/tutorials/esp8266/esp8266-oled */ #include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> #define OLED_WIDTH 128 // OLED width, in pixels #define OLED_HEIGHT 64 // OLED height, in pixels // create an OLED display object connected to I2C Adafruit_SSD1306 oled(OLED_WIDTH, OLED_HEIGHT, &Wire, -1); void setup() { Serial.begin(9600); // initialize OLED display with I2C address 0x3C if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { Serial.println(F("failed to start SSD1306 OLED")); while (1); } delay(2000); // wait two seconds for initializing oled.clearDisplay(); // clear display oled.setTextSize(1); // set text size oled.setTextColor(WHITE); // set text color oled.setCursor(0, 10); // set position to display oled.println("esp32io.com"); // set text oled.display(); // display on OLED } void loop() { }

Here are some functions that can be used to display text on the OLED:

  • oled.clearDisplay(): all pixels are off.
  • oled.drawPixel(x,y, color): plot a pixel in the x,y coordinates.
  • oled.setTextSize(n): set the font size, supports sizes from 1 to 8.
  • oled.setCursor(x,y): set the coordinates to start writing text.
  • oled.setTextColor(WHITE): set the text color.
  • oled.setTextColor(BLACK, WHITE): set the text color, background color.
  • oled.println(“message”): print the characters.
  • oled.println(number): print a number.
  • oled.println(number, HEX): print a number IN hex format.
  • oled.display(): call this method for the changes to make effect.
  • oled.startscrollright(start, stop): scroll text from left to right.
  • oled.startscrollleft(start, stop): scroll text from right to left.
  • oled.startscrolldiagright(start, stop): scroll text from left bottom corner to right upper corner.
  • oled.startscrolldiagleft(start, stop): scroll text from right bottom corner to left upper corner.
  • oled.stopscroll(): stop scrolling.

How to vertical and horizontal center align text/number on OLED

To learn about centering text and numbers on OLED, please refer to How to vertical/horizontal center on OLED. If you would like to know how to center text and numbers on OLED, take a look at How to vertical/horizontal center on OLED.

ESP8266 Code - Drawing on OLED

/* * This ESP8266 NodeMCU code was developed by newbiely.com * * This ESP8266 NodeMCU code is made available for public use without any restriction * * For comprehensive instructions and wiring diagrams, please visit: * https://newbiely.com/tutorials/esp8266/esp8266-oled */ #include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> #define OLED_WIDTH 128 // OLED width, in pixels #define OLED_HEIGHT 64 // OLED height, in pixels // create an OLED display object connected to I2C Adafruit_SSD1306 oled(OLED_WIDTH, OLED_HEIGHT, &Wire, -1); void setup() { Serial.begin(9600); // initialize OLED display with I2C address 0x3C if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { Serial.println(F("failed to start SSD1306 OLED")); while (1); } delay(2000); // wait two seconds for initializing oled.setCursor(0, 0); } void loop() { // draw a circle oled.clearDisplay(); oled.drawCircle(20, 35, 20, WHITE); oled.display(); delay(1000); // fill a circle oled.clearDisplay(); oled.fillCircle(20, 35, 20, WHITE); oled.display(); delay(1000); // draw a triangle oled.clearDisplay(); oled.drawTriangle(30, 15, 0, 60, 60, 60, WHITE); oled.display(); delay(1000); // fill a triangle oled.clearDisplay(); oled.fillTriangle(30, 15, 0, 60, 60, 60, WHITE); oled.display(); delay(1000); // draw a rectangle oled.clearDisplay(); oled.drawRect(0, 15, 60, 40, WHITE); oled.display(); delay(1000); // fill a rectangle oled.clearDisplay(); oled.fillRect(0, 15, 60, 40, WHITE); oled.display(); delay(1000); // draw a round rectangle oled.clearDisplay(); oled.drawRoundRect(0, 15, 60, 40, 8, WHITE); oled.display(); delay(1000); // fill a round rectangle oled.clearDisplay(); oled.fillRoundRect(0, 15, 60, 40, 8, WHITE); oled.display(); delay(1000); }

ESP8266 Code – Display Image

In order to display an image on the OLED, we must first convert it from its original format into a bitmap array. This can be done by using the online tool provided. The following image shows how to convert an image into a bitmap array. As an example, I have converted the Arduino icon into a bitmap array.

image to bitmap array

Once the conversion is complete, take the array code and replace the ArduinoIcon array in the code below with it.

/* * This ESP8266 NodeMCU code was developed by newbiely.com * * This ESP8266 NodeMCU code is made available for public use without any restriction * * For comprehensive instructions and wiring diagrams, please visit: * https://newbiely.com/tutorials/esp8266/esp8266-oled */ #include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> #define OLED_WIDTH 128 // OLED width, in pixels #define OLED_HEIGHT 64 // OLED height, in pixels // create an OLED display object connected to I2C Adafruit_SSD1306 oled(OLED_WIDTH, OLED_HEIGHT, &Wire, -1); // bitmap of arduino-icon image const unsigned char arduino_icon [] PROGMEM = { // 'arduino-icon', 128x64px 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x80, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x07, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0x03, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xf0, 0x00, 0x00, 0xff, 0xfc, 0x00, 0x00, 0x3f, 0xfc, 0x00, 0x00, 0xff, 0xfc, 0x00, 0x03, 0xff, 0xfc, 0x00, 0x00, 0x7f, 0xf8, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff, 0xf8, 0x00, 0x0f, 0xff, 0xff, 0x00, 0x00, 0x3f, 0xf0, 0x00, 0x03, 0xff, 0xff, 0xc0, 0x00, 0x7f, 0xf0, 0x00, 0x1f, 0xff, 0xff, 0xc0, 0x00, 0x1f, 0xe0, 0x00, 0x0f, 0xff, 0xff, 0xe0, 0x00, 0x7f, 0xf0, 0x00, 0x7f, 0xff, 0xff, 0xe0, 0x00, 0x0f, 0xc0, 0x00, 0x1f, 0xff, 0xff, 0xf8, 0x00, 0x3f, 0xe0, 0x00, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x07, 0x80, 0x00, 0x7f, 0xff, 0xff, 0xfc, 0x00, 0x1f, 0xe0, 0x00, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x03, 0x80, 0x00, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x1f, 0xc0, 0x01, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x03, 0x00, 0x01, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x1f, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0f, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x07, 0xff, 0xf0, 0x7f, 0xff, 0x00, 0x0f, 0xc0, 0x07, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x0f, 0xff, 0xf0, 0x7f, 0xff, 0x80, 0x0f, 0x80, 0x07, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x1f, 0xff, 0xf0, 0x7f, 0xff, 0x80, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x3f, 0xff, 0xf0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x7f, 0xff, 0xf0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xfe, 0x00, 0x00, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xfc, 0x00, 0x03, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xfe, 0x00, 0x00, 0xff, 0xfe, 0x00, 0x01, 0xff, 0xfc, 0x00, 0x01, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xfe, 0x00, 0x00, 0xff, 0xff, 0x00, 0x03, 0xff, 0xfc, 0x00, 0x01, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xfe, 0x00, 0x00, 0xff, 0xff, 0x00, 0x03, 0xff, 0xfc, 0x00, 0x01, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xfe, 0x00, 0x00, 0xff, 0xff, 0x00, 0x03, 0xff, 0xfc, 0x00, 0x01, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x01, 0xff, 0xff, 0xe0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xff, 0xf0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xff, 0xf0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x7f, 0xff, 0xf0, 0x7f, 0xff, 0xc0, 0x07, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x3f, 0xff, 0xf0, 0x7f, 0xff, 0x80, 0x07, 0x80, 0x07, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x1f, 0xff, 0xf0, 0x7f, 0xff, 0x80, 0x07, 0xc0, 0x07, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0x80, 0x0f, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0f, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0f, 0xe0, 0x01, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x03, 0x00, 0x01, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x1f, 0xe0, 0x00, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x07, 0x80, 0x00, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x1f, 0xe0, 0x00, 0x7f, 0xff, 0xff, 0xf0, 0x00, 0x0f, 0xc0, 0x00, 0x3f, 0xff, 0xff, 0xf8, 0x00, 0x3f, 0xf0, 0x00, 0x3f, 0xff, 0xff, 0xe0, 0x00, 0x1f, 0xe0, 0x00, 0x1f, 0xff, 0xff, 0xf0, 0x00, 0x3f, 0xf8, 0x00, 0x1f, 0xff, 0xff, 0x80, 0x00, 0x3f, 0xe0, 0x00, 0x07, 0xff, 0xff, 0xe0, 0x00, 0x7f, 0xf8, 0x00, 0x0f, 0xff, 0xff, 0x00, 0x00, 0x7f, 0xf8, 0x00, 0x03, 0xff, 0xff, 0xc0, 0x00, 0x7f, 0xfc, 0x00, 0x03, 0xff, 0xf8, 0x00, 0x00, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff, 0xfe, 0x00, 0x00, 0x7f, 0xe0, 0x00, 0x01, 0xff, 0xfe, 0x00, 0x00, 0x1f, 0xf8, 0x00, 0x01, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x07, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff }; void setup() { Serial.begin(9600); // initialize OLED display with I2C address 0x3C if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { Serial.println(F("failed to start SSD1306 OLED")); while (1); } delay(2000); // wait two seconds for initializing oled.setCursor(0, 0); } void loop() { oled.clearDisplay(); // display bitmap oled.drawBitmap(0, 0, arduino_icon, 128, 64, WHITE); oled.display(); delay(1000); // invert display oled.invertDisplay(1); delay(1000); }

※ NOTE THAT:

  • The size of the image should not exceed the size of the screen.
  • If you want to use the code for an OLED 128x32, you must resize the image and alter the width and height in the oled.drawBitmap(); function.

OLED Troubleshooting

Verify that the OLED is functioning properly by following these steps:

  • Ensure that your wiring is correct.
  • Confirm that your I2C OLED utilizes the SSD1306 Driver.
  • Utilize the I2C Address Scanner code on ESP8266 to check the I2C address of the OLED.
// I2C address scanner program #include <Wire.h> void setup() { Wire.begin(); Serial.begin(9600); Serial.println("I2C Scanner"); } void loop() { byte error, address; int nDevices; Serial.println("Scanning..."); nDevices = 0; for (address = 1; address < 127; address++ ) { Wire.beginTransmission(address); error = Wire.endTransmission(); if (error == 0) { Serial.print("I2C device found at address 0x"); if (address < 16) Serial.print("0"); Serial.print(address, HEX); Serial.println(" !"); nDevices++; } else if (error == 4) { Serial.print("Unknown error at address 0x"); if (address < 16) Serial.print("0"); Serial.println(address, HEX); } } if (nDevices == 0) Serial.println("No I2C devices found"); else Serial.println("done"); delay(5000); // wait 5 seconds for next scan }

The output displayed on the Serial Monitor is: . The Serial Monitor shows the following result:

COM6
Send
Scanning... I2C device found at address 0x3C ! done Scanning... I2C device found at address 0x3C ! done
Autoscroll Show timestamp
Clear output
9600 baud  
Newline