Driving OLED Display with NodeMCU (ESP8266)

The OLED display is one of the most important output devices in the electronic world and is widely used in embedded devices, mobile phones, TVs, and other electronic products. The main difference between OLED and LCD displays is that OLED does not require a backlight, making it more energy-efficient. Today, we will learn how to drive an OLED display using NodeMCU (ESP8266) and display content.

There are many different specifications of OLED displays available in the market, such as color, pin count, driver chip, and screen resolution. Common OLEDs include monochrome blue, monochrome white, and yellow-blue options. In terms of communication protocols, there are mainly two: I2C and SPI. If you are not familiar with communication protocols, you can refer to “Three Common Communication Protocols: UART, I2C, and SPI”. The I2C protocol OLED typically has 4 pins, while versions that support both SPI and I2C usually have 7 pins.

In this tutorial, we will use the SSD1306 model single white display with a 4-pin I2C protocol, measuring 0.96 inches and having a resolution of 128×64.

Hardware Connections

The four pins of the I2C version OLED are GND, VCC, and the I2C pins SCL (clock line) and SDA (data line). Connecting to NodeMCU is also very simple, as the default I2C pins for NodeMCU/ESP8266 are GPIO5 (SCL) and GPIO4 (SDA), just connect them accordingly. It’s that simple.

Installing Dependency Libraries

To drive the OLED screen, we need to install a few dependency libraries. Before installing the libraries, please ensure that your Arduino IDE is configured with the toolchain that supports ESP8266. If you are unsure how to configure it, please refer to “Lighting Up LEDs: How to Program NodeMCU with Arduino IDE” for specific steps.

Open the Arduino IDE, go to Sketch > Include Library > Manage Libraries to open the library manager tool, search for “SSD1306” and install it:

After installing the SSD1306 library, search for “GFX” and install the Adafruit GFX library:

After installing these two libraries, restart the Arduino IDE. These two libraries encapsulate the OLED driver program and many functions for displaying content on the OLED, allowing us to benefit from others’ work.

Displaying Hello, World!

Next, we can display content on the screen. Enter the following code in the Sketch:

#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)
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

void setup() {  Serial.begin(115200);
  if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3D for 128x64    Serial.println(F("SSD1306 allocation failed"));    for(;;);  }  delay(2000);  display.clearDisplay();
  display.setTextSize(1);  display.setTextColor(WHITE);  display.setCursor(0, 10);  // Display static text  display.println("Hello, world!");  display.display(); }
void loop() {}

Here we will explain the code line by line.

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

These three lines include the dependency libraries; Wire is for I2C, and GFX and SSD1306 are the two libraries we just installed.

#define SCREEN_WIDTH 128 // OLED display width, in pixels
#define SCREEN_HEIGHT 64 // OLED display height, in pixels

Then we define the width and height of the display content, which corresponds to the size of the OLED screen, 128×64.

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

Initialize the screen instance, requiring the width, height, I2C, and the last -1 represents the RESET pin of the OLED. If your OLED has a RESET pin, you should connect it to the corresponding NodeMCU pin and input the pin name here. If there is usually no RESET pin, just fill in -1.

Serial.begin(115200);

Initialize the serial output with a baud rate of 115200.

if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3D for 128x64    Serial.println(F("SSD1306 allocation failed"));    for(;;);  }

Here we start connecting to the OLED screen, where 0x3C is the I2C address of the OLED. If the connection fails, the message “SSD1306 allocation failed” will be displayed on the serial monitor.

display.clearDisplay();

Once connected successfully, we can use the GFX function clearDisplay to clear the screen.

display.setTextSize(1);  display.setTextColor(WHITE);  display.setCursor(0, 10);

Then we set some properties for the displayed content, such as font size, font color, and the starting display coordinates (0,10).

After setting up, we can display the content.

display.println("Hello, world!");display.display();

After uploading the code, we will see the OLED display showing “Hello World!”.

Displaying Geometric Shapes

The GFX graphics library also supports quickly displaying several basic shapes, such as points, lines, rectangles, circles, triangles, etc.

Point:

display.drawPixel(64, 32, WHITE);

Line:

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

Rectangle:

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

Filled Rectangle:

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

Rounded Filled Rectangle:

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

Circle:

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

Displaying Different Fonts

In addition to setting different font sizes, colors, and positions, GFX also supports different fonts. However, most fonts are still in English.

For example, if we want to use the FreeSerif12pt7b font, we first need to include it at the top:

#include <Fonts/FreeSerif12pt7b.h>

Then when displaying, we also need to use setFont() to apply it:

display.setFont(&FreeSerif12pt7b);

Complete Code:

#include <Wire.h>#include <Adafruit_GFX.h>#include <Adafruit_SSD1306.h>#include <Fonts/FreeSerif9pt7b.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)
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

