ESP32 S3 - OLED 128x64 Display

Hardware Preparation

Or you can buy the following kits:

Buy Note: If you want a bigger OLED display, use the 2.42 inch OLED Display 128x64 .

About OLED Displays

An OLED (Organic Light-Emitting Diode) display is a screen technology where every pixel emits its own light, eliminating the need for a backlight entirely. This gives OLED panels perfect blacks, extremely high contrast, and wide viewing angles that make them easy to read from almost any position. For ESP32 S3 projects the SSD1306-based 128x64 module is particularly popular because it communicates over I2C using only two signal pins, leaves most GPIO free for other peripherals, and runs comfortably from the 3.3 V supply the ESP32 S3 provides.

Key Specifications

The SSD1306 I2C OLED 128x64 has a resolution of 128 horizontal by 64 vertical pixels, giving a total of 8,192 individually addressable dots. It operates from a 3.3 V supply (some modules accept 3.3 V to 5 V) and communicates over the I2C bus at the default address 0x3C, though some modules are factory-configured to 0x3D. The display requires no backlight, draws only a few milliamps at typical brightness, and the SSD1306 driver chip is directly supported by the Adafruit SSD1306 and Adafruit GFX Arduino libraries.

I2C OLED Display Pinout

The SSD1306 OLED module exposes four pins that connect directly to the ESP32 S3:

1. GND pin: Connect to ground (GND) on ESP32 S3
2. VCC pin: Power supply — connect to 3.3 V on ESP32 S3 (some modules accept up to 5 V)
3. SCL pin: Serial Clock Line for I2C communication with ESP32 S3
4. SDA pin: Serial Data Line for I2C communication with ESP32 S3

Wiring Diagram

Connect the OLED 128x64 display to the ESP32 S3 over the I2C bus using the four-wire connection described below. Double-check polarity before powering the board — reversing VCC and GND can damage the OLED module.

Safety Notes

Always power the OLED from the 3.3 V pin of the ESP32 S3 rather than 5 V unless your specific module's datasheet confirms 5 V tolerance. Keep I2C wire lengths short (under 30 cm) to avoid signal integrity issues at higher bus speeds.

This image is created using Fritzing. Click to enlarge image

How To Use OLED with ESP32 S3

Install SSD1306 OLED Library

Before writing code, you need to install two libraries through the Arduino IDE Library Manager. Open the Library Manager by clicking the Libraries icon in the left sidebar, search for "SSD1306", locate the Adafruit SSD1306 entry, and click Install. When prompted, click "Install All" to also pull in the required Adafruit GFX dependency. The Adafruit_SSD1306 library handles low-level communication with the OLED driver chip on the ESP32 S3, while Adafruit_GFX provides the higher-level drawing primitives such as lines, circles, and text rendering.

• Search for Adafruit SSD1306 created by Adafruit and click the Install button.

Programming Your ESP32 S3 OLED Display

The following code snippets illustrate the essential building blocks for driving the OLED from your ESP32 S3 sketch. Every OLED program starts by including the three required headers, defining the pixel dimensions, and constructing the display object before the I2C bus is initialised.

Include libraries:

Define OLED dimensions:

Create OLED object:

Initialize OLED in setup():

The SSD1306_SWITCHCAPVCC flag tells the driver to use its internal charge pump for the display voltage, making external power supplies unnecessary. The address 0x3C matches most SSD1306 modules; if your scanner reports a different address, substitute it here. The while (true) halt ensures the program stops cleanly rather than proceeding with a non-functional display.

ESP32 S3 Code - Display Text on OLED

The following code demonstrates how to display text and numbers on the OLED screen with your ESP32 S3. It shows multiple text sizes, cursor positioning, and the essential oled.display() call that pushes the frame buffer to the physical screen.

Essential OLED Text Functions

The Adafruit SSD1306 and GFX libraries expose a rich set of text and drawing functions for your ESP32 S3 sketches. oled.clearDisplay() wipes all pixels before each new frame. oled.setTextSize(n) scales the built-in font from size 1 (smallest, 6×8 px per character) up to size 8. oled.setCursor(x, y) positions the text insertion point in pixel coordinates. oled.setTextColor(WHITE) renders light text on a dark background, while oled.setTextColor(BLACK, WHITE) inverts to dark text on a light background. oled.println("message") and oled.println(number) write content to the buffer, and oled.display() commits that buffer to the screen. For animated text the library also provides oled.startscrollright(), oled.startscrollleft(), oled.startscrolldiagright(), oled.startscrolldiagleft(), and oled.stopscroll() to drive the SSD1306's built-in hardware scroll engine.

Centering Text on Your OLED Display

Centering text on an OLED 128x64 display requires measuring the rendered dimensions of your string before positioning it. Use getTextBounds() to retrieve the pixel width and height of your text at the chosen size, then compute the starting X as (OLED_WIDTH - textWidth) / 2 and Y as (OLED_HEIGHT - textHeight) / 2. For a complete worked example covering both horizontal and vertical centering, visit our guide: How to vertical/horizontal center on OLED.

ESP32 S3 Code - Drawing Shapes on OLED

The following code shows how to draw geometric shapes on the OLED display with your ESP32 S3, using the Adafruit GFX drawing primitives to render lines, rectangles, circles, and triangles.

The Adafruit GFX library provides both outline and filled variants for the most common shapes. drawLine(x1, y1, x2, y2, color) draws a straight line between two pixel coordinates. drawRect and fillRect render rectangle outlines and solid rectangles respectively, while drawRoundRect and fillRoundRect add rounded corners. drawCircle and fillCircle take a centre point and radius, and drawTriangle and fillTriangle accept three vertex coordinates. All drawing functions accept WHITE or BLACK as the color parameter, letting you mix light and dark elements on the same frame.

