OLED Display Arduino: Complete Wiring Guide and Code Examples

OLED Display Arduino: Complete Wiring Guide and Code Examples

If you’re looking to add a crisp, low-power display to your next project, the SSD1306 OLED is the perfect choice. In this guide, I’ll walk you through the complete pinout, wiring diagrams, library setup, and example code for using an OLED display Arduino combination — whether you’re using I2C or SPI, 128x64 or 128x32.

I’ve built a handful of projects with these displays, from remote control fans to GPS trackers, and once you get the wiring right, it’s surprisingly straightforward. Let’s get that OLED showing text, numbers, and graphics.

SSD1306 OLED Display Pinout Explained

Before you wire anything, you need to understand the pins on your SSD1306 module. Most breakout boards come in two variants: I2C (4 pins) or SPI (7 pins). Some boards support both — check the back of your module.

I2C Version (Most Common)

SPI Version (Faster, More Pins)

Important: Many cheap OLED modules claim to accept 5V but actually run on 3.3V internally. If you’re using a 5V Arduino like the Uno, you can safely power the VCC pin with 5V — the onboard regulator handles it. However, always check your specific module’s datasheet first.

Parts List

For this tutorial, I’m using the I2C version because it’s simpler and frees up more digital pins. Here’s what you’ll need:

• Arduino Uno (or Nano, Mega, etc.)
• SSD1306 OLED display (128x64 or 128x32)
• Breadboard
• Jumper wires (male-to-female)
• USB cable for programming

Wiring the OLED Display to Arduino

Let’s wire it up. For I2C (the most common approach), the connections are dead simple:

For SPI, you’ll need more connections, but it’s faster for animations. Here’s the typical wiring:

Pro tip: If you're using an ESP8266 like the NodeMCU or WeAct board, the I2C pins are usually D1 (SCL) and D2 (SDA). I covered a similar wiring approach in my E-Paper Display with ESP8266 post — the same logic applies here, just different libraries.

Installing the Required Libraries

You need two libraries for the SSD1306 OLED:

1. Adafruit SSD1306 — handles the display driver
2. Adafruit GFX — provides graphics functions (text, shapes, bitmaps)

Open the Arduino IDE, go to Sketch → Include Library → Manage Libraries, then search for and install both of these:

• Adafruit SSD1306 by Adafruit
• Adafruit GFX Library by Adafruit

Alternatively, you can download them from the Adafruit SSD1306 GitHub repository and install manually.

I2C Address Detection (Crucial Step)

Many OLED modules use address 0x3C, but some use 0x3D. If your code compiles but nothing shows on screen, you’ve probably got the wrong address. Run this I2C scanner sketch to find yours:

#include <Wire.h>

void setup() {
  Wire.begin();
  Serial.begin(9600);
  Serial.println("I2C Scanner");
}

void loop() {
  byte error, address;
  int deviceCount = 0;
  
  for (address = 1; address < 127; address++) {
    Wire.beginTransmission(address);
    error = Wire.endTransmission();
    
    if (error == 0) {
      Serial.print("I2C device found at address 0x");
      if (address < 16) Serial.print("0");
      Serial.print(address, HEX);
      Serial.println(" !");
      deviceCount++;
    }
  }
  if (deviceCount == 0)
    Serial.println("No I2C devices found");
  delay(3000);
}

Open the Serial Monitor (9600 baud), and you’ll see the address printed. Note it down — you’ll pass it to the display.begin() function.

Basic OLED Display Arduino Code

Here’s the simplest sketch to show text on your OLED display Arduino setup:

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

#define SCREEN_WIDTH 128  // OLED display width, in pixels
#define SCREEN_HEIGHT 64  // OLED display height, in pixels
#define OLED_RESET -1     // Reset pin (or -1 if sharing Arduino reset pin)
#define SCREEN_ADDRESS 0x3C // Use the address from your scanner

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

void setup() {
  Serial.begin(9600);
  
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println(F("SSD1306 allocation failed"));
    for(;;);
  }
  
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("Hello, viktor.build!");
  display.println("OLED + Arduino");
  display.display();
}

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

If everything’s wired correctly, you’ll see Hello, viktor.build! on your OLED. If not, double-check your wiring and I2C address.

Displaying Sensor Data (Real-World Example)

Let’s make this useful. I’ll show you how to display analog readings — perfect if you’ve already read my How to Read a Potentiometer with Arduino guide.

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

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C

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

const int potPin = A0;

void setup() {
  Serial.begin(9600);
  
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println(F("SSD1306 allocation failed"));
    for(;;);
  }
  display.clearDisplay();
  display.display();
}

void loop() {
  int potValue = analogRead(potPin);
  int percentage = map(potValue, 0, 1023, 0, 100);
  
  display.clearDisplay();
  
  // Draw title
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("Potentiometer");
  
  // Draw large value
  display.setTextSize(3);
  display.setCursor(0, 20);
  display.print(percentage);
  display.print("%");
  
  // Draw raw value smaller
  display.setTextSize(1);
  display.setCursor(0, 55);
  display.print("Raw: ");
  display.print(potValue);
  
  display.display();
  delay(200);
}

This reads a potentiometer on pin A0, maps it to a percentage, and displays both the percentage and raw value. You can easily swap the potentiometer for any sensor — try a temperature sensor or distance module.

Common Issues and Fixes

Over the years, I’ve run into a few gotchas with these displays. Here’s what to check if you get a blank screen:

• Wrong I2C address — Run the scanner sketch, use the address it reports.
• Power issues — Some modules need 3.3V, others 5V. If it gets hot, disconnect immediately.
• Missing pull-up resistors — Most modules have them onboard, but if yours is bare, add 4.7kΩ resistors on SDA and SCL to VCC.
• Library version mismatch — Make sure you have the latest Adafruit SSD1306 and Adafruit GFX installed.
• Faulty module — Yes, it happens. I’ve had two DOA displays from the same batch. Try swapping it out.

Adding Graphics and Custom Fonts

Once you have text working, the Adafruit GFX library makes drawing shapes easy:

display.drawPixel(10, 10, SSD1306_WHITE);           // Single pixel
display.drawLine(0, 0, 127, 63, SSD1306_WHITE);     // Line
display.drawRect(20, 20, 40, 30, SSD1306_WHITE);    // Rectangle outline
display.fillRect(20, 20, 40, 30, SSD1306_WHITE);    // Filled rectangle
display.drawCircle(64, 32, 20, SSD1306_WHITE);      // Circle outline
display.fillCircle(64, 32, 20, SSD1306_WHITE);      // Filled circle

For custom fonts, check out the Adafruit_GFX library examples — you can include bitmap fonts for larger, cleaner text.

Conclusion

Adding an OLED display Arduino setup to your project is one of the most satisfying upgrades you can make. Whether you’re showing sensor readings, debug info, or a simple interface, the SSD1306 is cheap, power-efficient, and easy to wire up once you know the pinout and I2C address.

If you’re building something with multiple modules, remember that I2C lets you chain devices on the same two wires — perfect for combining this display with an GPS module or Bluetooth module. For more advanced projects, check out my ESP8266 LTE guide where I use an OLED for status output.

Found this helpful? Join the community on Discord to share your builds and ask questions.