ESP32 OLED Proposal Animation

Project

ESP32

ESP32 OLED Proposal Animation

Wiring Schematic

ARDUINO / C++

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SH110X.h>
#include <string.h>

// ---------------- Display ----------------
#define SCREEN_WIDTH   128
#define SCREEN_HEIGHT  64
#define OLED_RESET     -1
#define OLED_ADDR      0x3C

// Adjust these if your board wires I2C differently
// (some 38-pin ESP32 DevKits are happier on GPIO4/5 -- swap here if the
// display doesn't init)
#define OLED_SDA       21
#define OLED_SCL       22

Adafruit_SH1106G display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// ---------------- Timing (ms) ----------------
#define FRAME_DELAY           20
#define FLASH_DURATION        450
#define FORM_DURATION         3200
#define HOLD_DURATION         1400
#define BURST_DURATION        900
#define BOX_APPEAR_DURATION   900
#define LID_OPEN_DURATION     1600
#define RING_RISE_DURATION    1300
#define SPARKLE_DURATION      2200

// ---------------- Intro heart / particles ----------------
#define NUM_PARTICLES  50
#define HEART_CX       64
#define HEART_CY       30
#define HEART_SCALE    1.4f

// ---------------- Background stars ----------------
#define NUM_STARS      18

// ---------------- Ring box geometry ----------------
#define BOX_CX         64
#define BOX_BOTTOM     56
#define BOX_W          54
#define BOX_H          24
#define BOX_LEFT       (BOX_CX - BOX_W / 2)
#define BOX_RIGHT      (BOX_CX + BOX_W / 2)
#define HINGE_Y        (BOX_BOTTOM - BOX_H)

#define LID_THICK        5
#define LID_ARM           24.0f
#define LID_MAX_ANGLE      1.92f   // ~110 degrees

#define RING_RX        11
#define RING_RY        4
#define RING_REST_OFFSET 10

// ---------------- State machine ----------------
enum Stage {
  STAGE_FLASH,
  STAGE_FORM,
  STAGE_HOLD,
  STAGE_BURST,
  STAGE_BOX_APPEAR,
  STAGE_LID_OPEN,
  STAGE_RING_RISE,
  STAGE_SPARKLE,
  STAGE_FINAL
};

Stage stage;
uint32_t stageStart;

float angle0[NUM_PARTICLES];
float radius0[NUM_PARTICLES];
float targetX[NUM_PARTICLES];
float targetY[NUM_PARTICLES];

int16_t starX[NUM_STARS];
int16_t starY[NUM_STARS];

// ================= Easing helpers =================
float easeOutCubic(float x) {
  float f = 1.0f - x;
  return 1.0f - f * f * f;
}

float easeInOutCubic(float x) {
  if (x < 0.5f) return 4.0f * x * x * x;
  float f = -2.0f * x + 2.0f;
  return 1.0f - (f * f * f) / 2.0f;
}

float easeOutBack(float x) {
  const float c1 = 1.70158f;
  const float c3 = c1 + 1.0f;
  float f = x - 1.0f;
  return 1.0f + c3 * f * f * f + c1 * f * f;
}

float lerpF(float a, float b, float t) {
  return a + (b - a) * t;
}

// ================= Generic drawing helpers =================
void drawEllipse(int16_t cx, int16_t cy, int16_t rx, int16_t ry) {
  const int SEGMENTS = 28;
  int16_t px = cx + rx;
  int16_t py = cy;
  for (int i = 1; i <= SEGMENTS; i++) {
    float t = (TWO_PI * i) / SEGMENTS;
    int16_t x = cx + (int16_t)(rx * cos(t));
    int16_t y = cy + (int16_t)(ry * sin(t));
    display.drawLine(px, py, x, y, SH110X_WHITE);
    px = x;
    py = y;
  }
}

void drawFilledHeart(int16_t cx, int16_t cy, int16_t size) {
  if (size < 2) return;
  int16_t r = size / 2;
  display.fillCircle(cx - r, cy, r, SH110X_WHITE);
  display.fillCircle(cx + r, cy, r, SH110X_WHITE);
  display.fillTriangle(cx - size, cy, cx + size, cy, cx, cy + size, SH110X_WHITE);
}

