Skip to content

README.md

Latest commit

 

History

History
209 lines (161 loc) · 7.14 KB

README.md

File metadata and controls

209 lines (161 loc) · 7.14 KB

ESP32 Box3 - Smart Display with WiFi Status

A professional ESP32-S3-BOX-3 project featuring Material Design WiFi status indicators, intelligent reconnection logic, and animated robot eyes display.

ESP32 Box3 Display ESP32 Box3 showing the animated robot eyes with time, date, and WiFi status

🙏 Acknowledgments

RoboEyes Library

This project uses the excellent RoboEyes library by FluxGarage for the animated robot eyes display.

Special thanks to FluxGarage for creating this delightful library that brings personality and charm to embedded displays! 🤖👁️

🌟 Features

📡 Intelligent WiFi Management

  • Smart Reconnection: 10 attempts every second, then once per minute
  • Visual Status: Material Design icons (green=connected, red=disconnected)
  • Real-time Logging: Comprehensive serial console output
  • Automatic Recovery: Seamless reconnection with NTP time sync

🎨 Professional Display

  • Time & Date: 12-hour format with custom orange color (#f6b26b)
  • Anti-flicker: Selective rendering for smooth updates
  • Robot Eyes: Animated eyes with idle movement and auto-blinking
  • High-Quality Icons: 16x16 anti-aliased Material Design bitmaps

🔧 Development Pipeline

  • SVG to Bitmap: Automated conversion from Material Design SVGs
  • Python Environment: Virtual environment with all dependencies
  • Cross-platform: macOS support with Homebrew integration

🚀 Quick Start

Prerequisites

# Install PlatformIO
pip install platformio

# For icon generation (optional)
brew install cairo pango gdk-pixbuf

Build & Upload

# Clone and navigate to project
cd ESP32-Box3

# Build and upload firmware
pio run --target upload

# Monitor serial output
pio device monitor --baud 115200

WiFi Configuration

  1. Copy the WiFi configuration template:
cp include/wifi_config.h.template include/wifi_config.h
  1. Edit include/wifi_config.h with your actual WiFi credentials:
const char* ssid = "YourWiFiNetwork";
const char* password = "YourPassword";

Note: The wifi_config.h file is excluded from Git to keep your credentials private.

📁 Project Structure

ESP32-Box3/
├── README.md                    # This file
├── platformio.ini              # PlatformIO configuration
├── src/main.cpp                # Main ESP32 firmware
├── include/MaterialDesignIcons.h # Generated WiFi icon bitmaps
├── lib/                        # Arduino libraries
├── test/                       # Test files
└── assets/                     # Development assets
    ├── docs/                   # 📄 Documentation
    │   ├── SIMPLIFIED_CHANGES_SUMMARY.md
    │   ├── DISPLAY_MOCKUP.md
    │   ├── WIFI_ICON_MOCKUP.md
    │   └── VERSION_ROLLBACK_GUIDE.md
    ├── scripts/                # 🐍 Development scripts
    │   ├── svg_to_bitmap.py    # SVG to C bitmap converter
    │   └── requirements.txt    # Python dependencies
    ├── icons/                  # 🎨 Source SVG files
    │   ├── wifi.svg           # Material Design WiFi icon
    │   └── wifi-off.svg       # Material Design WiFi-off icon
    └── backups/               # 🗂️ Project backups

🔄 WiFi Reconnection Logic

Connection States

  • Connected: Green WiFi icon, real-time NTP sync
  • Disconnected: Red WiFi icon, automatic reconnection attempts

Reconnection Strategy

  1. Quick Mode: 10 attempts, 1 second intervals
  2. Slow Mode: Continuous attempts, 1 minute intervals
  3. Auto-Recovery: Returns to quick mode when connection restored

Serial Console Output

📡 WiFi CONNECTION LOST!
   Starting reconnection attempts (quick mode - 10 attempts every 1 seconds)

🔄 WiFi RECONNECTION attempt 1/10 (quick mode - 1 second interval)
   Connecting to SSID: YourNetwork
   Attempting connection..........
❌ WiFi reconnection FAILED
   Next attempt in 1 seconds

✅ WiFi CONNECTED successfully!
   IP Address: 192.168.1.100
   Signal Strength: -45 dBm
   Re-syncing NTP time...

🎨 Icon Generation

Regenerate WiFi Icons

# Activate Python environment
source .venv/bin/activate

# Set library paths (macOS)
export DYLD_LIBRARY_PATH="/opt/homebrew/opt/cairo/lib:$DYLD_LIBRARY_PATH"

# Generate new bitmaps
python assets/scripts/svg_to_bitmap.py

Custom Icons

  1. Replace SVG files in assets/icons/
  2. Run the generation script
  3. New bitmaps will be written to include/MaterialDesignIcons.h

🛠️ Hardware

  • Board: ESP32-S3-BOX-3
  • Display: ILI9341 320x240 TFT
  • Features: WiFi, Bluetooth, Touch screen
  • Power: USB-C

📊 Display Layout

┌─────────────────────────────────────────────────────────────────┐
│             01/26/2025                                    📶    │ ← Date & WiFi Status
│             07:57 PM                                            │ ← Time (12-hour format)
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                        👁️   👁️                                │ ← Animated Robot Eyes
│                          ─                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🔧 Technical Specifications

Performance

  • Memory Usage: 14.2% RAM, 14.3% Flash
  • Update Frequency: 5 seconds (time/date), 20ms (eyes - 50 FPS optimized)
  • WiFi Check: Every loop cycle (~20ms)
  • Eye Clearing: Optimized selective clearing (no more slow sweeping)
  • Anti-flicker: Selective rendering

Colors

  • Background: Black
  • Time/Date: Orange (#f6b26b / RGB565: 0xFD60)
  • WiFi Connected: Green
  • WiFi Disconnected: Red
  • Robot Eyes: Blue

📝 License

This project is open source. Feel free to modify and distribute.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Material Design Icons

WiFi icons are based on Google's Material Design icon set, converted to high-quality bitmaps for embedded use.

� Support

For issues or questions:

  • Check the documentation in assets/docs/
  • Review the serial console output
  • Verify WiFi credentials and network connectivity

Built with ❤️ for the ESP32 community