ESPHome Designer

A visual drag-and-drop editor for smart displays, supporting ESPHome, OpenEpaperLink (OEPL), and OpenDisplay - running as a Home Assistant integration or a standalone web app.

<div align="center"> <a href="https://github.com/sponsors/koosoli"> <img src="https://img.shields.io/badge/Sponsor-❤️-ff69b4?style=for-the-badge&logo=github-sponsors" alt="Sponsor Project"> </a> <a href="https://buymeacoffee.com/koosoli"> <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee"> </a> <br> <strong>If you find this project useful, consider <a href="https://github.com/sponsors/koosoli">supporting its development!</a></strong> </div> <div align="center"> <a href="https://youtu.be/BLkzDYYQJcQ"> <img src="https://img.youtube.com/vi/BLkzDYYQJcQ/maxresdefault.jpg" alt="Watch the v0.8.6 Feature Walkthrough" width="600"> </a> <br> <a href="https://youtu.be/BLkzDYYQJcQ"> <img src="https://img.shields.io/badge/YouTube-Watch%20v0.8.6%20Overview-red?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch Video"> </a> <a href="https://koosoli.github.io/ESPHomeDesigner/"> <img src="https://img.shields.io/badge/Live%20Demo-Try%20it%20now-blue?style=for-the-badge&logo=google-chrome&logoColor=white" alt="Live Demo"> </a> <br> <strong>▶️ Click to watch the latest feature walkthrough or try the demo!</strong> </div> <div align="center">

🖥️ Supported Platforms

| Platform | Output Format | Use Case | |----------|---------------|----------| | ESPHome | C++ Lambda / LVGL YAML | ESP32 devices with direct display control | | OpenEpaperLink | Home Assistant Service Call (JSON) | Wireless e-paper price tags (AP-based) | | OpenDisplay | JSON Actions | HTTP-driven e-paper displays |

</div>

No more hand-coding ESPHome display lambdas! 🎉

Build premium, touch-interactive dashboards for ESP32-based devices, wireless e-paper price tags, and HTTP-driven displays - all without writing a single line of display code.

📋 What Does It Do?

Visual drag-and-drop editor - Design layouts in your browser, see your actual HA entities update live on the canvas
Multi-Platform Export - One design, multiple outputs:
- ESPHome: Native C++ lambda code or LVGL YAML for ESP32 devices with direct display control
- OpenEpaperLink (OEPL): JSON service calls for wireless e-paper tags via the OEPL Access Point
- OpenDisplay (ODP): JSON action payloads for HTTP-driven displays
Flexible Data Sources - Connect widgets to Home Assistant entities or MQTT topics directly — no extra configuration needed.
Multi-Page "World View" - Manage all your project pages on a single unified stage with artboard-style rendering.
Plugin-Based Architecture - 55+ independent widget modules for everything from sensors and graphs to polygons and complex patterns.
Round-trip editing - Import existing ESPHome configs, OEPL YAML arrays, or ODP JSON payloads back into the editor.
AI-Powered Dashboard Assistant - Generate entire layouts or individual widgets from simple text prompts.
Conditional Visibility - Show or hide any widget based on Home Assistant entity state (binary, numeric, text, and range conditions).
Time-Based Page Scheduling - Assign visibility windows to pages so your device automatically shows the right content at the right time.
Full device integration - Exposes buttons, buzzer, temperature, and humidity sensors back to HA for automations.
Smart power management - Battery monitoring, configurable refresh intervals, and hardware-aware energy saving strategies.

Use case: Display a weather page when you wake up, switch to a sensor dashboard during the day, show a specific alert page when the doorbell rings - all automated through Home Assistant.

🚀 Quick Start

Installation (pick one)

1. Live Web Version (Easiest)

You can use the designer without installing anything!

Go to koosoli.github.io/ESPHomeDesigner/
Open Editor Settings (gear icon)
Enter your Home Assistant URL and a Long-Lived Access Token (created in your HA profile)
Add the designer URL to your HA cors_allowed_origins (see below)

2. Install via HACS (Recommended)

Add https://github.com/koosoli/ESPHomeDesigner to HACS as a custom repository
Search for "ESPHome Designer" and install
Restart Home Assistant
Go to Settings → Devices & Services → Add Integration → Search for "ESPHome Designer"

3. Manual Installation

Download the custom_components/esphome_designer folder from this repo
Copy it to your Home Assistant config/custom_components/ directory
Restart Home Assistant
Add the integration via Settings → Devices & Services

Where Home Assistant Stores Your Data