void drawSparkle(int16_t x, int16_t y, int16_t len) {
  if (len < 1) return;
  display.drawFastVLine(x, y - len, 2 * len + 1, SH110X_WHITE);
  display.drawFastHLine(x - len, y, 2 * len + 1, SH110X_WHITE);
  int16_t d = len / 2 + 1;
  display.drawLine(x - d, y - d, x + d, y + d, SH110X_WHITE);
  display.drawLine(x - d, y + d, x + d, y - d, SH110X_WHITE);
}

void drawStarfield(uint32_t nowMs) {
  for (int i = 0; i < NUM_STARS; i++) {
    int phase = (int)((nowMs / 150 + i * 13) % 20);
    if (phase < 15) {
      display.drawPixel(starX[i], starY[i], SH110X_WHITE);
    }
  }
}

// ================= Ring box drawing =================
void drawBoxBody(int16_t topY, int16_t h) {
  if (h < 1) return;
  int16_t r = (h < 10) ? 2 : 4;
  display.fillRoundRect(BOX_LEFT, topY, BOX_W, h, r, SH110X_WHITE);
  if (h > 10) {
    int16_t seamY = topY + (int16_t)(h * 0.32f);
    display.drawFastHLine(BOX_LEFT + 3, seamY, BOX_W - 6, SH110X_BLACK);
    display.fillCircle(BOX_CX, seamY, 1, SH110X_BLACK);
  }
}

void drawLidAt(float liftH) {
  int16_t lidBottom = HINGE_Y - (int16_t)liftH;
  int16_t lidTop = lidBottom - LID_THICK;
  if (liftH > 1) {
    display.drawLine(BOX_LEFT + 4, HINGE_Y, BOX_LEFT + 4, lidBottom, SH110X_WHITE);
    display.drawLine(BOX_RIGHT - 4, HINGE_Y, BOX_RIGHT - 4, lidBottom, SH110X_WHITE);
  }
  display.fillRoundRect(BOX_LEFT, lidTop, BOX_W, LID_THICK, 2, SH110X_WHITE);
}

void drawRing(int16_t y) {
  drawEllipse(BOX_CX, y, RING_RX, RING_RY);
  drawEllipse(BOX_CX, y, RING_RX - 1, RING_RY);

int16_t gemY = y - RING_RY - 3;
  display.fillTriangle(BOX_CX - 3, gemY, BOX_CX + 3, gemY, BOX_CX, gemY - 4, SH110X_WHITE);
  display.fillTriangle(BOX_CX - 3, gemY, BOX_CX + 3, gemY, BOX_CX, gemY + 3, SH110X_WHITE);

if ((millis() / 180) % 5 == 0) {
    display.drawPixel(BOX_CX + 5, gemY - 3, SH110X_WHITE);
    display.drawPixel(BOX_CX - 5, gemY + 2, SH110X_WHITE);
  }
}

void drawGroundGlow() {
  drawEllipse(BOX_CX, BOX_BOTTOM + 3, BOX_W / 2 + 5, 3);
}

// ================= Stage updates =================
void updateFlash(uint32_t elapsed) {
  float p = constrain(elapsed / (float)FLASH_DURATION, 0.0f, 1.0f);
  for (int k = 0; k < 3; k++) {
    float kp = constrain(p - k * 0.12f, 0.0f, 1.0f);
    if (kp <= 0.0f) continue;
    int16_t rad = (int16_t)(kp * 46.0f);
    if (rad > 0) display.drawCircle(HEART_CX, HEART_CY, rad, SH110X_WHITE);
  }
}

void updateForm(uint32_t elapsed) {
  float p = constrain(elapsed / (float)FORM_DURATION, 0.0f, 1.0f);
  float w = easeInOutCubic(p);
  for (int i = 0; i < NUM_PARTICLES; i++) {
    float orbitR = radius0[i] * (1.0f - p);
    float orbitA = angle0[i] + p * 9.0f;
    float sx = HEART_CX + orbitR * cos(orbitA);
    float sy = HEART_CY + orbitR * sin(orbitA) * 0.7f;
    float x = sx * (1.0f - w) + targetX[i] * w;
    float y = sy * (1.0f - w) + targetY[i] * w;
    int16_t ix = (int16_t)round(x);
    int16_t iy = (int16_t)round(y);
    display.drawPixel(ix, iy, SH110X_WHITE);
    if (i % 6 == 0) {
      display.drawPixel(ix + 1, iy, SH110X_WHITE);
      display.drawPixel(ix, iy + 1, SH110X_WHITE);
    }
  }
}

