OLED guides · On this page

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).

Ready
Open in Cirkit Designer

The knob on GPIO 34

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.

ESP32 serial monitor115200 baud

Output appears here when the simulation runs.

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.

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>

// 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('%');
}
  1. 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.

  2. Adafruit_SSD1306 display(128, 64, &Wire, -1);

    The screen, on the ESP32's default I²C pins: Wire uses GPIO 21 for SDA and 22 for SCL unless you choose others.

  3. 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.

  4. 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
  1. 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.

    PinConnect to the ESP32Show
    OLED VDD (VCC)3V3Show
    OLED GNDGNDShow
    OLED SDAGPIO 21Show
    OLED SCK (SCL)GPIO 22Show
    Knob, one outer leg3V3Show
    Knob, middle legGPIO 34Show
    Knob, other outer legGNDShow

    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.

  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.

    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.

    ESP32 Dev ModuleLIBRARY 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 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
    OLED on an ESP32FileEditExportHelp
    DesignCodeSimulateBuild
    1Parts & purchasing2Assemble3Upload firmware
    ESP32Edit Code

    Board

    ESP32 Change

    2

    Port

    Select PortCOM4 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 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.
    Device SerialStop

    Read serial data from your device.

    Start Serial Monitor
    Listening on COM4 at 115200 baud
    IO34 1660 mV 50%
    IO34 835 mV 25%
    IO34 3139 mV 95%
    IO34 142 mV 4%
    Select port

    Select a device port

    Select the device port for uploading code and serial communications

    COM4 (ESP32)
    1. Open Build
    2. Choose Upload firmware
    3. Click Select Port
    4. Pick COM4 (ESP32)
    5. Click Upload to Device
    6. Open Upload output and serial monitor
    7. 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
    Select BoardESP32 Dev Module

    Select other board and port

    ESP32 Dev ModuleCOM4
    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 baud

    Compiling 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.

    1. Click the board menu
    2. Pick ESP32 Dev Module on COM4
    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 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.
    The OLED on the ESP32 showing KNOB and 835 mV on the top line, 25% in large digits, and a bar a quarter full.
    With the knob a quarter of the way round, GPIO 34 reads 835 mV: 25 % of 3.3 V.

    Not working? See troubleshooting.

    Next guideRead a DHT11 on the same ESP32Temperature and humidity on GPIO 4, at 3.3 V, with Adafruit's DHT library.

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 ESP32ESP32-S3
Default SDA and SCLGPIO 21 and 22GPIO 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-onlyGPIO 34 to 39, fine for a knobNone
Avoid: flashGPIO 6 to 11GPIO 26 to 32, and 33 to 37 on modules with octal flash or octal PSRAM
Not on every moduleGPIO 16 and 17 aren't brought out on ESP32-WROVER-E modulesCheck your module's datasheet
Avoid: boot (strapping)GPIO 0, 2, 5, 12 and 15GPIO 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:

Add to setup(), before display.begin()
// 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 before display.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

  • 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