Show a Reading on an OLED Display with an ESP32
Show a knob's reading on an SSD1306 OLED with an ESP32, with the same library and nearly the same code as on an Arduino. The screen runs at 3.3 V on I²C pins GPIO 21 and 22, and the sketch reads the knob with analogReadMilliVolts(), because the ESP32's raw analog count isn't proportional to the voltage.
This guide uses an ESP32 DevKitC, the common ESP32-WROOM-32 board, with a knob on GPIO 34 and the OLED drawing how far it's turned. On an ESP32-S3 the pins differ; see which pins work. For the screen itself, see the OLED guide.
Try it first, no parts needed
This is the whole project, wired and running in your browser. Press Run simulation and turn the knob. The OLED shows the voltage on GPIO 34 and how far that is towards 3.3 V. At the very ends it stops short of 0 % and 100 %, as a real ESP32 does (see reading the knob).
The knob on GPIO 34
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.
ESP32 serial monitor115200 baud
What the code does
The sketch reads the knob in millivolts, turns it into a percentage, and draws the number and a bar on the screen.
// Turn the knob on GPIO 34: the OLED shows its voltage
// and how far that is towards 3.3 V, with a bar.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
// GPIO 34 is on ADC1, which still reads while Wi-Fi runs.
const int KNOB_PIN = 34;
const int SUPPLY_MV = 3300;
// 128 x 64 pixels on the ESP32's default I2C pins:
// SDA on GPIO 21, SCL on GPIO 22. -1: 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() {
// Millivolts, corrected with the chip's calibration:
// the raw analogRead() count isn't proportional to
// the voltage on an ESP32.
int millivolts = analogReadMilliVolts(KNOB_PIN);
int percent = round(millivolts * 100.0 / SUPPLY_MV);
// 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(millivolts);
display.print(F(" mV"));
display.setTextSize(3);
display.setCursor(0, 16);
display.print(percent);
display.print('%');
// A bar across the bottom, filled in proportion.
int barWidth = map(millivolts, 0, SUPPLY_MV, 0, 124);
display.drawRect(0, 52, 128, 12, SSD1306_WHITE);
display.fillRect(2, 54, barWidth, 8, SSD1306_WHITE);
display.display();
Serial.print(F("IO34 "));
Serial.print(millivolts);
Serial.print(F(" mV "));
Serial.print(percent);
Serial.println('%');
}const int KNOB_PIN = 34;The knob's pin, GPIO 34. It's on ADC1, which keeps reading while Wi-Fi runs, unlike ADC2's pins; and it's input-only, which is all a knob needs. See which pins work.
Adafruit_SSD1306 display(128, 64, &Wire, -1);The screen, on the ESP32's default I²C pins:
Wireuses GPIO 21 for SDA and 22 for SCL unless you choose others.int millivolts = analogReadMilliVolts(KNOB_PIN);Reads the knob in millivolts, corrected with the chip's calibration. On an ESP32 the raw
analogRead()count isn't proportional to the voltage, so it would misread the knob.display.display();Sends the finished picture to the screen. The drawing before it is the same as on the Arduino, except that the top line shows millivolts and the bar follows them.
Build it on an ESP32
Now with real parts. Wire it, get the code, then upload it and turn the knob. Not sure which pin is which? See the OLED pinout.
You'll need
- An ESP32 DevKitC (ESP32-WROOM-32) and a USB cable that carries data
- An SSD1306 128 × 64 I²C OLED module (four pins) that runs on 3.3 V: one sold for 3.3 V, or for 3.3 to 5 V
- A 10 kΩ potentiometer, the knob
- A breadboard and seven jumper wires
- Software to upload the sketch: either Cirkit Designer, free in your browser, or the Arduino IDE with Espressif's ESP32 boards installed
Wire it
Four wires for the screen and three for the knob, all powered from 3V3.
Tap a connection to see it on the circuit.
Pin Connect to the ESP32 Show OLED VDD (VCC) 3V3 Show OLED GND GND Show OLED SDA GPIO 21 Show OLED SCK (SCL) GPIO 22 Show Knob, one outer leg 3V3 Show Knob, middle leg GPIO 34 Show Knob, other outer leg GND Show Power the OLED from 3V3, not 5V. The module pulls SDA and SCL up to its own supply, and the ESP32's pins aren't 5 V tolerant. Check that your module's listing says it runs on 3.3 V.
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.
With the ESP32 boards installed (esp32 by Espressif, in the Boards Manager), open the Library Manager (1), search for Adafruit SSD1306 (2), and install it (3); when it asks about dependencies, choose Install all.
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 ESP32. In Cirkit, open the Build tab, then Upload firmware: click Select Port and pick your board, 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
COM4 (ESP32)- Open Build
- Choose Upload firmware
- Click Select Port
- Pick COM4 (ESP32)
- Click Upload to Device
- Open Upload output and serial monitor
- Click Start Serial Monitor
In the Arduino IDE, choose ESP32 Dev Module 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
esp32_oled_knob_gauge.ino// Turn the knob on GPIO 34: the OLED shows its voltage // and how far that is towards 3.3 V, with a bar. #include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h>
OutputSerial Monitor115200 baudCompiling sketch...
Sketch uses 328399 bytes (25%) of program storage space. Maximum is 1310720 bytes.
Global variables use 22456 bytes (6%) of dynamic memory, leaving 305224 bytes for local variables. Maximum is 327680 bytes.
Uploading...
IO34 1660 mV 50%
IO34 835 mV 25%
IO34 3139 mV 95%
IO34 142 mV 4%
Done uploading.
- Click the board menu
- Pick ESP32 Dev Module on COM4
- Click Upload
- Wait for Done uploading
- Click Serial Monitor
- Check it is set to 115200 baud
It works when:
- The screen shows the millivolts, a percentage and a bar, and turning the knob moves them nearly from end to end. The ends flatten out short of 0 % and 100 %, at 4 % and 95 % in Cirkit and near there on your board.
- After a few start-up lines from the ESP32's boot ROM, the Serial Monitor prints a line each time the percentage changes, such as
IO34 835 mV 25%with the knob a quarter of the way round, as pictured.

