Wokwi SSD1306 OLED Simulator: Arduino Uno and ESP32 Step by Step

By Ashish · Oct 29, 2026 · 8 min read · Tools

Wokwi SSD1306 projects are how I test OLED sketches when the real board is at the other end of the lab. Wokwi is a free online simulator that runs real Arduino and ESP32 firmware in your browser, and it includes a 128x64 SSD1306 OLED part. You wire it, add the library, paste a sketch and press play. The pixels it draws match what a real 0.96 inch module would show.

This walkthrough builds the same project twice, once on an Arduino Uno and once on an ESP32, then shows how to paste an animation exported from the OLED Animation Maker. At the end I compare Wokwi with the screen-only OLED Simulator on this site, because they solve different problems.

Step 1: create a Wokwi project with an OLED

1. Go to wokwi.com and start a new Arduino Uno project (or ESP32 for the second version).
2. Click the blue + button above the diagram and search for SSD1306. Add the "SSD1306 OLED display" part.
3. Drag wires from the OLED pins to the board. The OLED part has four pins: GND, VCC, SCL and SDA.

That is the same wiring as real hardware, which is the point. When the simulation works, you can copy the wiring to your breadboard one wire at a time. The pin table for more boards is in my Arduino OLED example code post.

Step 2: the diagram.json (Uno version)

Every Wokwi project stores its circuit in a diagram.json tab. Instead of dragging wires, you can paste this version into that tab. It places an Uno and an SSD1306 and connects the four wires.

{
  "version": 1,
  "author": "OLED Animation Maker",
  "editor": "wokwi",
  "parts": [
    { "type": "wokwi-arduino-uno", "id": "uno", "top": 0, "left": 0, "attrs": {} },
    { "type": "board-ssd1306", "id": "oled1", "top": -120, "left": 90, "attrs": { "i2cAddress": "0x3c" } }
  ],
  "connections": [
    [ "oled1:GND", "uno:GND.1", "black", [] ],
    [ "oled1:VCC", "uno:5V", "red", [] ],
    [ "oled1:SCL", "uno:A5", "green", [] ],
    [ "oled1:SDA", "uno:A4", "blue", [] ]
  ],
  "dependencies": {}
}

If the editor shows a red dot on a wire after you paste, a pin name did not match. Delete that wire and drag it by hand. Wokwi then writes the correct pin name into the file for you, which is also a quick way to learn the names.

Step 3: add the libraries

Open the Library Manager tab and add Adafruit SSD1306. Wokwi keeps the list in a file called libraries.txt. You can also edit it directly, one library per line:

# Wokwi Library List
Adafruit SSD1306
Adafruit GFX Library

For U8g2, add a line that says U8g2. Wokwi downloads the libraries each time the simulation starts, so the first run takes a few seconds longer.

Step 4: the sketch

Paste this into sketch.ino and press the green play button. You should see text, a frame and a bouncing dot.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 display(128, 64, &Wire, -1);
int x = 10, dx = 3;

void setup() {
  Serial.begin(115200);
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println("SSD1306 not found");
    while (true) {}
  }
}

void loop() {
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("Wokwi + SSD1306");
  display.drawRect(0, 16, 128, 48, SSD1306_WHITE);
  display.fillCircle(x, 40, 5, SSD1306_WHITE);
  display.display();
  x += dx;
  if (x < 6 || x > 121) dx = -dx;
  delay(30);
}

If the screen stays dark, open the serial monitor at the bottom. "SSD1306 not found" means SDA and SCL are swapped or the address does not match the part's i2cAddress attribute.

The ESP32 version

Start an ESP32 project instead, add the same OLED part, and wire VCC to 3V3, SDA to GPIO 21 and SCL to GPIO 22. The sketch above runs unchanged, because the ESP32 Arduino core uses 21 and 22 as the default I2C pins. If you wire other GPIOs, start the bus yourself before the display:

void setup() {
  Wire.begin(16, 17);      // SDA, SCL on any free GPIOs
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
}

The ESP32 simulation is slower to compile than the Uno one, so be patient on the first run. My ESP32 OLED animation guide covers the real hardware side.

Test an animation from OLED Animation Maker in Wokwi

1. Open the OLED Animation Maker, pick a template or import a GIF, and set the display to SSD1306 128x64 at address 0x3C.
2. Choose Arduino Uno (or ESP32) as the board and click Get the Code.
3. Replace everything in Wokwi's sketch.ino with the exported sketch. Keep libraries.txt as above.
4. Press play. The animation runs at roughly the frame rate the real board would manage.

This is a great way to check memory before you buy parts. Wokwi compiles for the real chip, so an animation too large for an Uno fails to build here with the same "Sketch too big" error you would get in the Arduino IDE. Robot faces from the OLED Robot Eyes generator paste in the same way and are a fun first test, since the eyes blink and change mood on their own.

Wokwi vs the OLED Simulator on this site

I use both. I draw and tune the frames in the OLED Simulator, where changing a pixel shows up instantly, then I paste the exported sketch into Wokwi to check it alongside a button or a sensor. The U8g2 vs Adafruit comparison is also easy to try in Wokwi, since you can swap libraries in seconds.

Limits worth knowing

• SH1106 quirks are not simulated. The 2-pixel offset of 1.3 inch modules only shows on real hardware. See SH1106 vs SSD1306.
• One OLED size. The part is 128x64. For a 0.91 inch 128x32 layout, run 128x32 code and use the top half.
• Timing is approximate. Frame rates are close to real boards, but always confirm on hardware before you tune delays to the millisecond.
• Power and wiring faults do not exist. A loose jumper or a missing pull-up only shows up on the bench. The blank screen fix helps there.

Popular searches: wokwi ssd1306 · wokwi oled · ssd1306 simulator · arduino oled simulator online · wokwi esp32 oled · wokwi diagram.json oled · oled simulator online

Frequently asked questions

Related guides you might like

• Arduino OLED example code (10 sketches)
• ESP32 OLED animation guide
• Arduino OLED display tutorial
• U8g2 vs Adafruit SSD1306
• Raspberry Pi Pico + OLED in Arduino IDE
• Live-connect a real OLED over USB

Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, the OLED Simulator to preview before you flash, OLED Robot Eyes for animated robot faces, Image to Byte Array for your logos, and Assemble Studio for your name and logo animations. See all tools.