SSD1306 OLED Overview

Power & Voltage Information

The AuscomTech product listing specifies a 3–5V DC supply at the module's VDD connection. The Arduino UNO example below therefore uses the UNO 5V pin to power this specific listed module.

For a 3.3V microcontroller or Raspberry Pi, use a 3.3V supply for the OLED module unless the documentation for that controller and module combination specifies otherwise.

Module Connections & Arduino UNO Wiring

The four connections are printed on the front of the pictured PCB. Connect them according to the markings rather than relying only on wire colour or physical position.

Find the I2C Address First

The SSD1306 controller supports two 7-bit I2C addresses: 0x3C and 0x3D. The address depends on how the module manufacturer has configured the SSD1306 address-selection input, so do not assume the address from display resolution alone.

Connect only the OLED and Arduino UNO as shown above, upload this scanner and open the Serial Monitor at 115200 baud.

#include <Wire.h>

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

  delay(500);
  Serial.println(F("I2C scanner"));
}

void loop() {
  byte deviceCount = 0;

  for (byte address = 1; address < 127; address++) {
    Wire.beginTransmission(address);
    byte error = Wire.endTransmission();

    if (error == 0) {
      Serial.print(F("Found I2C device at 0x"));

      if (address < 16) {
        Serial.print('0');
      }

      Serial.println(address, HEX);
      deviceCount++;
    }
  }

  if (deviceCount == 0) {
    Serial.println(F("No I2C devices found."));
  }

  Serial.println(F("Scan complete."));

  while (true) {
    delay(1000);
  }
}

Expected Scanner Result

A correctly connected SSD1306 should normally be reported as 0x3C or 0x3D. Write down the address shown by your module because the same value must be used in the display sketch.

Arduino Library Installation

The display example uses the Adafruit SSD1306 and Adafruit GFX libraries.

1. Open the Arduino IDE.
2. Open Tools → Manage Libraries or the Library Manager panel.
3. Search for Adafruit SSD1306 and install it.
4. Search for Adafruit GFX Library and install it if it was not installed automatically.
5. Accept any required library dependencies offered by the Arduino IDE.

The Arduino Wire library used for I2C communication is included with the Arduino board package and does not require a separate installation.

Basic Arduino Display Test

The example below assumes the scanner reported address 0x3C. If your scanner reported 0x3D, change the OLED_ADDRESS line before uploading.

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

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64

// This four-pin module has no separate reset pin.
#define OLED_RESET -1

// Change to 0x3D if that is what the I2C scanner reports.
#define OLED_ADDRESS 0x3C

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

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

  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS)) {
    Serial.println(F("SSD1306 initialisation failed."));
    while (true) {
      delay(1000);
    }
  }

  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);

  display.drawRect(
    0,
    0,
    SCREEN_WIDTH,
    SCREEN_HEIGHT,
    SSD1306_WHITE
  );

  display.setCursor(8, 8);
  display.println(F("AuscomTech"));

  display.setCursor(8, 20);
  display.println(F("SSD1306 128x64"));

  display.setCursor(8, 32);
  display.println(F("I2C OK"));

  // Drawing commands modify a RAM buffer.
  // display() transfers that buffer to the OLED.
  display.display();
}

void loop() {
  static unsigned long count = 0;

  // Clear only the counter area.
  display.fillRect(
    1,
    40,
    126,
    15,
    SSD1306_BLACK
  );

  display.setCursor(8, 44);
  display.print(F("Count: "));
  display.print(count++);

  display.display();
  delay(1000);
}

Expected Result

The OLED should show a rectangular border with AuscomTech, SSD1306 128x64 and I2C OK. A counter near the bottom of the display should increase approximately once per second.

If the counter changes, both the I2C communication and repeated display-buffer updates are working.

Understanding the Display Buffer

Adafruit GFX drawing commands change an image buffer stored in the microcontroller's memory. After drawing text, lines, rectangles or other graphics, call display.display() to transfer the updated buffer to the OLED.

If you change drawing commands but forget display.display(), the program may run normally while the visible screen remains unchanged.

Raspberry Pi & Other 3.3V Controllers

The same four connections are used with a Raspberry Pi, ESP32, Raspberry Pi Pico or other controller that supports I2C: power, ground, SDA and SCL.

Use the SDA and SCL pins documented for your particular controller board. On platforms such as Raspberry Pi, I2C must also be enabled in the operating system before software can communicate with the display.

Troubleshooting