ESP32 S3 Code - Display Images on OLED

The OLED's frame buffer can hold any 128×64 monochrome bitmap, making it straightforward to display custom logos, icons, or illustrations on your ESP32 S3 project.

Converting Images to Bitmap Arrays

To display a custom image you first need to convert it to a C byte array that the Adafruit library can render.

1. Choose your image file (JPG, PNG, GIF, etc.)
2. Open the online converter: image2cpp
3. Set canvas size to 128x64 to match your OLED resolution
4. Select "Arduino code" as the output format
5. Choose "Vertical - 1 bit per pixel" for the drawing mode
6. Click Generate and copy the resulting bitmap array into your sketch

Using Bitmap in ESP32 S3 Code

The following code loads a bitmap array and renders it on the OLED display connected to your ESP32 S3. Replace the ArduinoIcon array with the one generated from your own image.

For best results use high-contrast black-and-white source images, resize them to 128×64 before converting, and favour simple graphics over complex photographs. Smaller images also consume less of the ESP32 S3's RAM, leaving more headroom for the rest of your application.

OLED Troubleshooting Guide

If your OLED display is not working with the ESP32 S3, work through the checks below systematically before replacing any hardware.

Display Not Turning On

Start by verifying every wire in your wiring diagram. VCC must connect to 3.3 V on the ESP32 S3, GND to GND, SDA to the SDA pin, and SCL to the SCL pin. A single loose jumper wire is the most common cause of a blank screen. Also confirm that your module uses the SSD1306 driver — some visually identical modules use the SH1106 chip and require a different library.

Finding Your OLED's I2C Address

Most OLED displays use I2C address 0x3C, but some are configured to 0x3D. The following I2C scanner sketch will detect the address automatically on your ESP32 S3.

Upload and open the Serial Monitor — you should see output similar to the following:

If your address differs, update your sketch accordingly:

Common Issues and Solutions

"SSD1306 allocation failed" error: The most likely causes are a wrong I2C address, incorrect wiring to the ESP32 S3, or a faulty OLED module. Run the scanner sketch first to confirm the address before swapping hardware.

Random pixels on screen: Add oled.clearDisplay() at the start of your loop function and always follow drawing calls with oled.display() to commit the frame buffer.

Text too small or large: Adjust with oled.setTextSize(2) or higher. The valid range is 1 (smallest, approximately 6×8 px) through 8 (largest).

Display upside down: Physically rotate the OLED module, or call oled.setRotation(2) immediately after initialisation to rotate the frame buffer in software.

Screen not updating: Ensure every drawing sequence ends with a call to oled.display(). Without it the frame buffer is never pushed to the physical screen.

Detailed Instructions

1. New to ESP32 S3? Complete our Getting Started with ESP32 S3 guide first.
2. Wire the OLED: Connect the OLED to the ESP32 S3 (VCC→3.3V, GND→GND, SDA→SDA, SCL→SCL).
3. Install libraries: Open Library Manager in Arduino IDE and install Adafruit SSD1306 and Adafruit GFX.
4. Connect ESP32 S3: Plug your board into the computer via a USB Type-C cable.
5. Select board: Choose "ESP32 S3" and the correct COM port in Arduino IDE.
6. Upload code: Copy one of the example sketches above, paste it into Arduino IDE, and click Upload.
7. Verify display: The OLED should light up and show your programmed content within a few seconds of upload.
8. Pro Tip: Always call oled.display() after any drawing operation — without it the OLED screen will not reflect your changes.

Application Ideas

The OLED 128x64 display opens up a wide range of practical and creative uses for the ESP32 S3, from basic sensor readouts to interactive interfaces.

1. Temperature monitor: Display DHT22 sensor readings on the OLED in real time with the ESP32 S3.
2. WiFi status display: Show the current connection status and assigned IP address on the OLED screen.
3. Smart doorbell: Render visitor notifications or a doorbell icon on the OLED 128x64 when the button is pressed.
4. Weather station: Present temperature, humidity, and a simple forecast icon fetched from an online API.
5. System monitor: Display ESP32 S3 uptime, free heap memory, and WiFi signal strength on the OLED.
6. Countdown timer: Build a visual countdown with a large number centred on the OLED display.
7. Music player interface: Show the current track name and playback progress bar on the 128x64 screen.
8. Game display: Implement simple games such as Snake or Pong using the OLED's drawing primitives.

Video

Watch the step-by-step video walkthrough for this ESP32 S3 project below.

Challenge Yourself

Once you have the basics working there are plenty of ways to deepen your understanding of the OLED display and the ESP32 S3.

1. Beginner: Display live temperature readings from a DHT11 sensor on the OLED, updating every second.
2. Beginner: Create scrolling text that marquees a long message across the OLED screen using the hardware scroll engine.
3. Intermediate: Build an animated bouncing ball that moves around the OLED display and bounces off all four edges.
4. Intermediate: Design a multi-page menu system where button presses navigate between different OLED screens.
5. Advanced: Plot a real-time graph of sensor data that scrolls across the full 128×64 pixel width.
6. Advanced: Generate and display QR codes on the OLED using a QR-code library running on the ESP32 S3.

Language References

• Adafruit SSD1306 OLED Library
• Adafruit GFX Library

Learn More

• ESP32 S3 - LCD
• ESP32 S3 - LCD 20x4
• ESP32 S3 - SSD1309 OLED Display
• ESP32 S3 - OLED 128x32 Display
• ESP32 S3 - Round Circular TFT LCD Display
• ESP32 S3 - TFT LCD Touch Display SPI