ESP32 OLED Bairan Song Lyrics Visualizer

Wiring Schematic

View full-size circuit ↗

LT

YOUR PROJECT LEARNING PATH

Build it with confidence.

Progress saves on this device

01

Project overview

Know what you’re building before you start wiring.

Create an ESP32-powered lyrics visualizer that displays Bairan song lyrics as animated bitmap frames on a 128×64 SSD1306 OLED using I²C communication.

Follow this guide to assemble the display, install the required libraries, upload the animation sketch, and verify smooth frame playback while learning how to adjust animation timing.

Before you power up

Disconnect USB power before changing wiring, and connect the OLED to 3.3 V only if your specific display module supports that supply voltage.

PROJECT ROADMAP3 project stages

✓

Prepare your kitConfirm the components and tools

⌁

Assemble the circuitFollow the build steps in order

⌘

Upload and testCheck the output and resolve issues

Start the build

02

Components required

Gather these parts before you begin.

ESP32 Development BoardRuns the animation sketch and sends bitmap frames to the OLED display through I²C.× 1

SSD1306 OLED Display (128×64)Displays the animated Bairan lyrics using sequential monochrome bitmap frames.× 1

BreadboardProvides a convenient platform for arranging the display and organizing circuit connections.× 1

Jumper WiresConnect the OLED power, ground, SDA, and SCL pins to the ESP32.× 4

USB Data CablePowers the ESP32 and transfers the animation firmware from your computer.× 1

03

Build the project

Work through one focused step at a time. You can revisit any step whenever you need.

STEP 010 / 5 complete

BUILD STAGE 0120% of guide

Prepare the ESP32 and OLED

With USB power disconnected, position the ESP32 and SSD1306 OLED on the breadboard. Identify the display's VCC, GND, SDA, and SCL pins.

Check the pin labels on your specific modules because their physical order can vary. Keep the connections accessible for inspection before applying power.

Mark this step completeKeep your progress as you build

1 of 5

04

Software & tools

Install these before uploading the firmware.

Arduino IDEWrite, compile, and upload the ESP32 animation sketch from your computer.

ESP32 Board PackageProvides ESP32 board definitions, compiler support, and firmware upload tools in Arduino IDE.

Adafruit GFX LibraryProvides graphics functions for rendering bitmap frames on the OLED display.

Adafruit SSD1306 LibraryInitializes and controls the SSD1306 OLED through its supported I²C interface.

USB-to-Serial DriverEnables computer communication when the ESP32 board requires a compatible USB-to-serial driver.

05

Expected output

Compare your build with the result described here.

FINAL CHECKPOINT

After uploading the sketch, the SSD1306 OLED should initialize and display the Bairan lyrics as a sequence of animated bitmap frames, according to the supplied animation data.

Check that frames appear in the intended order and that playback speed matches the configured delay. If the sketch is designed to loop, confirm that the sequence restarts after its final frame.

06

Troubleshooting & fixes

Choose the issue that best matches what you’re seeing.

01OLED Display Remains Blank

Try these checks

Verify OLED VCC and GND connections, then check SDA on GPIO 21 and SCL on GPIO 22. Confirm the module's I²C address, display initialization settings, and supported voltage before testing again.

02Animation Frames Look Corrupted

Try these checks

Confirm the Adafruit GFX and SSD1306 libraries are installed correctly and that bitmap.h is available in the sketch's required location. Check bitmap dimensions, array definitions, and display-buffer updates.

03Animation Timing Is Incorrect

Try these checks

Check that ANIM_FRAME_COUNT matches the number of available frames and that the delay value uses milliseconds as intended. Adjust the frame interval gradually and verify the sequence after each upload.