OLED guides · On this page

Show a Reading on an OLED Display with an Arduino

Show a knob's reading on an SSD1306 OLED with an Arduino, as a number and a bar, running in your browser before you build it. The SSD1306 is the small, sharp screen in most starter kits, with 128 × 64 pixels that light themselves, driven over two I²C wires. It is easy to wire. Plan for its memory, since the library keeps a copy of the screen in the board's RAM, half of an Uno's 2 KB.

Left to right: a 0.96 inch blue 128 by 64 OLED module with four header pins labelled VDD, GND, SCK, SDA; a larger 1.3 inch black 128 by 64 module with four pins labelled GND, VCC, SCL, SDA; and a 0.96 inch blue module with seven pins labelled GND, VCC, D0, D1, RES, DC, CS.
0.96 in, 4 pinsI²C: this guide1.3 in, 4 pinsMay be an SH11060.96 in, 7 pinsSPI: wired differently

Try it first, no parts needed

This is the whole project, wired and running in your browser: a knob on A0, and the OLED drawing how far it's turned. Press Run simulation, then turn the knob and watch the percentage and the bar follow it.

Ready
Open in Cirkit Designer

The knob on A0

The screen redraws each time the percentage changes.

50 %

What the OLED shows

The display's 128 × 64 pixels, enlarged.

The screen lights up when the simulation runs.

Arduino Uno serial monitor115200 baud

Output appears here when the simulation runs.

What the code does

The sketch reads the knob, turns it into a percentage, and draws the number and a bar on the screen.

oled_knob_gauge.ino
// Turn the knob on A0: the OLED shows how far it's
// turned, as a percentage and a bar.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

const int KNOB_PIN = A0;

// 128 x 64 pixels on the Uno's I2C pins: SDA on A4,
// SCL on A5. -1: the module has no reset pin.
Adafruit_SSD1306 display(128, 64, &Wire, -1);

int shownPercent = -1;

void setup() {
  Serial.begin(115200);
  // Most modules answer at address 0x3C; some at 0x3D.
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println(F("NO_DISPLAY"));
    while (true) {}
  }
  display.setTextColor(SSD1306_WHITE);
}

void loop() {
  int reading = analogRead(KNOB_PIN);  // 0 to 1023
  int percent = round(reading * 100.0 / 1023);
  // Redraw only when the percentage changes: each
  // redraw sends the whole screen, 1 KB, over I2C.
  if (percent == shownPercent) {
    return;
  }
  shownPercent = percent;

  display.clearDisplay();
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.print(F("KNOB"));
  display.setCursor(80, 0);
  display.print(F("A0="));
  display.print(reading);

  display.setTextSize(3);
  display.setCursor(0, 16);
  display.print(percent);
  display.print('%');

  // A bar across the bottom, filled in proportion.
  int barWidth = map(reading, 0, 1023, 0, 124);
  display.drawRect(0, 52, 128, 12, SSD1306_WHITE);
  display.fillRect(2, 54, barWidth, 8, SSD1306_WHITE);
  display.display();

  Serial.print(F("A0="));
  Serial.print(reading);
  Serial.print(' ');
  Serial.print(percent);
  Serial.println('%');
}
  1. Adafruit_SSD1306 display(128, 64, &Wire, -1);

    Describes the screen: 128 × 64 pixels on the Uno's I²C pins, A4 and A5. The -1 means the module has no reset pin wired.

  2. if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
      Serial.println(F("NO_DISPLAY"));
      while (true) {}
    }

    Starts the screen at address 0x3C and reserves 1 KB of RAM for its copy. If there isn't room, it prints NO_DISPLAY and stops (see troubleshooting).

  3. if (percent == shownPercent) {
      return;
    }

    Turns the knob's 0 to 1023 into a percentage, and redraws only when that changes: each redraw sends the whole screen, 1 KB, over I²C.

  4. display.clearDisplay();

    Draws into the copy in RAM, not the screen: KNOB and the reading in small text, the percentage at size 3 (18 × 24 pixels a character) from (0, 16), then a bar up to 124 pixels wide.

  5. display.display();

    Sends the finished drawing from the Uno's RAM to the screen over I²C. Until this line runs, nothing the sketch drew shows.

Build it on an Arduino

Now with real parts. Check which pin is which, wire it, get the code, then upload it and turn the knob. Using an ESP32 board? It has its own guide →

