How to Use SSD1306 OLED with Arduino: Simple Guide

To use an SSD1306 OLED with Arduino, connect the display via I2C (SDA to A4, SCL to A5 on Uno), install the Adafruit_SSD1306 and Adafruit_GFX libraries, then initialize and draw on the display using provided functions. This setup allows you to show text and graphics easily on the OLED screen.

Syntax

Using the SSD1306 OLED with Arduino involves including libraries, initializing the display, and using drawing functions.

• #include <Adafruit_SSD1306.h>: Includes the OLED library.
• Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);: Creates a display object with screen size and reset pin.
• display.begin(SSD1306_SWITCHCAPVCC, 0x3C);: Initializes the display with power settings and I2C address.
• display.clearDisplay();: Clears the screen buffer.
• display.setTextSize(n);: Sets text size.
• display.setTextColor(SSD1306_WHITE);: Sets text color.
• display.setCursor(x, y);: Sets cursor position.
• display.print("text");: Prints text.
• display.display();: Sends buffer to the screen to show changes.

arduino

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

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET    -1

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

void setup() {
  if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    for(;;); // Loop forever if display init fails
  }
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0,0);
  display.print("Hello, OLED!");
  display.display();
}

void loop() {
  // Nothing here
}

Output

The OLED screen shows the text: Hello, OLED!

Example

This example shows how to initialize the SSD1306 OLED display and print "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

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

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

void loop() {
  // No repeated code needed
}

Output

The OLED screen displays "Hello, OLED!" in larger text near the center.

Common Pitfalls

Common mistakes when using SSD1306 OLED with Arduino include:

• Not installing the Adafruit_SSD1306 and Adafruit_GFX libraries.
• Using wrong I2C pins (on Arduino Uno, SDA is A4 and SCL is A5).
• Incorrect I2C address (usually 0x3C or 0x3D; check with an I2C scanner).
• Not calling display.display() after drawing commands, so nothing shows.
• Forgetting to clear the display buffer before drawing new content.

Example of a common mistake:

#include <Adafruit_SSD1306.h>
Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
  display.setCursor(0,0);
  display.print("Missing clearDisplay and display.display");
  // Missing display.clearDisplay() and display.display() calls
}

void loop() {}

Corrected version:

void setup() {
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
  display.clearDisplay();
  display.setCursor(0,0);
  display.print("Now it works!");
  display.display();
}

Quick Reference

Here is a quick reference for common SSD1306 OLED commands with Arduino:

Command	Description
display.begin(SSD1306_SWITCHCAPVCC, 0x3C)	Initialize the display with power and I2C address
display.clearDisplay()	Clear the screen buffer
display.setTextSize(n)	Set the size of the text
display.setTextColor(SSD1306_WHITE)	Set text color to white
display.setCursor(x, y)	Set cursor position for text
display.print("text")	Print text at cursor
display.display()	Send buffer to the screen to update display

Key Takeaways

Connect the SSD1306 OLED to Arduino using I2C pins (SDA to A4, SCL to A5 on Uno).

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

Always call display.begin() to initialize and display.display() to update the screen.

Clear the display buffer before drawing new content with display.clearDisplay().

Check the I2C address with a scanner if the display does not show anything.