void updateHold(uint32_t elapsed) {
  float pulse = 1.0f + 0.06f * sin(elapsed / 220.0f);
  for (int i = 0; i < NUM_PARTICLES; i++) {
    float x = HEART_CX + (targetX[i] - HEART_CX) * pulse;
    float y = HEART_CY + (targetY[i] - HEART_CY) * pulse;
    int16_t ix = (int16_t)round(x);
    int16_t iy = (int16_t)round(y);
    display.drawPixel(ix, iy, SH110X_WHITE);
    if (i % 6 == 0) display.drawPixel(ix + 1, iy, SH110X_WHITE);
  }
}

void updateBurst(uint32_t elapsed) {
  float p = constrain(elapsed / (float)BURST_DURATION, 0.0f, 1.0f);
  float explode = 1.0f + p * 4.0f;
  for (int i = 0; i < NUM_PARTICLES; i++) {
    float dx = targetX[i] - HEART_CX;
    float dy = targetY[i] - HEART_CY;
    float x = HEART_CX + dx * explode;
    float y = HEART_CY + dy * explode;
    if ((float)random(0, 100) > p * 100.0f) {
      display.drawPixel((int16_t)round(x), (int16_t)round(y), SH110X_WHITE);
    }
  }
  int16_t rad = (int16_t)(p * 60.0f);
  if (rad > 0 && rad < 64) display.drawCircle(HEART_CX, HEART_CY, rad, SH110X_WHITE);
}

void updateBoxAppear(uint32_t elapsed) {
  float p = easeOutCubic(constrain(elapsed / (float)BOX_APPEAR_DURATION, 0.0f, 1.0f));
  int16_t h = (int16_t)(BOX_H * p);
  int16_t topY = BOX_BOTTOM - h;
  drawBoxBody(topY, h);
  if (p > 0.5f) drawGroundGlow();
}

void updateLidOpen(uint32_t elapsed) {
  drawBoxBody(HINGE_Y, BOX_H);
  drawGroundGlow();
  float p = easeOutCubic(constrain(elapsed / (float)LID_OPEN_DURATION, 0.0f, 1.0f));
  float theta = p * LID_MAX_ANGLE;
  float liftH = LID_ARM * sin(theta);
  drawLidAt(liftH);
}

void updateRingRise(uint32_t elapsed) {
  drawBoxBody(HINGE_Y, BOX_H);
  drawGroundGlow();
  float liftFinal = LID_ARM * sin(LID_MAX_ANGLE);
  drawLidAt(liftFinal);

float p = constrain(elapsed / (float)RING_RISE_DURATION, 0.0f, 1.0f);
  float pe = easeOutBack(p);
  float ringY = lerpF(HINGE_Y, HINGE_Y - RING_REST_OFFSET, pe);
  drawRing((int16_t)round(ringY));
}

void sparkleWindow(uint32_t elapsed, uint32_t start, uint32_t end, int16_t baseY, int16_t offX) {
  if (elapsed < start || elapsed > end) return;
  float wp = (elapsed - start) / (float)(end - start);
  float amp = sin(wp * PI);
  int16_t len = (int16_t)(2 + amp * 4);
  drawSparkle(BOX_CX + offX, baseY - RING_RY - 6, len);
}

void updateSparkleHold(uint32_t elapsed) {
  drawBoxBody(HINGE_Y, BOX_H);
  drawGroundGlow();
  float liftFinal = LID_ARM * sin(LID_MAX_ANGLE);
  drawLidAt(liftFinal);

int16_t ringY = HINGE_Y - RING_REST_OFFSET;
  drawRing(ringY);

sparkleWindow(elapsed, 300, 550, ringY, 0);
  sparkleWindow(elapsed, 1000, 1250, ringY, -6);
  sparkleWindow(elapsed, 1650, 1900, ringY, 6);
}

