OLED Animation Maker OLED Maker
🔌 WebSerial · Live OLED

How to Live Connect Your OLED to the Browser (WebSerial)

I'll be honest, the single biggest time-waster in my early OLED projects was the upload cycle. Draw a frame, generate code, upload, wait, watch, notice something's off, repeat. Each upload took 30 to 60 seconds, and I'...

By Ashish May 19, 2026 10 min read WebSerial, Live Preview
📖

A tutorial you can follow

I wrote this for makers. You get the wiring, the code and the mistakes I see most.

🔌

Hardware you already own

It suits SSD1306 and SH1106, and you'll find pin tables where they help.

💻

Code you can paste

Sketches you can upload in Arduino IDE as they are.

✨

A free tool for you

Want more animations? Preview and export them at oledanimationmaker.com.

How to Live Connect Your OLED to the Browser (WebSerial): examples of pixel art and animations on a 128x64 SSD1306 OLED display
ESP32 microcontroller with SSD1306 OLED connected by USB to a laptop running browser live WebSerial animation preview
Live connect: edit in the browser, see frames on your physical OLED instantly.

I'll be honest, the single biggest time-waster in my early OLED projects was the upload cycle. Draw a frame, generate code, upload, wait, watch, notice something's off, repeat. Each upload took 30 to 60 seconds, and I'd do it dozens of times tweaking a single animation. I once spent an entire Saturday afternoon just adjusting the timing on a loading spinner. There had to be a better way.

There is, and it's called live connect using the Web Serial API (WebSerial). Here's the idea: instead of uploading a new sketch every time you change something, you upload one "receiver" sketch once. After that, your browser streams animation frames directly to your OLED over the USB cable. Edit a pixel, and it appears on the physical display instantly. No more upload-wait-repeat. It genuinely changed how I design animations.

The free OLED animation maker has this built in. In this guide, I'll walk you through the complete setup for Arduino Uno, ESP32 and ESP8266. Setup takes about five minutes, and once you've tried real-time preview, you won't want to go back. Let me show you how.

What is WebSerial and why is it useful?

Let me explain the technology quickly, because knowing it helps when you're troubleshooting. WebSerial (the Web Serial API) is a feature in modern browsers that lets a website talk directly to devices connected via USB serial ports, like your Arduino. Yes, a website can talk to your hardware. It sounded wild to me the first time I heard it.

Normally, only desktop programs (like the Arduino IDE) could touch your USB ports. But Google added the Web Serial API to Chrome a few years back, opening up browser-based hardware tools. That's what lets you preview your OLED live without installing any software. Everything happens right in your browser tab.

One important catch: WebSerial only works in Chrome and Edge (and other Chromium-based browsers like Brave or Opera). It does not work in Firefox or Safari, because they haven't implemented the API. So if you're a Firefox user like I used to be, you'll need to switch to Chrome or Edge for this. It's my one complaint, but a worthwhile trade-off for real-time preview.

What you'll need

  • Arduino Uno, Nano, Mega, ESP32, or ESP8266
  • SSD1306 or SH1106 OLED (128×64 is the typical size)
  • A USB cable that supports data (not a charge-only cable, more on this in troubleshooting)
  • Google Chrome or Microsoft Edge browser
  • oledanimationmaker.com, free, runs in your browser, no install

Step 1: Wire the OLED

Connect your I²C OLED to your board (see our Arduino OLED tutorial):

  • Uno/Nano: SDA → A4, SCL → A5
  • ESP32: SDA → GPIO 21, SCL → GPIO 22
  • ESP8266: SDA → D2, SCL → D1
ESP32 board wired to 0.96 inch I2C OLED display with labeled SDA SCL power and ground connections
Correct wiring is required before live connect will work.

Step 2: Configure the tool

  1. Open oledanimationmaker.com
  2. In the header, set Board (Uno, ESP32, etc.)
  3. Set Display, SSD1306 or SH1106, and size (128×64)
  4. Set I²C address, usually 0x3C

