OLED Display with ESP32

TIMEEstimated Time

LEVELDifficulty

PREPrerequisites

• Analog Inputs You should understand how the ESP32 reads changing values before showing those values on a display.

SKILLSkills You'll Learn

• Explain what an OLED display is
• Wire an SSD1306 I2C OLED to the ESP32 default I2C pins
• Describe SDA, SCL, and a simple I2C address
• Install and use the Adafruit SSD1306 and GFX libraries
• Display text and live analog values on the OLED

PARTSComponents Required

• ESP32ESP32 DevKit boardControls the OLED and reads the potentiometer
• OLEDSSD1306 0.96 inch I2C OLED displayShows text and live values
• POT10 kOhm potentiometerProvides a changing analog value from Mission 08
• WIREBreadboard and jumper wiresConnect 3.3 V, GND, SDA, SCL, and the analog input
• USBUSB data cableUpload code and compare OLED output with Serial Monitor

ENGEngineering Explanation

REALReal-World Analogy

WIREWiring Diagram

Follow these steps in order. Unplug USB before you change any wires.

1. 1

   Unplug the ESP32 USB cable before wiring.

2. 2

   Connect OLED VCC to ESP32 3.3 V.

3. 3

   Connect OLED GND to ESP32 GND.

4. 4

   Connect OLED SDA to ESP32 GPIO21.

5. 5

   Connect OLED SCL to ESP32 GPIO22.

6. 6

   Connect one outer potentiometer pin to 3.3 V.

7. 7

   Connect the other outer potentiometer pin to GND.

8. 8

   Connect the potentiometer middle pin to GPIO34.

9. 9

   Install Adafruit SSD1306 and Adafruit GFX libraries in Arduino IDE.

10. 10

    Plug USB back in, upload the sketch, and open Serial Monitor at 115200 baud.

GPIOGPIO Table

⌨️Arduino Code

Copy this into Arduino IDE, then click Upload.

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

const int SCREEN_WIDTH = 128;
const int SCREEN_HEIGHT = 64;
const int OLED_RESET = -1;
const int POT_PIN = 34;

const int I2C_SDA = 21;
const int I2C_SCL = 22;
const int OLED_ADDRESS = 0x3C;

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

void setup() {
  Serial.begin(115200);

  Wire.begin(I2C_SDA, I2C_SCL);

  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS)) {
    Serial.println("OLED not found. Check wiring and I2C address.");
    while (true) {
      delay(1000);
    }
  }

  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("ESP32 Engine");
  display.println("OLED ready");
  display.display();

  delay(1500);
}

void loop() {
  int rawValue = analogRead(POT_PIN);
  int percent = map(rawValue, 0, 4095, 0, 100);

  Serial.print("ADC: ");
  Serial.print(rawValue);
  Serial.print(" | Percent: ");
  Serial.print(percent);
  Serial.println("%");

  display.clearDisplay();

  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("Mission 09 OLED");

  display.setCursor(0, 18);
  display.print("ADC: ");
  display.println(rawValue);

  display.setCursor(0, 34);
  display.print("Dial: ");
  display.print(percent);
  display.println("%");

  display.setCursor(0, 52);
  display.println("GPIO34 -> screen");

  display.display();
  delay(250);
}

CODELine-by-line Explanation

• Wire.h gives the ESP32 I2C communication functions.
• Adafruit_GFX provides drawing and text functions used by many Adafruit display libraries.
• Adafruit_SSD1306 knows how to talk to the SSD1306 OLED controller.
• SCREEN_WIDTH and SCREEN_HEIGHT match a common 128x64 OLED module.
• POT_PIN is GPIO34, the analog input from Mission 08.
• Wire.begin(21, 22) starts I2C using the ESP32 default SDA and SCL pins.
• display.begin() checks whether the OLED responds at address 0x3C.
• If the OLED is not found, the sketch prints a clear error and stops so you do not miss the wiring problem.
• analogRead() gets the raw ADC value from the potentiometer.
• map() converts the raw 0 to 4095 range into a friendlier 0 to 100 percent range.
• clearDisplay() clears the screen buffer before drawing the next frame.
• setCursor() chooses where the next text will appear.
• print() and println() add text and numbers to the screen buffer.
• display.display() sends the finished buffer to the OLED so the visible pixels update.

WARNCommon Mistakes

• SDA and SCL swapped

  The OLED cannot understand the bus when data and clock are reversed.

• Wrong I2C address

  Most OLEDs use 0x3C, but some modules use 0x3D.