void updateFinal(uint32_t elapsed) {
  const char* msg = "Will you marry me?";
  int16_t len = (int16_t)strlen(msg);
  const uint32_t typeMs = 45;

uint32_t shownU = elapsed / typeMs;
  if (shownU > (uint32_t)len) shownU = (uint32_t)len;
  int16_t shown = (int16_t)shownU;

char buf[24];
  strncpy(buf, msg, shown);
  buf[shown] = '\0';

display.setTextSize(1);
  display.setTextColor(SH110X_WHITE);

int16_t x1, y1;
  uint16_t tw, th;
  display.getTextBounds(buf, 0, 0, &x1, &y1, &tw, &th);
  int16_t cx = (SCREEN_WIDTH - tw) / 2 - x1;
  display.setCursor(cx, 26);
  display.print(buf);

if (shown >= len) {
    uint32_t doneFor = elapsed - (uint32_t)len * typeMs;
    float pulse = 1.0f + 0.15f * sin(doneFor / 500.0f);
    int16_t hs = (int16_t)(6.0f * pulse);
    drawFilledHeart(SCREEN_WIDTH / 2, 44, hs);
  }
}

// ================= Setup / Loop =================
void setup() {
  Serial.begin(115200);

// Give OLED time to power up
  delay(1000);

Wire.begin(OLED_SDA, OLED_SCL);
  Wire.setClock(100000);   // 100kHz is more reliable than 400kHz

delay(200);

if (!display.begin(OLED_ADDR, true)) {
    Serial.println("OLED Init Failed!");
    while (1) {
      delay(100);
    }
  }

display.clearDisplay();
  display.display();

randomSeed(esp_random());

for (int i = 0; i < NUM_PARTICLES; i++) {
    angle0[i] = random(0, 6283) / 1000.0f;
    radius0[i] = 26.0f + random(0, 22);

float t = (TWO_PI * i) / NUM_PARTICLES;
    float st = sin(t);
    float hx = 16.0f * st * st * st;
    float hy = 13.0f * cos(t) - 5.0f * cos(2 * t) - 2.0f * cos(3 * t) - cos(4 * t);

targetX[i] = HEART_CX + hx * HEART_SCALE;
    targetY[i] = HEART_CY - hy * HEART_SCALE;
  }

for (int i = 0; i < NUM_STARS; i++) {
    starX[i] = random(0, SCREEN_WIDTH);
    starY[i] = random(0, SCREEN_HEIGHT);
  }

stage = STAGE_FLASH;
  stageStart = millis();

Serial.println("Boot OK");
}

void loop() {
  uint32_t now = millis();
  uint32_t elapsed = now - stageStart;

display.clearDisplay();

switch (stage) {
    case STAGE_FLASH:
      drawStarfield(now);
      updateFlash(elapsed);
      if (elapsed > FLASH_DURATION) { stage = STAGE_FORM; stageStart = now; }
      break;

case STAGE_FORM:
      drawStarfield(now);
      updateForm(elapsed);
      if (elapsed > FORM_DURATION) { stage = STAGE_HOLD; stageStart = now; }
      break;

case STAGE_HOLD:
      drawStarfield(now);
      updateHold(elapsed);
      if (elapsed > HOLD_DURATION) { stage = STAGE_BURST; stageStart = now; }
      break;

case STAGE_BURST:
      drawStarfield(now);
      updateBurst(elapsed);
      if (elapsed > BURST_DURATION) { stage = STAGE_BOX_APPEAR; stageStart = now; }
      break;

case STAGE_BOX_APPEAR:
      updateBoxAppear(elapsed);
      if (elapsed > BOX_APPEAR_DURATION) { stage = STAGE_LID_OPEN; stageStart = now; }
      break;

case STAGE_LID_OPEN:
      updateLidOpen(elapsed);
      if (elapsed > LID_OPEN_DURATION) { stage = STAGE_RING_RISE; stageStart = now; }
      break;

case STAGE_RING_RISE:
      updateRingRise(elapsed);
      if (elapsed > RING_RISE_DURATION) { stage = STAGE_SPARKLE; stageStart = now; }
      break;

case STAGE_SPARKLE:
      updateSparkleHold(elapsed);
      if (elapsed > SPARKLE_DURATION) { stage = STAGE_FINAL; stageStart = now; }
      break;

case STAGE_FINAL:
      updateFinal(elapsed);
      // Sequence holds here permanently once reached.
      // To loop the whole animation again instead, uncomment:
      // if (elapsed > 6000) { stage = STAGE_FLASH; stageStart = now; }
      break;
  }

display.display();
  delay(FRAME_DELAY);
}

