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.



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.


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.


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.drawString(0, 0, "Hello World");

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.


18 Replies to “ESP32 Arduino: Interacting with a SSD1306 OLED display”

    1. 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


    1. Hi!

      Thanks 🙂 I try to keep the code at the minimum indispensable for a given functionality so people can focus on the basics and then build more complex applications on top of it, taking into account their requirements.

      I will try to keep this approach on future tutorials 🙂

      Best regards,
      Nuno santos


  1. Love the idea of super simple to get it to work. This way you’re not troubleshooting a whole bunch of code trying to figure out what the problem is.

    I’m using a TTGO Development board that has OLED, and an 18650 battery holder on the back,
    Of course the SDA and SCL lines are on pins 5 and 4. So I had to change it to:
    SSD1306 display(0x3c, 5, 4);

    So now it’s running and I can build on it. Thanks.
    73, Michael

    Liked by 1 person

    1. Hi Michael,

      Thank you very much for the feedback, I’m very happy to know this tutorial was useful :).

      I try to follow that approach to explain the basic functionalities and then let the readers build their applications on top of it.

      When I’m testing code samples with lots of stuff beyond what I need, the first thing I do is start to cut unnecessary lines until getting the bare minimum working example.

      This is why I’ve opted for this minimum working code approach and I’m very happy to know people are finding it useful and easy to understand 🙂

      I’ve heard about those boards but haven’t yet had the time to test any, need to take some time to do it. They seem very interesting since they already incorporate the display.

      Best regards,
      Nuno Santos


  2. Nuno, parabéns pelo tutorial !

    Testei com o exemplo da Biblioteca – SSD1306SimpleDemo. Mostra textos e figuras bem interessantes.
    Usei dessa forma e funcionou OK.
    #include “SSD1306Wire.h”
    SSD1306Wire display(0x3c, 21, 22);

    Gustavo Murta (Brasil)

    Liked by 1 person

Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s