• Missing libraries

  Arduino IDE cannot compile the display code without Adafruit SSD1306 and Adafruit GFX.

• Forgetting display.display()

  The code draws into memory but never sends the buffer to the physical OLED.

• Old text remains on the screen

  New text is drawn over old pixels without clearing them first.

• Using 5 V signal logic

  The ESP32 GPIO pins are 3.3 V pins.

• Potentiometer value does not change

  The middle pin may not be connected to GPIO34, or the outer pins may not go to 3.3 V and GND.

• Screen updates too fast to read

  A very short delay can refresh the text more often than a human needs.

• Tiny text is hard to read

  Text size 1 fits more content but is small.

• Confusing display coordinates

  The top-left pixel is coordinate 0,0, and y increases downward.

!Troubleshooting

Most ESP32 problems are wiring, power, library, or timing issues. Check these first.

• OLED stays completely blank

  Likely cause: Power, ground, SDA, SCL, address, or library setup may be wrong.

  Fix: Check 3.3 V, GND, GPIO21, GPIO22, OLED_ADDRESS, and installed libraries.

• Serial Monitor says OLED not found

  Likely cause: The ESP32 did not receive a response from the display at address 0x3C.

  Fix: Check wiring first, then try 0x3D if your module uses a different address.

• Code compiles but upload fails

  Likely cause: Wrong board, wrong port, or boot mode issue in Arduino IDE.

  Fix: Select the correct ESP32 board and port, then hold BOOT during upload if your board requires it.

• OLED works but analog value is random

  Likely cause: GPIO34 may be floating if the potentiometer wiper is not connected.

  Fix: Reconnect the potentiometer exactly like Mission 08.

• OLED shows strange characters

  Likely cause: The display type, I2C address, or memory update may not match the module.

  Fix: Confirm the module is SSD1306 128x64 and use the correct address.

• Values change on Serial Monitor but not OLED

  Likely cause: The display buffer may not be refreshed after printing the new value.

  Fix: Make sure display.display() runs after all OLED print statements in loop().

TIPEngineer Tip

REMRemember This Forever

?FAQs

• What is an OLED display?

  An OLED display is a small screen where each pixel can create its own light. The SSD1306 module is popular because it is low power, sharp, and easy to control over I2C.

• Why use an OLED instead of Serial Monitor?

  Serial Monitor is only visible on your computer. An OLED lets the ESP32 project show information when it is running on a desk, wall, robot, or enclosure.

• What does SSD1306 mean?

  SSD1306 is the display controller chip used on many 0.96 inch OLED modules. Your Arduino code talks to this controller, and the controller updates the pixels.

• What is I2C?

  I2C is a communication bus that lets the ESP32 talk to smart parts using two signal wires: SDA for data and SCL for clock.

• Which ESP32 pins should I use for I2C OLED?

  For a typical ESP32 DevKit, use GPIO21 for SDA and GPIO22 for SCL. Those are the default I2C pins used in this mission.

• What OLED I2C address should I use?

  Most SSD1306 0.96 inch OLED modules use address 0x3C. Some use 0x3D. If the screen stays blank, address mismatch is one of the first things to check.

• Should OLED VCC connect to 3.3 V or 5 V?

  Use 3.3 V for this mission. Many modules tolerate 5 V on VCC, but the ESP32 GPIO signals are 3.3 V, so 3.3 V wiring is the safer beginner choice.

• Why does the code call display.display()?

  The library first draws into a memory buffer. display.display() sends that buffer to the real screen, so the pixels actually update.

• Why do we clear the display before drawing again?

  If you do not clear the display, old text can remain behind new text. clearDisplay() gives each refresh a clean screen.

• Can the OLED show sensor values?

  Yes. Any value you can print to Serial Monitor can usually be printed to the OLED, including temperature, humidity, light level, distance, and ADC readings.

• Why does the OLED flicker if I refresh too fast?

  Refreshing too often can make updates look unstable. Update only as fast as the user needs to read the value, such as a few times per second.

• What libraries do I need?

  Install Adafruit SSD1306 and Adafruit GFX from the Arduino Library Manager. The Wire library is included with the ESP32 Arduino core.

• Can I use a different OLED size?

  Yes, but you must match the screen width, height, and driver. This mission assumes a 128x64 SSD1306 OLED.

• Can many I2C devices share GPIO21 and GPIO22?

  Yes, if each device has a different I2C address and the wiring is clean. That is one reason I2C is useful.

• What should I do if the screen is blank?

  Check VCC, GND, SDA, SCL, the I2C address, library installation, and whether your module is really SSD1306.