ESP32 OLED Proposal Animation

Project Overview

The ESP32 OLED Proposal Animation teaches advanced techniques for creating cinematic multi-stage animations on small display screens using procedural drawing and I2C communication protocols.

This project displays a complete marriage proposal animation sequence on a 128×64 SSD1306 OLED display featuring galaxy particles, heart formation, ring box reveal, and text reveal effects with professional visual quality.

When you run the project, a cinematic animation unfolds across multiple stages beginning with a starburst galaxy effect that transforms into a pulsing heart shape. The heart bursts apart revealing a decorative ring box with opening lid, rising ring, sparkle effects, and finally typewriter text displaying a proposal message.

Key Features: I2C communication between ESP32 and OLED displays, multi-stage cinematic animation sequence, procedurally drawn graphics without bitmaps, particle system animations with convergence effects, decorative ring box graphics with mechanical animation, typewriter text reveal effect, smooth transitions between animation stages, lightweight code optimized for microcontroller platforms.

Components Required

To build this project, collect these specific items from your kit and ensure each component is in good working condition.

ESP32 Development Board x 1, SSD1306 OLED Display (128×64) x 1, Breadboard x 1, Jumper Wires x 4, USB Cable x 1.

Circuit Connections

Step 1: Connect Ground Rail for Shared Reference

Connect the ESP32 GND ground pin directly to the negative rail of your breadboard to establish a shared ground connection for your entire circuit and all connected electronic components throughout the system.

Step 2: Place and Position OLED Display Module

Position the SSD1306 OLED display module carefully near the top edge of your breadboard for convenient access and proper alignment with all jumper wire connections during the assembly process to ensure success.

Step 3: Connect VCC Power Pin to Supply

Connect the OLED VCC power pin directly to the ESP32 3.3V output pin to provide the correct voltage level and adequate power supply for the small OLED display module operation and functionality.

Step 4: Connect Ground Pin for Return Path

Connect the OLED GND ground pin to the breadboard negative rail to complete the power circuit and establish the electrical return path for all current flowing through connected components on the breadboard.

Step 5: Connect SDA Data Pin for I2C

Connect the OLED SDA serial data pin to ESP32 GPIO pin 21 to enable I2C protocol serial data transmission between the ESP32 microcontroller and the OLED display device communication successfully.

Step 6: Connect SCL Clock Pin for Timing

Connect the OLED SCL serial clock pin to ESP32 GPIO pin 22 to provide I2C timing synchronization that coordinates precise data transmission between all connected I2C devices on the bus system.

Step 7: Verify All Connections Before Upload

Double-check all four display pins for correct connections and secure jumper wire placement before uploading any code to your ESP32 microcontroller board to prevent connectivity problems during operation and testing.

Important: The SSD1306 OLED display uses the I2C protocol, a two-wire communication standard where the SDA pin transmits data and the SCL pin provides essential timing synchronization for reliable data transfer.

Software Requirements

Before uploading code to your ESP32, install the following software components, libraries, and drivers on your development system.

Arduino IDE : Download and install the latest version from the official Arduino website for code development, editing, and uploading to your microcontroller board.

ESP32 Board Package : Add the ESP32 board package to Arduino IDE by accessing Boards Manager and searching for ESP32 with proper version selection.

Adafruit GFX Library : Install this library using Arduino IDE Library Manager to access graphics drawing functions and text rendering capabilities for display output.

Adafruit SSD1306 Library : Install this library for complete SSD1306 OLED display control, initialization, and I2C communication protocol implementation.

CH340 USB Driver : Download and install the CH340 USB driver for your specific operating system to enable ESP32 board serial communication with your computer.

Verify Installation : Open Arduino IDE, select your ESP32 board from Tools menu, and confirm the COM port shows your connected microcontroller device.

How the Project Code Works

Initialize Animation State Machine and Particle Systems

The setup function configures I2C pins and initializes the SSD1306 OLED display with reliable communication settings for data transmission. The particle arrays are populated with random initial positions and angles that create the galaxy effect starting configuration for animation sequence.