Which pin is which: the OLED pinout

The four pins sit along the top edge. On the module drawn here they are, left to right: VDD, GND, SCK and SDA. Other modules put VDD and GND the other way round, or print VCC and SCL instead; go by the labels on yours.

SSD1306 128 × 64 I2C OLED module pinout with the screen toward you, left to right along the top edge: 1 VDD, power, 3.3 V or 5 V as the module is sold for; 2 GND, ground; 3 SCK, the I2C clock, also called SCL, to A5 on an Uno; 4 SDA, the I2C data line, to A4 on an Uno. Four header pins at 0.1 inch (2.54 mm) pitch; the order varies between modules.
Pixels128 × 64, one colour, each lighting itself
ControllerSolomon Systech SSD1306
InterfaceI²C: SDA (data) and SCL (clock, printed SCK on many modules)
Address0x3C, or 0x3D on some modules
Supply3.3 V or 5 V, as the module is sold for
RAM it needs1 KB on the board, for the library’s copy of the screen

You'll need

  • An Arduino Uno (a Nano works the same way) and its USB cable
  • An SSD1306 128 × 64 I²C OLED module sold for 5 V boards (four pins)
  • A 10 kΩ potentiometer, the knob
  • A breadboard and seven jumper wires
  • Software to upload the sketch to the Uno: either Cirkit Designer, free in your browser, or the Arduino IDE, a free download for Windows, macOS and Linux
  1. Wire it

    Four wires for the screen, three for the knob.

    Tap a connection to see it on the circuit.

    PinConnect to the UnoShow
    OLED VDD (VCC)5VShow
    OLED GNDGNDShow
    OLED SDAA4Show
    OLED SCK (SCL)A5Show
    Knob, one outer leg5VShow
    Knob, middle legA0Show
    Knob, other outer legGNDShow

    The knob's outer legs are interchangeable: swapped, turning it the same way lowers the reading instead of raising it.

  2. Get the code

    I'm using:

    Steps 2 and 3 follow the tool you pick.

    Open in Cirkit Designer

    The project opens with the sketch and its libraries already in it, so there's nothing to install.

    No Arduino IDE yet? Download it free for Windows, macOS or Linux.

    First, open the Library Manager (1), search for Adafruit SSD1306 (2), and install it (3); when it asks about dependencies, choose Install all, which adds Adafruit GFX and Adafruit BusIO.

    Arduino UnoLIBRARY MANAGERAdafruit SSD1306Type: AllTopic: AllAdafruit SSD1306by AdafruitSSD1306 oled driver library formonochrome 128x64 and 128x32displaysMore infoINSTALL123

    Then copy the sketch into a new one:

    How it works line by line is in what the code does, above.

  3. Upload and check it

    Plug in your Uno. In Cirkit, open the Build tab, then Upload firmware: click Select Port and pick your Uno, then Upload to Device. The first time, Cirkit asks you to install Cirkit Create Agent, a small desktop helper that lets it reach the board over USB. Then open Upload output and serial monitor and click Start Serial Monitor.

    Show me where to click in Cirkit
    OLED on an Arduino UnoFileEditExportHelp
    DesignCodeSimulateBuild
    1Parts & purchasing2Assemble3Upload firmware
    Arduino UnoEdit Code

    Board

    Arduino Uno Change

    2

    Port

    Select PortCOM3 Connected

    3

    Upload

    Upload to DeviceUploading...Upload successful

    4

    Check that it works

    Your project should now run as designed.

    Upload output and serial monitor
    Compile / Upload Output
    Sketch uses 15972 bytes (49%) of program storage space. Maximum is 32256 bytes.
    Global variables use 525 bytes (25%) of dynamic memory, leaving 1523 bytes for local variables. Maximum is 2048 bytes.
    Device SerialStop

    Read serial data from your device.

    Start Serial Monitor
    Listening on COM3 at 115200 baud
    A0=512 50%
    A0=257 25%
    A0=1023 100%
    A0=0 0%
    Select port

    Select a device port

    Select the device port for uploading code and serial communications

    COM3 (Arduino Uno)
    1. Open Build
    2. Choose Upload firmware
    3. Click Select Port
    4. Pick COM3 (Arduino Uno)
    5. Click Upload to Device
    6. Open Upload output and serial monitor
    7. Click Start Serial Monitor

    In the Arduino IDE, choose Arduino Uno and its port from the board menu, press Upload, then open the Serial Monitor and set it to 115200 baud.

    Show me where to click in the Arduino IDE
    Select BoardArduino Uno

    Select other board and port

    Arduino UnoCOM3
    oled_knob_gauge.ino
    // Turn the knob on A0: the OLED shows how far it's
    // turned, as a percentage and a bar.
    #include <Wire.h>
    #include <Adafruit_GFX.h>
    #include <Adafruit_SSD1306.h>
    
    OutputSerial Monitor115200 baud

    Compiling sketch...

    Sketch uses 15972 bytes (49%) of program storage space. Maximum is 32256 bytes.

    Global variables use 525 bytes (25%) of dynamic memory, leaving 1523 bytes for local variables. Maximum is 2048 bytes.

    Uploading...

    A0=512 50%

    A0=257 25%

    A0=1023 100%

    A0=0 0%

    Done uploading.

    1. Click the board menu
    2. Pick Arduino Uno on COM3
    3. Click Upload
    4. Wait for Done uploading
    5. Click Serial Monitor
    6. Check it is set to 115200 baud

    It works when:

    • The screen shows a percentage and a bar, and turning the knob moves both from 0 % at one end to 100 % at the other.
    • The Serial Monitor prints a line each time the percentage changes, such as A0=257 25% with the knob a quarter of the way round, as pictured.
    The OLED showing KNOB and A0=257 on the top line, 25% in large digits, and a bar a quarter full.
    With the knob a quarter of the way round, the screen shows 25 % and a quarter-full bar.

    Not working? See troubleshooting.

    Next guideShow sensor readings: a DHT11 room monitorTemperature, humidity and a comfort label on the same OLED, from a DHT11 sensor.