When you run ESPHome Designer inside Home Assistant, your saved layouts are stored in Home Assistant's storage folder:

Layouts and editor state: /config/.storage/esphome_designer
Custom layouts you create in the editor: saved inside that same /config/.storage/esphome_designer file as separate layout entries
Legacy installs (0.8.6.2 and older): may still have old data in /config/.storage/reterminal_dashboard; the integration can read that and migrate it on a later save
Uploaded custom hardware profiles: /config/esphomedesigner_custom_profiles/*.yaml

If you are browsing the Home Assistant filesystem from the host OS, replace /config with your actual Home Assistant configuration directory.

4. Local Development Server

Run the editor locally without Home Assistant:

Option A: Full Repository Clone (with npm/bun)

If you cloned the full repository, run from the project root:

npm install
npm run dev

Open http://localhost:5174 in your browser.

Option B: Frontend-Only (Python HTTP Server)

If you only have the custom_components folder (e.g., HACS install), serve the frontend directly:

cd custom_components/esphome_designer/frontend
python3 -m http.server 8000

Open http://localhost:8000 in your browser.

Connect to Home Assistant by entering your HA URL and a Long-Lived Access Token in Editor Settings.

Setup (ESPHome devices)

5. Prepare Your Device

Important: Copy the Material Design Icons font file first!

From this repo: font_ttf/font_ttf/materialdesignicons-webfont.ttf
To your ESPHome: /config/esphome/fonts/materialdesignicons-webfont.ttf

(Create the fonts folder if it doesn't exist)

Then create a new ESPHome device:

Create a new device in ESPHome Dashboard
Let ESPHome generate the base config (WiFi, API, OTA, etc.)
Configure the correct ESP platform for your device (instructions included in the generated YAML comments)

6. Design Your Dashboard

Open the integration at /esphome-designer in Home Assistant
Select your device type (E1001, E1002, TRMNL,...)
Drag widgets onto the canvas
Add your sensors, weather entities, icons, shapes
Create multiple pages with different refresh rates
Live Preview: Your YAML is generated on the fly as you design! Just look at the YAML snippet box. <p align="center"><img src="screenshots/canvas.gif" width="800" alt="Modern Canvas Interaction"></p>

7. Flash It

Copy the generated YAML snippet
Paste it below ESPHome's auto-generated sections in your device config
Compile and flash via ESPHome

Done! Your custom dashboard is now running on your device.

8. Connect & Automate

Once flashed, your device will come online.

Go to Settings → Devices & Services in Home Assistant.
Your device should be discovered (or you can add it via the ESPHome integration).
Configure it to ensure Home Assistant connects to its API.

🎨 Widget Types

Text & Sensor Text - Static labels or live HA entity values with smart type detection and multiple formatting options <p align="center"><img src="screenshots/text_formatting.gif" width="700" alt="Rich Text Formatting"></p>
Icon & Weather Icon - 360+ Material Design Icons or dynamic weather-state icons with full size/color control <p align="center"><img src="screenshots/icon_picker2.gif" width="700" alt="Icon Picker System"></p>
Date, Time & Calendar - Customizable clock, date, and full monthly calendar views
Progress Bar & Battery - Visual indicators for percentages and dynamic battery level tracking
Shapes & Rounded Rects - Rectangles, circles, lines, and rounded rects with gray/dither support
Graph - Advanced sensor history plotting with auto-scaling, grid lines, and X/Y axis labeling
Image & Online Image - Static photos or dynamic URLs (weather maps, cameras) with auto-dithering
Quote / RSS Feed - Inspirational quotes or external RSS feeds with auto-scaling, refresh logic, and multi-item display (up to 10 items per feed)
QR Code - Dynamic QR generation for URLs, text, or WiFi credentials (auto-formats SSID/password for instant phone scanning)
Touch Area - Invisible or icon-labeled interactive zones to trigger HA actions (supports dual-state feedback) <p align="center"><img src="screenshots/touch_icons.gif" width="700" alt="Touch Interactive Icons"></p>
Weather Forecast - Multi-day or hourly forecast display integrated with HA weather entities, with configurable hour slots and start offsets

⚡ LVGL Support (Experimental)

⚠️ Highly Experimental - Expect Bugs!

This tool includes experimental support for LVGL (Light and Versatile Graphics Library) widgets on LCD+Touch devices. LVGL enables interactive widgets like buttons, switches, sliders, and checkboxes that can control Home Assistant entities directly from the touchscreen.

Important Notes

LCD+Touch devices only - LV

ESPHomeDesigner

Install / Use

README