Create Starburst Flash and Galaxy Particle Effects

The updateFlash function draws concentric circles expanding outward to create a starburst effect at the animation beginning. The updateForm function animates particles orbiting around a center point while gradually converging into a heart shape using mathematical easing functions.

Render Heart Shape and Burst Transitions

The updateHold function maintains a pulsing heart shape by applying sinusoidal scaling to particle positions to create breathing motion effects. The updateBurst function explodes particles outward from the heart center with randomized fade effects creating a visual transition to the ring box stage.

Draw Ring Box with Mechanical Animation

The updateBoxAppear function gradually grows the ring box on screen using easing functions for smooth expansion animation. The updateLidOpen function rotates the box lid upward using trigonometric calculations to create realistic mechanical opening motion and reveal the interior.

Render Ring and Final Proposal Text

The updateRingRise function animates the diamond ring rising from the box bottom using easing functions for natural motion. The updateFinal function displays the proposal message using typewriter effects where characters appear one by one with a pulsing heart drawn below.

Expected Output

After uploading your code to the ESP32, connect the USB cable and observe the display initialization process beginning.

The OLED display shows a starburst galaxy effect with swirling particles that gradually converge into a beautiful pulsing heart shape. Watch as the heart bursts apart revealing an ornate ring box that grows, opens its lid, and displays a sparkling diamond ring rising from inside.

The complete proposal animation concludes with a typewriter effect revealing the message accompanied by a pulsing heart symbol. The animation cycles through all stages and automatically holds at the final screen for continuous display.

Operational Troubleshooting

OLED Display Remains Blank or Unresponsive to Code :- Verify all four display pins connect to correct ESP32 GPIO pins as specified in the circuit diagram. Check VCC and GND connections for proper power supply with adequate current. Confirm the USB cable provides sufficient power and verify the I2C address matches your OLED model..

Animation Displays But Graphics Appear Corrupted or Distorted :- Confirm both Adafruit GFX and SSD1306 libraries are correctly installed in your Arduino IDE folder. Check the I2C clock speed is set appropriately for stable communication. Verify no other code is interfering with GPIO pins 21 and 22 during execution.

Animation Timing Appears Incorrect or Stages Transition Too Fast :- Verify the stage duration constants define correct timing values in milliseconds for each animation sequence. Check that easing function calculations are working properly without errors or interruptions. Adjust timing constants to control animation pacing and create desired visual effects.

Text Reveal Appears Garbled or Display Shows Rendering Issues :- Ensure all jumper wire connections are secure with no loose contacts interrupting data transmission between devices. Verify the text size and coordinate calculations position text within the 128×64 pixel display bounds properly. Check that the typewriter effect delay value allows characters to render correctly on display.

What You Learned

By finishing this project, you understand how to create complex multi-stage cinematic animations on OLED displays using state machines and easing functions. You have learned techniques for managing particle systems, implementing mechanical animations, and synchronizing multiple visual effects with precise timing on microcontroller systems.

You can apply animation state machines to create sophisticated user experiences on embedded platforms with limited resources. You have experienced how easing functions, particle systems, and procedural drawing create professional cinematic effects on constrained microcontroller devices with impressive visual results.

WHAT'S NEXT?

Ready to Build More?

Explore more Lifetronix projects, improve your skills, and turn your ideas into real working prototypes.

Project

ESP32

ESP32 OLED Proposal Animation

Instagram

Youtube

Wiring Schematic

ESP32 OLED Proposal Animation

Project Overview

Components Required

Circuit Connections

Step 1: Connect Ground Rail for Shared Reference

Step 2: Place and Position OLED Display Module

Step 3: Connect VCC Power Pin to Supply

Step 4: Connect Ground Pin for Return Path

Step 5: Connect SDA Data Pin for I2C

Step 6: Connect SCL Clock Pin for Timing

Step 7: Verify All Connections Before Upload

Software Requirements

How the Project Code Works

Initialize Animation State Machine and Particle Systems

Create Starburst Flash and Galaxy Particle Effects

Render Heart Shape and Burst Transitions

Draw Ring Box with Mechanical Animation

Render Ring and Final Proposal Text

Expected Output

Operational Troubleshooting

What You Learned

WHAT'S NEXT?

Ready to Build More?