void setup() {  Serial.begin(115200);
  if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {     Serial.println("SSD1306 allocation failed");    for(;;);  }  delay(2000);
  display.setFont(&FreeSerif9pt7b);  display.clearDisplay();  display.setTextSize(1);               display.setTextColor(WHITE);          display.setCursor(0,20);               display.println("Hello, world!");  display.display();  delay(2000); }
void loop() { }

After uploading, we will see different fonts.

Displaying Chinese Characters and Bitmaps

What if you want to display Chinese characters? Due to the special nature of Chinese characters, they cannot be used directly like English fonts. Chinese font libraries are generally quite large and often exceed the storage size of microcontrollers. A common approach is to draw Chinese characters as bitmaps. The Adafruit GFX graphics library also provides the drawBitmap() function for displaying bitmaps.

First, we need to convert the bitmap we want to display into an array. There are many online tools that can help us with this:

http://javl.github.io/image2cpp/

For example, if we want to display this avatar:

After uploading, a bitmap array will be automatically generated.

Then we write the generated bitmap array into the code:

#include <Wire.h>#include <Adafruit_GFX.h>#include <Adafruit_SSD1306.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64

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

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, 0xf0, 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,     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, 0x80, 0x00, 0x00, 0x00, 0x00, 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, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1f, 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,     0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0xff, 0x80, 0x00, 0x0b, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xf0, 0x0f, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0x80, 0x07, 0xff, 0xff, 0xff, 0xf0, 0x0f, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0f, 0x07, 0xff, 0xf8, 0xf8, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x0e, 0x01, 0xff, 0xc0, 0x38, 0x07, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x1c, 0x46, 0xff, 0xb1, 0x18, 0x07, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x3f, 0x97, 0xff, 0xc0, 0x7a, 0x07, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xfe, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfe, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xfe, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfe, 0x01, 0x3f, 0xff, 0xff, 0xff, 0xfe, 0x01, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfe, 0x01, 0xbf, 0xff, 0xff, 0xff, 0xfe, 0x81, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0xbf, 0xff, 0xff, 0xff, 0xfc, 0x81, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0xff, 0xff, 0xfe, 0xff, 0xfd, 0x83, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0xbf, 0xff, 0xfe, 0xff, 0xfd, 0x01, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff, 0x01, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xfb, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x3f, 0xff, 0xdc, 0xff, 0xfa, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xd8, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xf8, 0x03, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xd0, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xf8, 0x01, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x90, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xf8, 0x02, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xb0, 0x00, 0x0f, 0xf5, 0xff, 0xd7, 0xf8, 0x01, 0xff, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xb0, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xf8, 0x00, 0x5f, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xa0, 0x00, 0x0f, 0xfb, 0xff, 0xff, 0xf0, 0x00, 0x3f, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x0f, 0xfd, 0xff, 0xdf, 0xf0, 0x00, 0x3f, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x07, 0xff, 0xff, 0xbf, 0xf0, 0x00, 0x0f, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x07, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x87, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x03, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x43, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x60, 0x00, 0x01, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x73, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfe, 0xe0, 0x00, 0x00, 0xff, 0xff, 0xff, 0x80, 0x00, 0x7b, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfd, 0xe0, 0x00, 0x00, 0x7f, 0xff, 0xfe, 0x00, 0x00, 0x33, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfd, 0xe0, 0x00, 0x00, 0x3f, 0xff, 0xf8, 0x00, 0x00, 0x27, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0xe0, 0x00, 0x00, 0x0f, 0xff, 0xf0, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x60, 0x00, 0x00, 0x67, 0xff, 0xe0, 0x00, 0x00, 0x1b, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfd, 0x40, 0x00, 0x00, 0xf3, 0xff, 0xc4, 0x00, 0x00, 0x0b, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfe, 0x80, 0x00, 0x00, 0xfc, 0xff, 0x8c, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x7f, 0x3c, 0x3c, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x3f, 0xc0, 0x7c, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff,     0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xfc, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff}; 
void setup() {  Serial.begin(115200);   if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {    Serial.println(F("SSD1306 allocation failed"));    for(;;);  }  delay(2000); // Pause for 2 seconds   // Clear the buffer.  display.clearDisplay();    // Draw bitmap on the screen  display.drawBitmap(0, 0, image_data_Saraarray, 128, 64, 1);  display.display();}
void loop() {}

After burning the program, we can display the bitmap.

Similarly, to display Chinese characters, we can save the characters as images, generate the corresponding bitmap arrays, and then reference them in the code. We will not practice that here.

Thus, we have a basic understanding of how to drive an OLED display using NodeMCU/ESP8266 and how to use the functions encapsulated by the Adafruit GFX graphics library to display different content. With the IoT capabilities of NodeMCU, you can combine OLED to implement many interesting projects, such as network weather forecasts, displaying different time zones, fan counters, etc. We will introduce more in the future.

Leave a Comment Cancel reply