Troubleshooting

Find your symptom; the checks under it run from the most common cause down.

The screen stays blank, but the Serial Monitor shows readings

The sketch runs, but its pictures don't reach the screen. Check, in order:

  • The OLED is wired by its printed labels. Pin order differs between modules; check VDD (VCC) and GND first.
  • SDA goes to A4 and SCK (SCL) to A5. Swapped, the Uno can't reach the screen.
  • The address matches. Most modules answer at 0x3C; some, including Adafruit's 128 × 64 boards, at 0x3D. Change 0x3C in display.begin() and upload again, or find the address.
  • The module is an SSD1306. Some modules that look the same use an SH1106, which needs a different library; see a garbled picture.
  • The module is an I²C one, with four pins. A seven-pin module (GND, VCC, D0, D1, RES, DC, CS) talks SPI and needs different wiring and code.

The Serial Monitor prints NO_DISPLAY, or "SSD1306 allocation failed"

Both mean the same thing: this sketch prints NO_DISPLAY, and Adafruit's example sketch prints "SSD1306 allocation failed". The library couldn't reserve RAM for its copy of the screen, so the sketch stopped. That copy takes 1 KB of the Uno's 2 KB, and it's reserved only when the screen starts, so the compiler's memory report doesn't include it.

  • Your additions leave room for the screen. Keep fixed text in F("…"), as this sketch does, and avoid large arrays. This sketch leaves about 500 bytes free once the screen starts.
  • The screen size matches your module. A larger size in display(…) reserves a larger copy.

Nothing in the Serial Monitor, or garbled characters

  • The Serial Monitor is set to 115200 baud. It must match Serial.begin(115200) in the sketch.
  • The sketch prints only when the percentage changes. It prints once at the start; turn the knob to see more.

The picture is garbled, shifted, or has a stripe of noise

  • The module may be an SH1106, not an SSD1306. They look alike; the module's listing or the markings on it say which. An SH1106 needs a library for it, such as Adafruit SH110X, instead of Adafruit SSD1306.
  • The screen size in the code matches. A 128 × 32 module needs display(128, 32, …) and a layout that fits.

The reading stays at 0 % or 100 %

  • The knob's middle leg goes to A0. On the outer legs, A0 sees only 5 V or 0 V.
  • Both outer legs are connected. One to 5V and one to GND; with one missing, the reading has nothing to divide.

"Adafruit_SSD1306.h" or "Adafruit_GFX.h": No such file or directory

Arduino IDE only
  • The library is installed, with its dependencies. Install Adafruit SSD1306 and choose Install all, which adds Adafruit GFX and Adafruit BusIO. Cirkit Designer includes them all.

