Why must the sketch folder have the same name as the .ino file?

Arduino IDE treats a sketch as a folder containing a .ino file with the same name. If the names differ, the IDE offers to move the file into a new folder, or refuses to open it. Renaming the folder to match avoids that.

Why is my ESP8266 board missing from Arduino IDE?

The ESP8266 package is not in the default board list. Add https://arduino.esp8266.com/stable/package_esp8266com_index.json under File, Preferences, Additional boards manager URLs, then install esp8266 by ESP8266 Community in the Boards Manager.

Why does the Serial Monitor say SSD1306 allocation failed?

The sketch could not talk to the display. Check that VCC is on 3V3, that SDA and SCL are on the right pins, and try address 0x3D instead of 0x3C.

How do I get this code for a different board?

Open OLED Animation Maker on oledanimationmaker.com, pick your board and library from its board menu, import your clip or GIF and click Get the Code.

Upload an OLED Animation from GitHub to ESP8266, Step by Step

Arduino · ESP8266 · SSD1306 · Beginner guide

Pixel art of an OLED module wired to a microcontroller board, the cover for the guide on uploading an OLED animation from GitHub to ESP8266

Most of the OLED projects on this site live in a GitHub repository, and they all work the same way: a single .ino sketch with the animation frames stored inside it. If you've never done this before, a few Arduino IDE rules trip people up: the folder name, the board package that isn't installed by default, and the pin names on the OLED. This guide covers every step once, so each project page can stay focused on its own animation.

Everything here was built and tested on an ESP8266 (NodeMCU or Wemos D1 Mini) with a 0.96" SSD1306 I2C OLED. If you use another board, jump to the section on generating code for it.

What you need

Item	Notes
ESP8266 board	NodeMCU or Wemos D1 Mini. Large animations need a version with 4MB flash
OLED	0.96" SSD1306, I2C, 128×64. It has four pins: GND, VCC, SCL, SDA
Wires	Four female-to-female Dupont jumpers, or a breadboard with male-to-female ones
USB cable	It must carry data. Some cheap cables only charge
Computer	Windows, macOS or Linux with Arduino IDE 2.x

The steps

Download the code On the GitHub repo, click the green Code button, then Download ZIP. People who use git can run git clone with the repo's address instead.
Extract the ZIP Right-click it and choose Extract All (on a Mac, double-click it). GitHub names the folder after the repository with -main on the end, so a repo called Dussehra gives you Dussehra-main.
Rename the folder to match the sketch Arduino IDE treats a sketch as a folder holding a .ino file with the same name. If a repo contains main.ino, rename the folder to main. If the repo has an inner folder with its own .ino (the Batman project is an example), rename that inner folder instead. Skip this and the IDE offers to move your file into a new folder, or refuses to open it.
Install the board package and two libraries (first time only) The ESP8266 isn't in Arduino IDE's default board list. Open File → Preferences, paste https://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional boards manager URLs and click OK. Then open Tools → Board → Boards Manager, search esp8266 and install esp8266 by ESP8266 Community. Finally open Tools → Manage Libraries and install Adafruit SSD1306 and Adafruit GFX Library (accept the dependencies if asked).
Open the sketch Choose File → Open and select the .ino file inside the renamed folder. Large animation files take a moment to load.
Wire the OLED Four wires, as in the diagram below. Power the screen from 3V3, not 5V.
Choose the board and upload Under Tools set Board to NodeMCU 1.0 (ESP-12E Module) (or LOLIN(WEMOS) D1 R2 & mini for a D1 Mini), pick a 4MB option for flash size, and select your Port. Click Upload.

Wiring diagram

ESP8266 NodeMCU / Wemos D1 Mini: SDA to D2 (GPIO4), SCL to D1 (GPIO5)

An I2C display needs just two signal wires: SDA (data) and SCL (clock), plus power and ground. On the ESP8266 the default I2C pins are D2 = GPIO4 for SDA and D1 = GPIO5 for SCL, and the sketches here set exactly those pins. The diagram is a schematic, so the pins on your real board sit in a different order: match the names, not the positions.

VCC to 3V3. Most OLED modules accept 3.3V to 5V, but the ESP8266's pins are 3.3V, so 3V3 keeps everything at the same level.
The address is usually 0x3C. A few modules are strapped to 0x3D. If the screen stays black, try that value in the sketch.
Pull-up resistors for SDA and SCL are already on almost every 0.96" module, so you don't add any.
Check the labels. Some modules print the pins in a different order (VCC, GND, SCL, SDA). Read the silkscreen on yours.

Board settings in Arduino IDE

