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.

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.
The knob on A0
The screen redraws each time the percentage changes.
What the OLED shows
The display's 128 × 64 pixels, enlarged.
The screen lights up when the simulation runs.
Arduino Uno serial monitor115200 baud
What the code does
The sketch reads the knob, turns it into a percentage, and draws the number and a bar on the screen.
// 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('%');
}Adafruit_SSD1306 display(128, 64, &Wire, -1);Describes the screen: 128 × 64 pixels on the Uno's I²C pins, A4 and A5. The
-1means the module has no reset pin wired.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_DISPLAYand stops (see troubleshooting).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.
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.
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.
| Pixels | 128 × 64, one colour, each lighting itself |
|---|---|
| Controller | Solomon Systech SSD1306 |
| Interface | I²C: SDA (data) and SCL (clock, printed SCK on many modules) |
| Address | 0x3C, or 0x3D on some modules |
| Supply | 3.3 V or 5 V, as the module is sold for |
| RAM it needs | 1 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
Wire it
Four wires for the screen, three for the knob.
Tap a connection to see it on the circuit.
Pin Connect to the Uno Show OLED VDD (VCC) 5V Show OLED GND GND Show OLED SDA A4 Show OLED SCK (SCL) A5 Show Knob, one outer leg 5V Show Knob, middle leg A0 Show Knob, other outer leg GND Show The knob's outer legs are interchangeable: swapped, turning it the same way lowers the reading instead of raising it.
Get the code
I'm using:Steps 2 and 3 follow the tool you pick.
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.
Then copy the sketch into a new one:
How it works line by line is in what the code does, above.
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
Select a device port
Select the device port for uploading code and serial communications
COM3 (Arduino Uno)- Open Build
- Choose Upload firmware
- Click Select Port
- Pick COM3 (Arduino Uno)
- Click Upload to Device
- Open Upload output and serial monitor
- 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
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 baudCompiling 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.
- Click the board menu
- Pick Arduino Uno on COM3
- Click Upload
- Wait for Done uploading
- Click Serial Monitor
- 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.

With the knob a quarter of the way round, the screen shows 25 % and a quarter-full bar. Device SerialA0=512 50%A0=257 25%A0=1023 100%A0=0 0%OutputSerial MonitorA0=512 50%A0=257 25%A0=1023 100%A0=0 0%Not working? See troubleshooting.

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
0x3Cindisplay.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.
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.
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:
// 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 | |
|---|---|
| Memory | The 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 time | Each 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. |
| Screens | One 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. |
| Brightness | Each pixel is on or off, in the panel's one colour; the contrast setting dims or brightens the whole screen in 256 steps. |
| Supply | The 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?
| Shows | Interface | RAM on an Uno | Choose it for | |
|---|---|---|---|---|
| SSD1306 OLED | 128 × 64 pixels, one colour | I²C; SPI on 7-pin modules | 1 KB for the screen's copy | Text, numbers and simple graphics on a small, sharp screen |
| SH1106 OLED | 128 × 64 pixels, one colour | I²C or SPI | 1 KB for the screen's copy | The same kind of screen; it needs the Adafruit SH110X library instead |
| 16 × 2 LCD (HD44780) | Text: 16 characters on each of 2 lines | Parallel, or I²C through an add-on backpack board | No copy of the screen; the LCD keeps its own 80 characters | Plain text, a character at a time, when the sketch needs its RAM |
| ILI9341 TFT | 240 × 320 pixels, in colour | SPI | No copy of the screen; the library draws straight to it | Colour, 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
- Solomon Systech SSD1306 datasheet, revision 1.1 (hosted by Adafruit)
- Adafruit SSD1306 library, version 2.5.15
- Adafruit GFX library, version 1.12.5 (text sizes: each character advances 6 pixels at size 1)
- Adafruit SH110X library, version 2.1.15, for SH1106 and SH1107 OLEDs
- Adafruit GFX library guide: using fonts
- Adafruit GFX library guide: graphics primitives
- Adafruit guide: monochrome OLED breakouts
- Arduino: Inter-Integrated Circuit (I²C) protocol and its pins
- Arduino reference: analogRead()
- Arduino memory guide (Uno: 2 kB SRAM)
- Hitachi HD44780 LCD controller datasheet
- Adafruit guide: I²C/SPI character LCD backpack
- Ilitek ILI9341 TFT controller datasheet
- Adafruit ILI9341 library, version 1.7.0
- NXP I²C-bus specification (UM10204): each byte is 8 data bits and an acknowledge

