Skip to content

🧭 TUAS Electrical Onboarding Workshop — OLED Display

This guide will walk you through your first embedded task: displaying text on an SSD1306 OLED using an ESP32-WROOM-DA board.

Objectives Met: Soldering (possibly), circuit theory, Arduino code, datasheet understanding.

The display connects to the ESP32 over I2C, a common communication protocol for embedded devices. You can learn more about how they work in our wiki.

In this workshop, we won't be writing code for I2C directly. We will instead use the Adafruit display driver, which handles the data parsing and communcation part for us, leaving us with an abstracted function call for ease of use. But under the hood, it still uses I2C.

🧩 1. ESP32–OLED Pinout Diagram

| OLED Pin  | ESP32 Pin  | Description        |
|-----------|------------|--------------------|
| **VCC**   | 3.3V       | Power supply       |
| **GND**   | GND        | Ground             |
| **SCL**   | GPIO 22    | I2C Clock          |
| **SDA**   | GPIO 21    | I2C Data           |

Wiring Diagram (Example) 

SSD1306 OLED ESP32-WROOM-DA

VCC <------------> 3.3V
GND <------------> GND
SCL <------------> GPIO 22
SDA <------------> GPIO 21

🧰 2. Environment Setup

Follow the TUAS Arduino IDE Setup Guide to install the Arduino IDE and set up your environment.

Once installed: 1. Open Arduino IDE
2. Go to Tools → Board → ESP32 Arduino → ESP32-WROOM-DA
3. Select the correct COM port (You can check this by unplugging and replugging the board, to see which one it is)

📦 3. Install Required Libraries

Open Tools → Manage Libraries, then search for and install:

  • Adafruit SSD1306
  • Adafruit GFX Library

These provide functions for text, shapes, and images on the OLED display.

💻 4. Code Walkthrough

Let’s go step-by-step through the example program.

Step 1: Include the Required Libraries

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
- Wire.h enables I2C communication. - Adafruit_GFX.h provides text and shape drawing functions. - Adafruit_SSD1306.h is the driver for the OLED display.

Step 2: Define Display Parameters

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
  • The display is 128x64 pixels.
  • OLED_RESET is set to -1 since it shares the ESP32’s hardware reset line.
  • The display object controls the OLED.

Step 3: Initialize the Display in setup()

    Serial.begin(115200); // This begin serial connection from the board to your computer, to send messages

    if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println(F("SSD1306 allocation failed"));
    for (;;);
    }
- Initializes the display with the I2C address 0x3C (typical for 128x64 OLEDs). - If initialization fails, it loops forever — useful for debugging connection issues.

Step 4: Prepare the Display

    delay(2000);

    display.clearDisplay();
    display.setTextSize(1);
    display.setTextColor(SSD1306_WHITE);
    display.setCursor(0, 0);
  • Waits 2 seconds for power stabilization.
  • Clears any previous data on the screen.
  • Sets text size, color, and cursor position.

Step 5: Print Text to the OLED

    display.println("Hello, ESP32!");
    display.println("I2C OLED Display");
    display.display();
  • println() adds text to the buffer.
  • display.display() sends the buffer to the screen.
  • The Adafruit_SSD1306 driver handles taking in the data, and sending it to the display to the right pixels for us

Step 6: Loop Function

void loop() {
  // Nothing needed here for now

  // You can add something here as per your which, to create an animation, or scrolling text, etc...
}

✅ 5. Expected Output

After uploading the code, your OLED should show:

Hello, ESP32!
I2C OLED Display

If you don’t see anything: - Check your wiring (SDA/SCL swapped is common) - Verify the display address (0x3C or 0x3D) using an I2C scanner - Ensure libraries are installed correctly

🚀 Next Steps

Once you get this working, try: - Changing text size or position - Displaying sensor data over I2C - Animating text or graphics