Setting	Value
Board	NodeMCU 1.0 (ESP-12E Module), or LOLIN(WEMOS) D1 R2 & mini
Flash Size	A 4MB option. If the IDE says the sketch is too big, choose a layout with a larger sketch area
Upload Speed	Leave the default. If uploads fail, try 115200
Port	The COM port (Windows) or /dev/cu.* (Mac) that appears when you plug the board in

If no port appears, your computer probably needs the USB chip's driver. NodeMCU and D1 Mini boards use a CH340 or a CP210x chip, and the chip name is printed on the board.

What success looks like

After the upload finishes, the board restarts and the animation starts straight away. Open Tools → Serial Monitor and set the speed to 115200. If the display starts correctly there's usually no message at all, and if it can't find the screen you'll see SSD1306 allocation failed. The Batman video player is different: it prints a status line every second with the frame number and the real frames per second.

Speed, frames and flash

Every full-screen 128×64 frame is 1,024 bytes (8,192 pixels at one bit each). The sketch shows one frame, waits a fixed number of milliseconds, then shows the next. Two numbers decide how an animation behaves:

Setting	Where	Effect
Delay per frame	`millis() - lastMs >= 67`	67 ms is about 15 fps. A bigger number is slower, a smaller one is faster
I2C clock	`Wire.setClock(400000)`	The default 100 kHz needs about 90 ms to send one frame, so it can't keep up with 67 ms. 400 kHz needs about 23 ms

The flash cost is simple arithmetic: frames × 1,024 bytes. A 150-frame animation takes about 150 KB, a 300-frame one about 300 KB. That is why a classic Arduino Uno (32 KB of flash) can only hold a handful of frames while an ESP8266 with 4MB can hold hundreds. After you compile, the IDE prints a line like Sketch uses N bytes, and that line is the real answer to "will it fit?". For the full explanation see the PROGMEM memory limits guide.

Troubleshooting

What you see	Likely cause	Fix
IDE says the sketch name doesn't match, or offers to move the file	Folder name differs from the `.ino` name	Rename the folder to match the file
ESP8266 isn't in the board list	Board manager URL not added	Add the URL in Preferences, then install esp8266 in the Boards Manager
No COM port appears	Charge-only cable or missing driver	Use a data cable and install the CH340 or CP210x driver
Upload times out	Bad cable, hub or upload speed	Plug straight into the computer, try another cable, lower the upload speed
"Sketch too big" or "text section exceeds"	Too many frames for the flash layout	Pick a 4MB layout with a bigger sketch area, or generate fewer frames
Screen stays black	Wiring, power or address	Re-check the four wires, use 3V3, try `0x3D`. See the blank screen checklist
Serial shows "SSD1306 allocation failed"	The display wasn't found	Same checks as above
Picture shifted or noisy at the edge	The module is an SH1106, not an SSD1306	Read the SH1106 guide
Animation looks slow	The I2C bus is the bottleneck	Add `Wire.setClock(400000);` after the display starts
Board keeps resetting	Something blocks for too long	Keep `yield()` or short waits in the loop
Compile errors about Adafruit_*	Libraries missing	Install Adafruit SSD1306 and Adafruit GFX

Using a different board

The sketches on this site are built for the ESP8266, and editing one by hand for another chip is easy to get wrong because the I2C pins, the memory layout and the library calls all differ. The reliable way is to generate fresh code for your board on our website:

Open OLED Animation Maker in Chrome or Edge.
Choose your board from the menu. It lists 24, including Arduino Uno, Nano and Mega, many ESP32 types, the ESP8266, and Raspberry Pi Pico.
Choose the library (Adafruit SSD1306, Adafruit SH110X or U8g2) to match your display.
Import a short GIF or video that you have the right to use, then adjust the threshold and frame count.
Click Get the Code and paste it into Arduino IDE.

You can also try the animation first in the online OLED simulator. If you want to know how a clip becomes frames, read GIF to OLED and Video to OLED.

FAQ

Is this free?

Yes. The tool, the guides and the GitHub sketches are free to use for learning and personal projects.

Will the animation play sound?

No. An SSD1306 only shows pictures, and these sketches don't drive a speaker. Play audio from your phone, or add a speaker module yourself.

Can I swap in my own clip?

Yes. Import it in OLED Animation Maker and export a new sketch, then follow the same steps. Use only clips you have the right to convert.

Why do I need to rename the folder every time?

GitHub names the downloaded folder after the repository, and Arduino IDE needs that folder to match the sketch file. It's a one-second fix, and the IDE's own prompt to move the file does the same thing.

Related guides

Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, Assemble Studio for your name and logo animations, and the Shadow Box Lamp Generator for your 3D-printed shadow lamps. See all tools.