How the screen works

The OLED talks over I²C, a two-wire bus: SDA carries the data and SCL (SCK on this module) the clock. The Uno's I²C pins are A4 and A5. Each device on the bus has an address; the SSD1306's is 0x3C or 0x3D, set by a pin the module ties high or low.

Drawing never touches the screen directly. The library keeps a copy of the screen in the Uno's RAM and draws into it; display.display() then sends the whole copy to the SSD1306, which keeps its own and lights the panel from it until the next one arrives.

How a picture reaches the screen. On the Arduino Uno, the sketch draws with print(), drawRect() and the other drawing calls into the library's copy of the screen in RAM, 1,024 bytes, one bit a pixel; drawing changes only that copy. display() sends all 1,024 bytes over I2C into the SSD1306's display memory, which has the same layout. The SSD1306 lights the panel from that memory, again and again, until the next display().

Both copies have the same layout: one bit a pixel, in eight pages of eight rows. Each byte is one column of one page, eight pixels tall, with bit 0 at the top; 128 columns times 8 pages is 1,024 bytes. Below is the screen this guide's sketch draws, as those bytes.

The OLED's memory, byte by byteExample at 50 %Run the circuit above, and this shows its screen as the sketch draws it.

Column 4, page 2:
0xC7

Binary 11000111, bit 7 first

The numbers down the left are the pages. Point at the screen, tap it, or use the buttons or the arrow keys, to read the byte behind any column of any page. Bit 0 is the column's top pixel, bit 7 its bottom one, and a 1 lights it.

Positions count from the top-left corner, (0, 0); x grows to the right, to 127, and y down, to 63. Text size 1 is the library's small built-in font: each character takes 6 × 8 pixels, its 5 × 7 letter plus a pixel of space. Size 2 doubles that to 12 × 16, and this sketch's size 3 makes each character 18 × 24: the 50 % above starts at (0, 16) and fills pages 2 to 4. Lines, circles and boxes draw into the same copy:

Shapes, then display()
// A line from corner to corner
display.drawLine(0, 63, 127, 0, SSD1306_WHITE);
// A circle: centre (64, 32), radius 20
display.drawCircle(64, 32, 20, SSD1306_WHITE);
// A filled box: top-left (100, 10), 20 × 12
display.fillRect(100, 10, 20, 12, SSD1306_WHITE);
// Send it all to the screen
display.display();

Memory, speed and other limits

SSD1306 OLED on an Uno
MemoryThe library's copy of the screen takes 1,024 of the Uno's 2,048 bytes of RAM, reserved when the screen starts, so the compiler's report doesn't count it. This sketch has about 500 bytes left.
Redraw timeEach display() sends all 1,024 bytes over I²C. At the 400 kHz the library uses while it sends, and 9 clock pulses a byte, the bytes alone take about 23 ms, so the screen can be redrawn at most about 43 times a second, and the sketch waits for each transfer.
ScreensOne 128 × 64 screen on an Uno: a second copy of the screen wouldn't leave the sketch any RAM. On a board with more RAM, two can share the bus, at 0x3C and 0x3D.
BrightnessEach pixel is on or off, in the panel's one colour; the contrast setting dims or brightens the whole screen in 256 steps.
SupplyThe chip runs on 1.65 to 3.3 V; a module sold for 5 V boards brings its own regulator.

Redraw only when something on the screen changes, as this sketch does, and the time and the I²C traffic stay small. Keep fixed text in F("…") so it stays out of RAM. For a second screen, use a board with more RAM, such as an ESP32, and give it the other address.

OLED or something else?

ShowsInterfaceRAM on an UnoChoose it for
SSD1306 OLED128 × 64 pixels, one colourI²C; SPI on 7-pin modules1 KB for the screen's copyText, numbers and simple graphics on a small, sharp screen
SH1106 OLED128 × 64 pixels, one colourI²C or SPI1 KB for the screen's copyThe same kind of screen; it needs the Adafruit SH110X library instead
16 × 2 LCD (HD44780)Text: 16 characters on each of 2 linesParallel, or I²C through an add-on backpack boardNo copy of the screen; the LCD keeps its own 80 charactersPlain text, a character at a time, when the sketch needs its RAM
ILI9341 TFT240 × 320 pixels, in colourSPINo copy of the screen; the library draws straight to itColour, and pictures with more detail; its logic runs at 3.3 V, so on a 5 V Uno use a module with level shifting

