ESP32 OLED Proposal Animation
Wiring Schematic
View full-size circuit ↗
YOUR PROJECT LEARNING PATH
Build it with confidence.
Project overview
Know what you’re building before you start wiring.
Create an ESP32-powered proposal animation featuring a galaxy particle effect, a forming heart, a decorative ring box, and a rising diamond ring on a 128×64 SSD1306 OLED display.
Follow this guide to wire the display, install the required libraries, upload the animation sketch, and explore cinematic transitions, particle effects, mechanical motion, and a typewriter-style proposal message.
Disconnect USB power before changing wiring, and connect the OLED to 3.3 V only if your specific display module supports that supply voltage.
Components required
Gather these parts before you begin.
Build the project
Work through one focused step at a time. You can revisit any step whenever you need.
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 before starting the wiring.
Check the pin labels on your specific modules because their physical order can vary. Keep the connections accessible so you can inspect the circuit before applying power.
Connect OLED Power and Ground
Connect OLED VCC to the ESP32 3.3 V output and OLED GND to ESP32 GND, provided the specific display module supports 3.3 V operation.
Inspect the power polarity and confirm that the ground connection is secure. Keep USB power disconnected until you have verified both connections against the module labels.
Connect the I²C Data Line
Connect the OLED SDA data pin to ESP32 GPIO 21. This line transfers display commands and graphical data from the microcontroller to the OLED.
Trace the SDA wire at both ends and confirm that it reaches GPIO 21, not SCL or a power connection. Keep the wiring secure and unobstructed.
Connect the I²C Clock Line
Connect the OLED SCL clock pin to ESP32 GPIO 22. The clock line synchronizes data transfers between the ESP32 and the display during animation rendering.
Verify that SDA and SCL are not swapped and compare the wiring with your board's pin labels. Confirm that the sketch uses the same GPIO assignments.
Upload and Test the Animation
Install the required libraries, select the correct ESP32 board and serial port in Arduino IDE, then compile and upload your verified proposal animation sketch.
Confirm that the galaxy, heart formation, ring box, rising ring, and final text appear in the programmed sequence. If the display remains blank, check wiring and initialization settings.
Software & tools
Install these before uploading the firmware.
Expected output
Compare your build with the result described here.
After uploading the sketch, the SSD1306 OLED should display an animated galaxy of particles that gradually forms a pulsing heart, followed by the transition to a decorative ring box.
The ring box should open, reveal a rising diamond ring with sparkle effects, and transition to the programmed proposal message using a typewriter animation. Verify the sequence against your sketch.
Troubleshooting & fixes
Choose the issue that best matches what you’re seeing.
01OLED Display Remains Blank
Verify OLED VCC and GND connections, then check SDA on GPIO 21 and SCL on GPIO 22. Confirm your module's I²C address and ensure the sketch initializes the display with the correct dimensions.
02Animation Graphics Appear Distorted
Confirm the Adafruit GFX and SSD1306 libraries are installed correctly. Review particle positions, drawing coordinates, display-buffer updates, and screen boundaries to identify graphics that exceed the 128×64 display area.
03Animation Stages Transition Incorrectly
Review the stage-duration constants and confirm animation state transitions occur in the intended order. Check elapsed-time calculations, easing functions, particle updates, and typewriter delays against the sequence defined in your sketch.