With the knob a quarter of the way round, GPIO 34 reads 835 mV: 25 % of 3.3 V. Device SerialIO34 1660 mV 50%IO34 835 mV 25%IO34 3139 mV 95%IO34 142 mV 4%OutputSerial MonitorIO34 1660 mV 50%IO34 835 mV 25%IO34 3139 mV 95%IO34 142 mV 4%Not working? See troubleshooting.

Which ESP32 pins work for the OLED and the knob
SDA and SCL need pins that can drive the bus as well as read it; the knob needs a pin on ADC1, the analog input that keeps working while Wi-Fi runs. GPIO 21, 22 and 34 are all fine on a classic ESP32.
| Classic ESP32 | ESP32-S3 | |
|---|---|---|
| Default SDA and SCL | GPIO 21 and 22 | GPIO 8 and 9 |
| Knob (ADC1) | GPIO 32 to 39; on the DevKitC, 32 to 35, 36 (VP) and 39 (VN) | GPIO 1 to 10 |
| Avoid for SDA and SCL: input-only | GPIO 34 to 39, fine for a knob | None |
| Avoid: flash | GPIO 6 to 11 | GPIO 26 to 32, and 33 to 37 on modules with octal flash or octal PSRAM |
| Not on every module | GPIO 16 and 17 aren't brought out on ESP32-WROVER-E modules | Check your module's datasheet |
| Avoid: boot (strapping) | GPIO 0, 2, 5, 12 and 15 | GPIO 0, 3, 45 and 46 |
ADC2's pins are shared with Wi-Fi, so their reads can fail while it runs; that's why the knob stays on ADC1.
Reading the knob
The ESP32's analog input gives 12 bits, 0 to 4095. But the count isn't proportional to the voltage: in Cirkit, the knob's midpoint, 1.65 V, reads 1872 rather than 2048. At the Arduino core's default attenuation, 11 dB, the classic ESP32 also measures only from about 150 mV to 3,100 mV. So the sketch reads millivolts with analogReadMilliVolts(), which applies the chip's calibration, and shows them as a share of 3.3 V.
Outside about 150 mV to 3,100 mV the input isn't accurate, so the knob's first and last stretch hardly change the reading. In Cirkit the ends read 4 % and 95 %; a real board flattens near there, and each chip a little differently. Put the knob between 3V3 and GND anyway; just expect the ends to flatten.
Using other pins for the OLED
The ESP32 can put I²C on most of its GPIOs. To move it, start Wire on your pins before the screen, choosing pins the table above doesn't rule out:
// Before display.begin(): I²C on GPIO 25 (SDA)
// and 26 (SCL) instead of 21 and 22.
Wire.begin(25, 26);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:
- SDA goes to GPIO 21 and SCK (SCL) to GPIO 22. Swapped, the ESP32 can't reach the screen. On an ESP32-S3 the defaults are GPIO 8 and 9.
- The OLED is wired by its printed labels. VDD (VCC) to 3V3 and GND to GND.
- Moved SDA and SCL?
Wire.begin(sda, scl)comes first. It must run beforedisplay.begin(); see using other pins. - The module runs on 3.3 V. One built only for 5 V boards may stay blank or dim from 3V3; its listing says which.
- The address matches. Most modules answer at 0x3C, some at 0x3D; see finding the address.
The reading stays at one end and the knob doesn't move it
- The knob's middle leg goes to GPIO 34. On an outer leg, the pin sees only 3.3 V or 0 V.
- Both outer legs are connected, one to 3V3 and one to GND.
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 ESP32's own start-up lines, from its boot ROM, come first at the same speed, so they should be readable too. - The sketch prints only when the percentage changes. It prints once at the start; turn the knob to see more.
The board won't start or upload after you moved the OLED
- SDA and SCL are off the boot pins. GPIO 0, 2, 5, 12 and 15 set how the ESP32 starts, and the module's pull-ups can change that; move to pins the pin table allows.
No port appears for the ESP32
- The cable carries data. The board's USB port carries its serial link as well as power, so a cable that only charges powers the board but shows no port.
- The board's USB-to-serial chip has its driver. Its name, such as CP210x, is printed on the chip near the USB socket. The driver usually installs itself; if no port appears, install it from the chip's maker (Silicon Labs for a CP210x).
The upload stops at Connecting..., then says Failed to connect
Connecting..., then says Failed to connect- The board is in download mode. Hold BOOT, press and release EN (RST on some boards), then release BOOT, and upload again.
More causes are in the OLED guide's troubleshooting.
FAQ
Can I power the OLED from 5V on an ESP32?
Not this way: a module powered from 5V may pull SDA and SCL up to 5 V, and the ESP32's pins aren't 5 V tolerant. Power the OLED from 3V3 instead; a module sold for 3.3 V, or for both 3.3 V and 5 V, runs there.
Can I connect two OLEDs to an ESP32?
Yes. On one bus they need different addresses, 0x3C and 0x3D, which only some modules let you change. Otherwise, put the second screen on the ESP32's second I²C bus, Wire1, on two other pins: Wire1.begin(sda, scl), then Adafruit_SSD1306 second(128, 64, &Wire1, -1).
Does the same code work on an ESP32-S3 or an ESP32-C3?
Yes, with two changes. Both default to GPIO 8 for SDA and 9 for SCL, so wire them there or set your own with Wire.begin(sda, scl). Their ADC1 pins differ (GPIO 1 to 10 on the S3, GPIO 0 to 4 on the C3), so move the knob to GPIO 1, an ADC1 pin on both that stays clear of SDA and SCL, and set KNOB_PIN to 1. On the C3 the input measures only up to about 2,500 mV, so the reading tops out near 76 %.
My ESP32 board has an OLED built in. What changes?
Only the pins: use the SDA and SCL pins its maker documents, with Wire.begin(sda, scl) before display.begin(). If the board wires the screen's reset pin, pass that pin in place of -1: Adafruit_SSD1306 display(128, 64, &Wire, resetPin).
Simulating the OLED on an ESP32 in Cirkit Designer
Cirkit runs your compiled sketch on an emulated ESP32, and its OLED answers the Adafruit library over GPIO 21 and 22, as in the OLED guide; the OLED is tested on the classic ESP32, the ESP32-S3 and the Arduino Uno. The ESP32's analog input follows Espressif's default calibration curve, so the raw counts bend as a real chip's do and analogReadMilliVolts() corrects them; it adds no noise, and every chip reads the same, where real ones differ a little.
References
- Espressif esptool: troubleshooting (download mode by hand, the boot log at 115200 baud)
- ESP-IDF: establishing a serial connection (the USB-to-UART bridge and its driver)
- Arduino-ESP32 core, version 3.3.5 (the ADC's default 11 dB attenuation, Wire's default pins)
- Arduino-ESP32: ADC, including analogReadMilliVolts() and the measurable range
- ESP-IDF: ADC on the ESP32, and ADC2 shared with Wi-Fi
- Arduino-ESP32: I²C, Wire.begin() and the default pins
- Espressif ESP32-DevKitC user guide
- Espressif ESP32 datasheet
- Espressif ESP32-S3 datasheet
- Espressif ESP32-C3 datasheet
- Espressif ESP32-WROVER-E datasheet (its pins: no GPIO 16 or 17)
- Solomon Systech SSD1306 datasheet, revision 1.1 (hosted by Adafruit)
- Adafruit SSD1306 library, version 2.5.15