The receiver sketch you'll get matches these settings automatically.

Step 3: Upload the WebSerial receiver sketch

  1. Click Connect in the app header, or open the hardware modal
  2. Copy the receiver sketch. It matches your board, display and library
  3. Paste it into Arduino IDE and upload once to your board
  4. Leave your board powered over USB

You only upload this receiver sketch once per project session, unless you change your board or display type.

Step 4: Live connect in the browser

Laptop screen showing OLED animation maker editor with drag and drop workflow for live hardware preview
  1. Click Connect again in Chrome or Edge
  2. Select your board's USB serial port when prompted
  3. Draw, import a GIF or play a template, and you'll see frames stream to your physical OLED
  4. Change the FPS on the timeline and watch it update as you go

This live oled preview workflow is much faster than uploading a full sketch after every edit, and it's ideal when you're tuning ssd1306 animation timing and pixel art.

Troubleshooting live connect (solutions to every issue I've hit)

WebSerial is reliable once it's working, but your first connection might need a little troubleshooting. Here are the exact problems I've run into and how I fix each one:

  • Your USB port isn't listed when you click Connect. This is usually a driver issue. Lots of cheap Arduino clones and ESP boards use CH340 or CP2102 USB chips that need drivers installed. Google "CH340 driver" or "CP2102 driver" for your operating system, install it, and restart your browser. Also, and I've embarrassingly done this, make sure you're using a real data USB cable. Charge-only cables don't have data lines, so your computer can't see the board at all.
  • The OLED stays blank after connecting. This is almost always a settings mismatch. Check that the I²C address in the tool matches your display (try 0x3D if 0x3C doesn't work), and make sure you picked the right display type (SSD1306 vs SH1106). If they don't match, the data goes out but nothing shows.
  • Connect fails or says the port is busy. Only one program can use a serial port at a time. If you've got the Arduino IDE Serial Monitor open, close it. That's the most common culprit. Same goes for any other serial terminal you're running.
  • You're using Firefox or Safari. WebSerial just isn't supported there. Switch to Chrome, Edge, Brave or another Chromium-based browser. There's no workaround. It's a browser limit, not a problem with the tool.
  • ESP8266 won't connect properly. Make sure you're powering it at 3.3V and you're using the D2/D1 pins for SDA/SCL. Check our ESP guide for the full ESP8266 wiring details.

Pro tip: If your connection drops mid-session, don't panic. The receiver sketch is still running on your board. Just click Connect again and pick the port, and you're back in a second or two. A loose USB cable is the usual cause.

Live connect vs Get the Code: when to use each

These two workflows do different jobs, and knowing which to pick will save you time:

  • Use live connect while you're actively designing: editing frames, debugging, tuning the FPS or adjusting pixel art. You get instant feedback, so it's fast.
  • Use Get the Code when your animation is finished and you want it to run standalone. You get a complete sketch that runs on your board with no computer or browser attached. That's what you flash for your final project.

Think of live connect as your "design mode" and Get the Code as your "ship it" mode. I use live connect for 95% of my time building an animation, then I run Get the Code once at the end to bake it into the final project.

Try live connect now, free

Open the tool, upload the receiver once, click Connect, and preview on your own OLED.

Open OLED Animation Maker →

Worked example: first live session on an Uno

Here's the sequence I use when a board has never talked to the site before. It's the same four steps from above: wire, match the tool, upload the receiver once, then click Connect in Chrome or Edge. Firefox and Safari can't open the serial port. Start in Chrome or Edge, even if you browse in something else all day.

  1. Wire a 128×64 SSD1306: Uno SDA to A4, SCL to A5, VCC and GND to the module. ESP32 uses GPIO 21 and GPIO 22, and an ESP8266 NodeMCU uses D2 and D1. Set the tool's I²C address to 0x3C unless you know your module answers on 0x3D.
  2. In the header, set Board to Uno (or whatever you've got), Display to SSD1306 128×64, and the same address. Open Connect and copy the receiver sketch the site shows for those settings. Paste it into a blank Arduino sketch and upload. Leave the USB plugged in. That sketch is what reads frames from the browser, and a normal "Hello World" OLED sketch won't.
  3. Close the Arduino IDE Serial Monitor if it's open, because only one program can hold a port. Click Connect in the site again and pick the same COM or tty device you just uploaded to.
  4. Draw a single white rectangle or play a short template. Your OLED should update without another upload. Change one pixel and wait a moment. If the glass follows the canvas, you're set. Use Get the Code only when you want a standalone sketch that runs with the laptop unplugged.

A 128×64 frame is 1024 bytes of bitmap data. You don't paste that array while live-connecting. The receiver you uploaded already knows how to take each frame from the browser and call the display library. If you change board type, display size, or SSD1306 versus SH1106, copy a fresh receiver and upload it again. The old sketch will still open the port, but it won't paint anything useful.

What to do when Connect does nothing

Most failed sessions are the USB port, not your animation. Walk this list in order before you rewrite the sketch. I'd start at the top.

  • Port busy. Quit Serial Monitor, PuTTY, screen, and any other tab that already clicked Connect. Unplug the board, plug it back in, and try Connect once. Two tabs fighting over one port look like a random failure, but it isn't.
  • Port missing. Charge-only cables never show up. CH340 and CP2102 clones need their driver installed, then a browser restart. After an upload the IDE may still hold the port until you close Serial Monitor.
  • Baud. Don't edit Serial.begin in the receiver you copied from the tool. The site opens the port at the speed that sketch expects. If you changed the baud "to be safe," frames won't line up and the OLED stays on the boot splash or goes blank. Paste the receiver again and upload it untouched.
  • Board reset. Uploading resets the board, and the COM number can change for a few seconds. Wait until the port reappears, then Connect. If the OLED shows the receiver's idle screen and then freezes, press the reset button once, wait for the port to come back, and click Connect again. A loose USB plug drops the session the same way, so replug and reconnect. You don't need to re-upload unless you changed the receiver.
  • Blank OLED with a successful Connect. That's an address or controller mismatch. Try 0x3C, then 0x3D, and check that SSD1306 versus SH1106 in the tool matches the receiver you flashed. Wiring stays A4/A5 on Uno, GPIO 21/22 on ESP32, D2/D1 on ESP8266.
  • Browser. If Connect can't list any ports, you're probably not in Chrome or Edge (or another Chromium browser). The page can't add WebSerial to Firefox or Safari for you.

After a drop, the receiver's still running. Click Connect, choose the port, and keep editing. Re-flash only when your tool settings and the sketch on the board don't match anymore.

Frequently asked questions

Do I upload a new sketch every time I edit a pixel?

No. Upload the receiver from the Connect dialog once. After that, Chrome or Edge streams frames over USB while you draw or play the timeline. Get the Code is the separate export you flash when you want the animation to run with no browser attached.

Connect says the port is busy. What is holding it?

The Arduino Serial Monitor is the usual culprit. Close it, and close any second browser tab that's already connected. Then pick the port again. A charge-only cable or a missing CH340/CP2102 driver means you won't see the port at all, which is a different problem.

The port opens, then the board resets and the OLED stalls. Do I recompile?

No. Press the reset button, wait until the serial port shows up again, and click Connect. Leave the receiver's Serial.begin line as the tool made it. Re-upload only if you've changed board, display size, or SSD1306 versus SH1106.

Related tutorials

Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, Assemble Studio for your name and logo animations, the Shadow Box Lamp Generator for your 3D-printed shadow lamps, Text to STL for your 3D-printed names and keychains, and 3MF to Web to show your 3D prints on any website. New: the Image to Byte Array converter, the OLED Robot Eyes generator and the Lithophane Maker. See all tools.