How to Use OLED Display with Arduino: Simple Guide and Example

To use an OLED display with Arduino, connect it via I2C or SPI pins and use a library like Adafruit_SSD1306 to control it. Initialize the display in your code, then use commands to show text or graphics on the screen.

Syntax

To use an OLED display with Arduino, you typically include the Adafruit_SSD1306 and Adafruit_GFX libraries. Then you create a display object with the screen size and I2C address. Initialize the display in setup() and use functions like clearDisplay(), setCursor(), and print() to show content.

arduino

#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 ///< See datasheet for Address; 0x3C or 0x3D

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

void setup() {
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    // Display initialization failed
    for(;;); // Don't proceed, loop forever
  }
  display.clearDisplay();
  display.setTextSize(1);      // Normal 1:1 pixel scale
  display.setTextColor(SSD1306_WHITE); // Draw white text
  display.setCursor(0,0);      // Start at top-left corner
  display.print("Hello, OLED!");
  display.display();           // Show on screen
}

void loop() {
  // Nothing here
}

Output

OLED screen shows: Hello, OLED!

Example

This example shows how to display a simple message on a 128x64 OLED screen connected via I2C. It initializes the display, clears it, sets text size and color, then prints "Hello, OLED!" on the screen.

arduino

#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);

void setup() {
  Serial.begin(9600);
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println("SSD1306 allocation failed");
    for(;;);
  }
  display.clearDisplay();
  display.setTextSize(2);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(10, 20);
  display.println("Hello, OLED!");
  display.display();
}

void loop() {
  // No repeated actions
}

Output

OLED screen shows: Hello, OLED! in larger text

Common Pitfalls

• Wrong I2C address: OLED displays often use 0x3C or 0x3D. Use an I2C scanner sketch to find the correct address.
• Missing or wrong library: Make sure to install Adafruit_SSD1306 and Adafruit_GFX libraries via Arduino Library Manager.
• Incorrect wiring: Connect SDA and SCL pins correctly (usually A4 and A5 on Arduino Uno).
• Not calling display.display(): Changes won't show on screen until this function is called.

arduino

/* Wrong way: Missing display.display() call */
display.clearDisplay();
display.setCursor(0,0);
display.print("No update");
// Missing display.display(); so screen stays blank

/* Right way: */
display.clearDisplay();
display.setCursor(0,0);
display.print("Shows text");
display.display(); // Must call to update screen

Quick Reference

Here are key functions to remember when using OLED with Arduino:

• display.begin(): Initialize the display
• display.clearDisplay(): Clear the screen
• display.setTextSize(n): Set text size
• display.setTextColor(color): Set text color
• display.setCursor(x, y): Set text position
• display.print(): Print text
• display.display(): Refresh screen to show changes

Key Takeaways

Connect OLED display correctly to Arduino using I2C or SPI pins before coding.

Install and include Adafruit_SSD1306 and Adafruit_GFX libraries to control the OLED.

Always call display.display() after drawing commands to update the screen.

Use an I2C scanner to find the correct OLED address if unsure.

Clear the display before drawing new content to avoid overlapping graphics.