ESP32 Arduino: Interacting with a SSD1306 OLED display

The objective of this post is to explain how to connect the ESP32 to a SSD1306 OLED display and print a “Hello World” message, using the Arduino core. For this tutorial, an Elecrow’s version of the OLED was used. The ESP32 board used was a NodeMCU.

 

Introduction

The objective of this post is to explain how to connect the ESP32 to a SSD1306 OLED display and show a “Hello World” message, using the Arduino core.

In order to facilitate the interaction with the display, we will need to install a library that supports the mentioned display model and can be used on the ESP32. You can check below at figure 1 the library, which can be installed via Arduino IDE library manager.

You can check here the GitHub page of the library, which details the API available to interact with the display.

Figure 1 – Installing the OLED library.

For this tutorial an Elecrow’s version of the OLED was used. The display can be bought here. It can also be obtained as part of this starter kit. The ESP32 board used was a NodeMCU.

 

Electric diagram

The ESP32 will interact with the SSD1306 display via I2C. Thus, besides the power supply, we will only need two wires between the devices.

The electric diagram can be seen below at figure 2. We are using the ESP32 pins 21 and 22 as I2C SDA and SCL, respectively.

Since the SSD1306 can operate at 3.3 V, we can use the the 3.3 V supply pin that most ESP32 boards have to power the display.

Please note that depending on your development board, the names or numbers labeled  on the pins may not directly match with the ones of the ESP32 microcontroller. You should consult the pin mapping of your board to confirm, before proceeding with the actual connections.

Figure 2 – Electric diagram between the ESP32 and the SSD1306 OLED display.

The code

The code for this tutorial will be very simple since the library we have just installed has a very easy to use API.

To get started, we will need to include the Wire.h library, which is needed for the I2C communication with the OLED display. We will also need to include the SSD1306.h library, which we will use to interact with the device.

#include <wire.h>
#include "SSD1306.h"

Next, we will need to declare an object of class SSD1306, which will make available the functions needed to draw in the display. We will call this object display.

The constructor for the mentioned class receives as first parameter the I2C address of the device, which is 0x3c. As second and third parameters, the constructor receives the number of the SDA and SCL pins, respectively. In our case, as shown in the schematic diagram, we are using pins 21 and 22 of the ESP32.

 
SSD1306 display(0x3c, 21, 22); 

Now, on the setup function, we will initialize the display by calling the init method of the display object. This method receives no arguments and returns void.

display.init();

Next we can start drawing on the display. For this simple example, we will draw a very simple “Hello World” message. To do so, we can call the drawString method of the display object.

This method receives as first and second arguments the x and y coordinates where the string will be drawn on the display, and as third argument it receives a String with the actual content.

 
display.drawString(0, 0, "Hello World");

Finally, to send the content to the display to be effectively drawn, we need to call the display method on our object. This method receives no parameters.

display.display();

Since we are not going to change the content of the display, we may leave an empty Arduino loop function. The string we just drawn will then stay on the display as long as it is connected. The final source code can be seen below.

#include <Wire.h>
#include "SSD1306.h" 

SSD1306  display(0x3c, 21, 22);

void setup() {

  display.init();
  display.drawString(0, 0, "Hello World");
  display.display();
}

void loop() {}

Testing the code

To test the code, simply compile it and upload it to your ESP32 board using the Arduino IDE, after performing the connections specified in the diagram of figure 1.

Upon execution of the program, the “Hello World” message should appear on your display, as shown in figure 3.

Figure 3 – Hello World message drawn on the display.