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.

ESP32 Arduino SSD1306 OLED display library.png

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.

ESP32 Arduino OLED SSD1306 Schematic I2C

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.

ESP32 Arduino OLED SSD1306 Hello World.jpg

Figure 3 – Hello World message drawn on the display.

Advertisements
This entry was posted in ESP32 and tagged , , , , . Bookmark the permalink.

9 Responses to ESP32 Arduino: Interacting with a SSD1306 OLED display

  1. Pingback: ESP32 Arduino: Interacting with a SSD1306 OLED display – Arduino Boards News

  2. Dan says:

    Hi,

    Thanks for sharing, there are some very nifty ESP32 based dev boards, that come directly with a SSD1306 OLED on them, like the one I use on one of my latest projects: https://trandi.wordpress.com/2017/11/16/thermal-printer-remotely-controlled-through-an-esp32/

    These are currently my preferred / go to boards, given how cheap they are and how much you get in the package !

    Dan

    Liked by 1 person

    • antepher says:

      Hi Dan,

      Thank you very much for sharing with us 🙂

      It is indeed a very good ideia to integrate the display in the board so we don’t need to worry about wiring.

      Hopefully we keep seeing new boards that already include some extra peripherals.

      Best regards,
      Nuno Santos

      Like

  3. Pingback: ESP32 Arduino SSD1306 OLED: Redrawing a string | techtutorialsx

  4. Pingback: ESP32 Arduino SSD1306 OLED: Redrawing a string – Arduino Boards News

  5. julian flores santervas says:

    Hola que bien explicado esta, hasta los novatos como yo nos queda bastante claro, gracias por compartir sabiduría y un saludo

    Liked by 1 person

  6. julian flores santervas says:

    Perdona, los novatos como yo

    Liked by 1 person

  7. Pingback: ESP32 Arduino SSD1306 OLED: Drawing a QR Code | techtutorialsx

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s