ESP-DashboardPlus

A real-time, on-device web dashboard library for ESP32 microcontrollers. Create beautiful, responsive dashboards with minimal code using WebSocket-based communication.

✨ Features

• ✏️ Customizabe - Adjust to your brand / product with own themes / custom titles.
• 🔌 Real-time Updates - WebSocket-based communication for instant UI updates
• 📊 14 Card Types - Stats, charts, gauges, toggles, sliders, buttons, and more
• 🎨 Modern Dark & Light Theme - Industrial IoT aesthetic with light/dark mode support
• 📱 Responsive Design - Works on desktop and mobile browsers
• 🗂️ Tabbed Interface - Dashboard, Console, and OTA tabs in a single HTML file
• 🔄 OTA Updates - Dedicated firmware update tab with device info
• 📝 Console Logging - Full-page console tab with filtering, export, and command input
• ⚡ Optimized - Gzip-compressed HTML stored in PROGMEM (~18KB)
• 🛠️ Easy Integration - Simple C++ API with minimal boilerplate

Note: OTA and Console are available as tabs only, not dashboard cards. Configure visibility with enableOTA and enableConsole parameters in begin().

📦 Installation

PlatformIO (Recommended)

Add to your platformio.ini:

lib_deps = 
    aaronbeckmann/ESP-DashboardPlus@^1.0.0

Or install via PlatformIO CLI:

pio lib install "ESP-DashboardPlus"

Manual Installation

1. Download the latest release
2. Extract to your project's lib/ folder
3. Include the library in your code

🚀 Quick Start

#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include "ESPDashboardPlus.h"
"dashboard_html.h"  // Auto-generated

AsyncWebServer server(80);
ESPDashboardPlus dashboard("My Device");

void setup() {
    Serial.begin(115200);
    WiFi.begin("SSID", "PASSWORD");
    while (WiFi.status() != WL_CONNECTED) delay(500);
    
    // Initialize dashboard
    dashboard.begin(&server, DASHBOARD_HTML_DATA, DASHBOARD_HTML_SIZE);
    
    // Add a temperature display
    StatCard* temp = dashboard.addStatCard("temp", "Temperature", "25.0", "°C");
    
    // Add a toggle switch
    ToggleCard* led = dashboard.addToggleCard("led", "LED", "Status", false);
    led->onChange = [](bool state) {
        digitalWrite(LED_BUILTIN, state);
    };
    
    server.begin();
    Serial.printf("Dashboard: http://%s\n", WiFi.localIP().toString().c_str());
}

void loop() {
    dashboard.loop();
    
    // Update values periodically
    static unsigned long lastUpdate = 0;
    if (millis() - lastUpdate > 2000) {
        lastUpdate = millis();
        dashboard.updateStatCard("temp", String(random(20, 30)));
    }
}

📊 Available Card Types

Card	Description	Use Case
StatCard	Display numeric values with units	Temperature, humidity, voltage
GaugeCard	Circular gauge with thresholds	CPU usage, battery level
ChartCard	Line/area/bar/scatter/step charts	Historical data visualization
ToggleCard	On/off switch	LED control, relay control
SliderCard	Range slider	Brightness, volume, PWM
ButtonCard	Simple clickable button	Trigger actions
ActionButton	Button with confirmation popup	Restart, factory reset
LinkCard	URL redirect button	External links, documentation
InputCard	Text/number input field	WiFi SSID, configuration
DropdownCard	Select menu	Mode selection, options
ColorPickerCard	Color picker with presets	RGB LED control
DateCard	Date/time picker	Scheduling, alarms
TimezoneCard	Browser timezone detection	Time synchronization
StatusCard	Icon + status message	Connection status, system health

Tabs (not cards)

Tab	Description
Console	Timestamped logging with filtering, export, and command input
OTA Update	Firmware update via drag-and-drop with progress display

📖 Documentation

Full documentation is available at: https://aaronbeckmann.github.io/ESP-DashboardPlus

• Getting Started
• Card Reference
• API Reference
• Examples

📁 Library Structure

ESP-DashboardPlus/
├── library.json              # PlatformIO manifest
├── README.md                 # This file
├── LICENSE                   # MIT License
├── src/
│   ├── ESPDashboardPlus.h    # Main library header
│   └── dashboard_html.h      # Auto-generated (gzipped HTML)
├── extras/
│   └── dashboard.html        # Source HTML file
├── scripts/
│   ├── html_to_header.py     # Standalone HTML converter
│   └── html_to_header_pio.py # PlatformIO pre-build script
├── examples/
│   └── basic/
│       └── main.cpp          # Complete example
└── docs/                     # GitHub Pages documentation
    ├── index.md
    ├── getting-started.md
    ├── cards.md
    └── ...

🔧 Build Configuration

platformio.ini

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

lib_deps = 
    ESP-DashboardPlus

; HTML auto-conversion is handled by the library

Manual HTML Conversion

If you modify extras/dashboard.html, regenerate the header:

python scripts/html_to_header.py extras/dashboard.html src/dashboard_html.h

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ESPAsyncWebServer
• JSON handling by ArduinoJson

📞 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions