How to Use an OLED Display (SSD1306): Text, Shapes and Graphics with Arduino

Although it's barely bigger than a fingertip, the 0.96-inch OLED display shows a sharp 128×64-pixel image and is one of the most popular displays for Arduino projects. Unlike character LCDs, it can draw not only letters but lines, circles, icons, graphs and even small games. It's ideal for smartwatches, weather stations, remotes and portable measuring devices. Almost all of these displays use a driver chip called the SSD1306 and connect with just two data wires (I2C).

What is an OLED, and how is it different from an LCD?

In an OLED (Organic Light Emitting Diode) display, every pixel produces its own light; there's no backlight. That's why black areas are truly black, contrast is very high, the screen looks sharp from every angle, and it uses very little power when most of the image is dark. Its 128×64 pixels make graphics, icons and drawings possible that character-based LCDs can't show.

Specifications

OLED display wiring

On two-colour models the top 16 rows of the screen glow yellow and the rest blue; these colours can't be changed in software, so it looks good to design the top part like a title bar. If you're not sure of the display's address, use the I2C scanner sketch from Using an I2C LCD Display.

Installing the libraries

1. Open the Library Manager in the Arduino IDE and search for Adafruit SSD1306.
2. When it asks about dependencies during installation, choose Install all so that Adafruit GFX and Adafruit BusIO are installed too.
3. If you like, open File > Examples > Adafruit SSD1306 > ssd1306_128x64_i2c and try it with the display address set to 0x3C.

First program: writing text on the screen

1#include <Wire.h>
2#include <Adafruit_GFX.h>
3#include <Adafruit_SSD1306.h>
4
5Adafruit_SSD1306 display(128, 64, &Wire, -1);   // genişlik, yükseklik, I2C, reset pini yok / width, height, I2C, no reset pin
6
7void setup() {
8  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {   // I2C adresi / I2C address
9    for (;;);                                         // ekran bulunamadı / display not found
10  }
11  display.clearDisplay();
12  display.setTextColor(SSD1306_WHITE);
13  display.setTextSize(2);                   // 2 kat büyük / double size
14  display.setCursor(0, 0);
15  display.println(F("BlueGrays"));
16  display.setTextSize(1);
17  display.setCursor(0, 24);
18  display.println(F("OLED 128x64 hazir!"));
19  display.display();                        // tamponu ekrana gönder / push the buffer to the screen
20}
21
22void loop() {
23}

Drawing shapes: Adafruit GFX functions

The top-left corner of the screen is (0, 0) and the bottom-right corner is (127, 63). For the colour you use SSD1306_WHITE (on), SSD1306_BLACK (off) or SSD1306_INVERSE (invert).

Showing a sensor value: a live thermometer

The OLED's strength is showing readings with big digits and graphics. The code below writes the temperature read from a DHT11 in a large font and shows the humidity as a bar graph underneath. For the sensor wiring, see DHT11 Temperature and Humidity Sensor.

1#include <Wire.h>
2#include <Adafruit_GFX.h>
3#include <Adafruit_SSD1306.h>
4#include <DHT.h>
5
6Adafruit_SSD1306 display(128, 64, &Wire, -1);
7DHT dht(2, DHT11);
8
9void setup() {
10  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
11  display.setTextColor(SSD1306_WHITE);
12  dht.begin();
13}
14
15void loop() {
16  float t = dht.readTemperature();
17  float h = dht.readHumidity();
18  display.clearDisplay();
19  display.setTextSize(1);
20  display.setCursor(0, 0);
21  display.print(F("Sicaklik / Temp"));
22  display.setTextSize(3);
23  display.setCursor(0, 16);
24  display.print(t, 1);
25  display.print(F("C"));
26  display.drawRect(0, 52, 128, 10, SSD1306_WHITE);                    // nem çubuğu çerçevesi / humidity bar frame
27  display.fillRect(2, 54, (int)(h / 100.0 * 124), 6, SSD1306_WHITE);  // nem oranı kadar dolu / filled by humidity
28  display.display();
29  delay(2000);
30}

Drawing your own icon: bitmaps

To show a logo or icon you turn the image into a byte array: each bit is one pixel. Conversion tools such as image2cpp turn a black-and-white image straight into an Arduino array. You can also write small icons by hand; the 8×8 array below draws a heart:

1const unsigned char PROGMEM heart[] = {
2  0b01100110,
3  0b11111111,
4  0b11111111,
5  0b11111111,
6  0b01111110,
7  0b00111100,
8  0b00011000,
9  0b00000000
10};
11
12// setup() ya da loop() içinde / inside setup() or loop()
13display.drawBitmap(60, 28, heart, 8, 8, SSD1306_WHITE);
14display.display();

OLED with the ESP32 and Raspberry Pi Pico

The same Arduino code and libraries run on the ESP32; the I2C pins are GPIO 21 (SDA) and 22 (SCL). Because the ESP32 has plenty of memory, animations and fast-refreshing graphics are much smoother. On the Pico with MicroPython, just copy the ssd1306.py driver file (from micropython-lib) to the Pico:

1from machine import Pin, I2C
2import ssd1306                                 # ssd1306.py Pico'da olmalı / must be on the Pico
3
4i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)
5oled = ssd1306.SSD1306_I2C(128, 64, i2c)       # adres varsayılan 0x3C / default address 0x3C
6
7oled.fill(0)                                   # ekranı temizle / clear the screen
8oled.text("BlueGrays", 0, 0)
9oled.text("Pico + OLED", 0, 16)
10oled.rect(0, 40, 128, 20, 1)                   # çerçeve / frame
11oled.fill_rect(2, 42, 80, 16, 1)               # dolu çubuk / filled bar
12oled.show()                                    # ekrana gönder / push to the screen

Display lifetime and burn-in

OLED pixels lose brightness as they're used. If the same image stays on the screen unchanged for months, a faint ghost can form on frequently lit pixels. To prevent this, switch the display off when it's not in use (display.ssd1306_command(SSD1306_DISPLAYOFF)), lower the brightness (display.dim(true)), shift static content by a few pixels now and then, or use a PIR sensor to switch the display on only when someone is nearby.

OLED display project ideas

• Mini weather station: show temperature, humidity and pressure with icons.
• Pocket games: play games like Pong or the T-Rex runner with buttons or a joystick.
• Weather display: show the weather you fetch from the internet with an ESP32, complete with icons.
• Parking sensor display: show the distance measured by an HC-SR04 as a number and a bar.
• Signal plotter: draw analogRead values as a scrolling graph on the screen.
• Desk clock: bring together the internet time, the date and the day's weather on one screen.

Common mistakes and how to fix them

• The screen stays blank: display.display() isn't called, the address is wrong (0x3D instead of 0x3C), or SDA and SCL are swapped.
• "SSD1306 allocation failed": the Uno is out of RAM; a 128×64 display's buffer takes 1 KB. Write text with F(), move large arrays to PROGMEM, or use the RAM-friendly U8g2 library.
• The image is garbled or only half shown: a 128×32 display has been declared as 128×64 (or vice versa); use the correct size in the code.
• The image is upside down: rotate it 180 degrees with display.setRotation(2).
• Connecting VCC and GND the wrong way round: this destroys the display permanently; read the pin labels before connecting.
• Random freezes: long, loose I2C wires; keep wires short and lower the I2C speed if needed.

An OLED display is the cheapest way to give your project a professional look. If you only need to show numbers, a 7-segment display is a good choice, and for text that must be readable in sunlight, an I2C LCD. In the BlueGrays app you'll find OLED Pong and T-Rex games, an ESP32 weather display, a parking sensor and a temperature logger, with circuit diagrams and code.