On an Uno, memory often decides. The OLED's copy of the screen leaves at most 1 KB for everything else; a 16 × 2 LCD needs no copy, so it suits text-only projects that are short of RAM. The DHT11 room monitor shows what fits on the OLED alongside a sensor.

OLED FAQ

Why is my OLED blank?

Usually the wiring or the address: SDA and SCL swapped, VDD and GND swapped (pin order differs between modules), or a module at 0x3D while the code says 0x3C. Troubleshooting walks through the checks in order. If the Serial Monitor also says NO_DISPLAY or "SSD1306 allocation failed", the board ran out of RAM for the screen's copy; see that entry.

Can I connect two OLEDs to one Arduino?

Not with this library on an Uno. Each screen needs its own 1 KB copy, and two take all of the Uno's 2 KB of RAM. On a board with more RAM, yes, as long as they answer at different addresses, 0x3C and 0x3D; only some modules let you change theirs, with a jumper or resistor on the back.

Why doesn't my drawing show up?

Call display.display() after drawing. Every drawing call changes only the library's copy of the screen in RAM; display() is what sends it to the screen.

How do I show a picture or a logo?

Turn it into an array of bits, one a pixel, row by row, and draw it with display.drawBitmap(x, y, picture, width, height, SSD1306_WHITE), then display.display(). Keep the array in flash with PROGMEM, so it doesn't take RAM the screen's copy needs: a full-screen picture is 1,024 bytes.

Can I use another font or bigger text?

For bigger text, display.setTextSize(n) scales the built-in font, as this sketch's size 3 does. For a smoother font, the GFX library comes with others, such as FreeSans: include one and choose it with display.setFont(&FreeSans9pt7b). Each font adds to the sketch's flash.

Can I use a 128 × 32 OLED?

Yes, with two changes: display(128, 32, …), and a layout that fits half the height, such as the percentage beside the bar instead of above it.

How do I find my OLED's I²C address?

Most 128 × 64 modules answer at 0x3C and some at 0x3D; the number on the back of the board is often written as 0x78 or 0x7A, the same addresses shifted one bit left. If you're unsure, try 0x3D after 0x3C, or upload the I²C scanner sketch with the OLED connected and set the Serial Monitor to 9600 baud: it lists every address that answers. Upload this sketch again afterwards and return to 115200.

Which pins are SDA and SCL on other boards?

On an Uno or Nano, A4 is SDA and A5 is SCL; the Uno R3 also has them as the two pins beside AREF. On a Mega they're 20 and 21. On an ESP32 they're GPIO 21 and 22 by default; see the ESP32 guide.

Does the OLED run on 3.3 V or 5 V?

It depends on the module. The SSD1306 chip's logic supply is 1.65 to 3.3 V, so a module wired to a 5 V Uno needs a regulator for its supply and SDA and SCL lines that tolerate the Uno's 5 V. Modules sold for 5 V Arduino boards are built for that, and wire straight to the Uno's 5V, A4 and A5; check that the listing says so. A module sold for 3.3 V only needs a 3.3 V supply and an I²C level shifter, which this guide doesn't cover.

Does it need a backlight?

No. Each pixel is an organic LED that gives its own light, so black pixels are simply off. The SSD1306 also makes the higher voltage the panel needs itself, with a built-in charge pump, from the module's supply.

Simulating the OLED in Cirkit Designer

Cirkit's OLED is an SSD1306 that answers the Adafruit library over the board's real I²C pins: its display memory, addressing modes, row and column mapping, display on and off, inverse, contrast and scrolling follow Solomon Systech's datasheet, so the same code runs on hardware. It is tested on the Arduino Uno, the ESP32-S3 and the classic ESP32.

Where it differs from a real module: it answers only at 0x3C, accepts a 2.7 to 5.5 V supply as a regulated module would, and starts with a blank screen, where a real chip's memory isn't guaranteed to start cleared. Brightness follows the contrast setting in proportion, not as measured light. The knob is a 10 kΩ potentiometer with 270° of travel and no noise, wear or tolerance. On real hardware, check your module's address first: if it answers at 0x3D, use 0x3D in the sketch you upload to it, and keep 0x3C in Cirkit, whose screen answers only there.

References