A festive, feature-rich Christmas animation project for ESP32 microcontrollers with SSD1306 OLED displays. This project showcases advanced animation techniques, modular code architecture, and professional embedded systems practices.
- Christmas Tree Scene: Animated twinkling star, decorated tree, moving snowman
- Santa's Sleigh: Flying Santa with reindeer across the screen
- Fireplace Scene: Flickering flames with presents
- Weather Display: Dynamic weather effects with day/night cycle
- Weather System: Snow, rain, and clear sky with particle effects
- Day/Night Cycle: Automatic sun/moon transitions
- Smooth Animations: Professional easing and interpolation
- Particle System: Efficient weather particles and effects
- Modular Architecture: Clean separation of concerns
- Memory Monitoring: Real-time heap usage tracking
- Performance Monitoring: Frame rate and timing analysis
- Error Handling: Comprehensive error reporting and recovery
- Configurable Parameters: Easy customization via config files
For the easiest setup, you can purchase a pre-built ESP32-C3 development board with integrated 0.42" OLED display:
ESP32-C3 OLED Development Board
- Where to buy: AliExpress - ESP32-C3 OLED Board
- Features: ESP32-C3 supermini with built-in 0.42" OLED, ceramic antenna, WiFi & Bluetooth
- Advantages: No wiring required, compact form factor, plug-and-play setup
💡 Note: While we don't currently have an affiliate partnership, this link helps you find the exact board this project was designed for. Most users discover this repository after purchasing the board!
- MCU: ESP32-C3FN4/FH4 with 4MB Flash
- Connectivity: WiFi & Bluetooth with ceramic antenna
- Display: 0.42″ OLED with 72×40 pixel animation area
- Programming: USB download support
- Power: USB-C connection
This project uses a 72×40 pixel animation area centered on the display. All the Christmas scenes, animations, and effects are designed for this area. The display driver handles the technical details automatically.
If you're using a different 0.42″ OLED display and the animations appear off-center, you may need to adjust the SCREEN_WIDTH constant in config.h.
Based on feedback from actual AliExpress buyers, here are important setup notes:
✅ Working U8g2 Constructors:
// Option 1: Direct 72x40 support (recommended)
U8G2_SH1106_72X40_WISE_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE, 6, 5);
// Option 2: Alternative 72x40
U8G2_SSD1306_72X40_ER_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE, 6, 5);
// Option 3: Standard 128x64 with manual offsets
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE, 6, 5);
// Then use offsets: xOffset = 28-30, yOffset = 12- Low brightness: Set
u8g2.setContrast(255);for maximum brightness - Poor WiFi: Antenna is close to display - expected ~20% weaker signal
- Arduino IDE: Select "ESP32C3 Dev Module" as board type
- Misaligned overlay: Cosmetic only, doesn't affect functionality
🔌 Confirmed Pin Layout:
- I2C: SCL=6, SDA=5 (confirmed by multiple users)
- Blue LED: Pin 8
- Boot Button: Pin 9
- Power: ~200mA @ 5V via USB-C
Alternatively, you can build your own setup with individual components:
| Component | Specification | Notes |
|---|---|---|
| MCU | ESP32-C3 (or compatible) | ESP32, ESP32-S2, ESP32-S3 also supported |
| Display | SSD1306 128x64 OLED | I2C interface, 0.42" to 1.3" supported |
| Power | 3.3V/5V | Via USB or external supply |
Note: If using the integrated AliExpress board, no wiring is needed!
ESP32-C3 <-> SSD1306 OLED
-------- --------------
GPIO6 (SDA) <-> SDA
GPIO5 (SCL) <-> SCL
3.3V <-> VCC
GND <-> GND
- PlatformIO installed
- ESP32 board drivers installed
- USB cable for programming
# Clone the repository
git clone https://github.com/MikeDX/ESP32-C3-OLED.git
cd ESP32-C3-OLED
# Open in PlatformIO (VSCode)
code .
# Or build/upload via command line
pio run -t upload
pio device monitor -b 115200Edit src/config.h to customize:
// Animation timing
constexpr unsigned long SCENE_DURATION = 5000; // Scene change interval
constexpr unsigned long ANIMATION_FRAME_DELAY = 50; // Frame rate (20 FPS)
// Feature toggles
constexpr bool ENABLE_STAR_ANIMATION = true;
constexpr bool ENABLE_WEATHER_EFFECTS = true;
constexpr bool ENABLE_DAY_NIGHT_CYCLE = true;
// I2C pins (if different)
constexpr uint8_t I2C_SDA_PIN = 6;
constexpr uint8_t I2C_SCL_PIN = 5;ESP32-C3-OLED/
├── src/
│ ├── main.cpp # Main application with Christmas animations
│ ├── config.h # Configuration constants and parameters
│ ├── animation.h # Animation system declarations
│ ├── AnimationManager.h # Animation classes and utilities
│ └── DebugUtils.h # Debug and monitoring utilities
├── .vscode/ # VSCode configuration
├── .pio/ # PlatformIO build files
├── platformio.ini # PlatformIO configuration
├── .gitignore # Git ignore rules
└── README.md # This file
📝 Note: This project is specifically optimized for the AliExpress ESP32-C3 OLED board and uses the U8G2_SSD1306_128X64_NONAME_F_HW_I2C constructor with calculated offsets. Based on user reviews, you may get better results with the direct U8G2_SH1106_72X40_WISE_F_HW_I2C constructor, but this project's approach works reliably across different board revisions.
Enable debug output to see performance metrics:
// In config.h
constexpr bool ENABLE_SERIAL_DEBUG = true;Monitor output shows:
- Average frame rate (FPS)
- Memory usage and leak detection
- Scene transition timing
- Error reporting
Extend the system by adding new scenes:
// In main.cpp
enum Scene {
SCENE_CHRISTMAS_TREE = 0,
SCENE_SANTA_SLEIGH,
SCENE_FIREPLACE,
SCENE_WEATHER_DISPLAY,
SCENE_YOUR_CUSTOM_SCENE, // Add here
SCENE_COUNT
};
void drawYourCustomScene() {
// Your animation code here
}For constrained environments:
- Reduce
MAX_PARTICLESin config.h - Disable unused features via feature flags
- Use PROGMEM for large string constants
| Problem | Cause | Solution |
|---|---|---|
| Blank display | Wiring/I2C | Check connections, try different U8g2 constructor |
| Display too dark | Low contrast | Add u8g2.setContrast(255); in setup() |
| Animations off-center | Wrong display driver | Try U8G2_SH1106_72X40_WISE_F_HW_I2C constructor |
| Poor WiFi signal | Antenna near display | Expected behavior - signal ~20% weaker |
| Arduino IDE issues | Wrong board selection | Select "ESP32C3 Dev Module" |
| Memory errors | Heap exhaustion | Reduce MAX_PARTICLES, enable monitoring |
| Compilation errors | Missing dependencies | Run pio lib install |
This board works with multiple firmware options:
🔸 Arduino IDE
// Minimal working example from user reviews
#include <U8g2lib.h>
#include <Wire.h>
U8G2_SH1106_72X40_WISE_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE, 6, 5);
void setup() {
u8g2.begin();
u8g2.setContrast(255);
u8g2.setFont(u8g2_font_6x10_tf);
}
void loop() {
u8g2.clearBuffer();
u8g2.drawStr(0, 15, "Hello OLED");
u8g2.sendBuffer();
delay(1000);
}🔸 ESPHome
i2c:
sda: 5
scl: 6
display:
- platform: ssd1306_i2c
model: "SH1106 128x64" # Use with offset compensation
# Actual usable area: 72x40 with offset 28,12🔸 Tasmota Compatible with standard Tasmota firmware (confirmed by users).
🔸 MicroPython
from machine import Pin, I2C
from sh1106 import SH1106_I2C
W,H = 72,40
X0,Y0 = 28,12
i2c = I2C(0, scl=Pin(6), sda=Pin(5), freq=400000)
oled = SH1106_I2C(X0+W, (Y0+H+7) & 0xf8, i2c, rotate=180)Typical performance on ESP32-C3:
- Frame Rate: 20 FPS (50ms per frame)
- Memory Usage: ~45KB heap (32 particles)
- I2C Frequency: 400kHz
- Animation Smoothness: 60+ interpolation steps
We welcome contributions! Areas for improvement:
- Additional animation scenes
- New particle effects
- Performance optimizations
- Hardware support (different displays)
- Sound integration
- Fork the repository
- Create a feature branch
- Test on hardware
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- WiFi connectivity for remote control
- Multiple display support
- Sound/music synchronization
- Mobile app companion
- Real-time weather integration
- Custom animation scripting
MikeDX - GitHub Profile
- U8g2 Library for excellent OLED support
- PlatformIO for the development platform
- ESP32 community for hardware support and documentation
Made with ❤️ for the maker community