ESPHome export
The same design as one ESPHome YAML file - no compiler to install, one command to flash, and the widgets you bind can appear in Home Assistant as real entities.
ESPHome builds ESP32 firmware from a configuration file rather than from source you write. It has carried an LVGL component for a while now, which makes it a third way to put an LCD Wizard design on a board: screens, widgets, styles, events, variables, bindings, automations and peripherals all come across, and what you flash is described by a file you can read.
It suits you if you already run Home Assistant, or if the Arduino toolchain is more setup than you want for a panel that shows four numbers and a button. It does not suit you if you need a chart, a calendar or a board outside the ESP32 family - see what it covers.
Choosing it
The toolchain is picked when the project is made, in the setup wizard, and stays with it. That is deliberate: it decides what you can draw. ESPHome has no chart widget at all, so offering one and refusing it at export time would waste your afternoon. Pick ESPHome on the first step and the palette, the board list and the hardware pickers follow - a widget it cannot build stays in its place, greyed, with the reason on it.
It cannot be changed afterwards. A design is built for one toolchain. If you picked the wrong one, start a new project - the wizard takes about twenty seconds.
An ESPHome build is one generation, metered exactly like an Arduino one - see Accounts and limits. A design it refuses costs nothing, and the export dialog tells you what it refused and why before you spend anything finding out.
What it covers
| Supported | Not yet | |
|---|---|---|
| MCU | ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6 | ESP32-P4, STM32, RP2040 |
| Panel | SPI and quad SPI: ILI9341, ILI9342, ILI9481, ILI9486, ILI9488, ST7735, ST7735S, ST7789, ST7796, GC9A01, GC9107, ST77916, CO5300, AXS15231B. 8-bit parallel on an ESP32-S2 or S3, which ESPHome drives as an octal SPI bus | RGB and MIPI-DSI panels; 16-bit parallel; monochrome panels, because ESPHome renders LVGL in 16-bit colour only |
| Touch | XPT2046, GT911, FT6206, FT6236, FT5x06, CST816S, CST820, CST226SE, CST328, TT21100, CHSC6540, AXS15231B | GT9271, FT3267, ADS7846, STMPE610, NS2009, TSC2007; encoder and button inputs |
| Board presets | Nine: ESP32 + ILI9341 2.8" SPI, both Cheap Yellow Displays, WT32-SC01, WT32-SC01 Plus, M5Stack Core2, ESP32-S3 + ILI9341, ESP32-S3 + GC9A01 round, LilyGO T-Display-S3 | The RGB, AMOLED, STM32 and RP2040 presets |
| Widgets | Twenty-three, including every control, the scale (ESPHome calls it a meter), line, tileview, tabview, keyboard and spinner | Chart, Calendar, Colourwheel, List, Image Button and Window, none of which ESPHome has |
| Design | Every style property and state, every trigger, variables, formulas, bindings, automations, analog inputs, digital I/O, backlight, images, library fonts and icons | Play animation and Switch theme actions; styles on a dropdown's open list or a tabview's button row, which ESPHome cannot address separately |
| Peripherals | Sixteen, each becoming its own ESPHome component: BME280, BMP280, SHT31, AHT20, SCD4x, BH1750, MCP9808, ADS1115, INA219, MPU6050, VL53L0X, MAX6675, MAX31855, MCP3008, PCA9685, NeoPixel | MAX17048, ADXL345, DS3231 and the SD card |
| I/O expanders | All seven, natively - a control line behind a PCF8574 or a CH422G is written as a pin belonging to that component | - |
Built against ESPHome 2026.8.2, which bundles LVGL 9.5. A design drawn for LVGL 8 is exported as LVGL 9 all the same. The lists above are not approximate: the export reads ESPHome's own component tables, and anything it has not read is refused rather than guessed at - a wrong driver is a blank panel with nothing to say why.
Every file
| File | What it is |
|---|---|
<name>.yaml | The whole configuration: the board, its buses, the panel, touch, the backlight, every sensor and switch, and the interface under lvgl:. Commented throughout, with the pins gathered into substitutions: at the top. |
fonts/ | Any font that is not one of LVGL's built-in Montserrat cuts. ESPHome converts them itself at build time, so these are the real font files - and their licences travel with them. |
images/ | Your pictures, as you imported them. ESPHome converts and compiles them in. |
images/icons/ | One PNG per icon and size used: white, with the shape in the alpha channel, tinted by image_recolor. |
lw_math.h | Only when a formula uses map, clamp or constrain - the same arithmetic the Arduino export uses, so the two behave alike. |
secrets.yaml.example | Only with Home Assistant turned on. Rename it and put your own values in; nothing in the YAML itself is a credential. |
README.md | The command for this board, what to copy where, and anything about this design worth knowing. |
It is one file on purpose. ESPHome's unit of work is a file - esphome run x.yaml,
or the "+" button in its dashboard - and splitting the config across
packages
would buy a shorter file at the cost of a folder that has to stay together anyway.
Flashing it
Copy the YAML and the folders beside it into your ESPHome configuration directory, then:
esphome run my-panel.yamlThat is the whole of it. The first build takes a few minutes while ESPHome fetches its toolchain; after that, plug the board in over USB and it flashes. If you run the ESPHome dashboard - as an add-on in Home Assistant, or on its own - drop the file in and press Install instead.
There is no lv_conf.h to edit, no library versions to pin and no partition
scheme to choose. ESPHome sizes its own partition table, which is why the layout on the
designer's Hardware tab has no effect here.
Home Assistant
The wizard asks whether the panel should join Home Assistant. Left off - the default - the YAML has no network in it at all: the panel runs on its own, and the Wi-Fi block is written commented out so you can change your mind with one edit.
Turned on, the export adds Wi-Fi, the ESPHome API and updates over the air, and publishes
every widget you have bound as an entity through ESPHome's own LVGL platforms - a slider
becomes a number, a switch a switch, a dropdown a
select, a label a text_sensor. Move the slider on the panel and the
entity moves in Home Assistant; change it in Home Assistant and the panel follows.
No credentials are written. The YAML names them - !secret wifi_ssid and
so on - and reads them from a secrets.yaml you make yourself. The export ships a
secrets.yaml.example to rename rather than a real one, so it cannot overwrite the
one you already have.
Where it differs from the Arduino export
Most of the design comes across unchanged. Four things behave differently enough to be worth knowing before you wonder why:
| In the designer | On an ESPHome device |
|---|---|
| A binding updates every refresh | ESPHome updates when the reading changes, which is what its sensors are built around. In practice you see the same numbers, a little less often. |
| An icon is a font glyph and takes its colour from the text around it | An icon is a tinted image. It looks identical - the same rasteriser draws it - but the colour is written out per state rather than inherited, so restyling one by hand means setting image_recolor. |
| A resistive panel calibrates itself on the first boot | ESPHome takes fixed calibration values. The ones from the designer are written into the touchscreen: block; ESPHome has its own procedure for redoing them. |
A Call function action becomes a stub in ui_events.c | It becomes a script: with an empty lambda at the bottom of the YAML. Fill it in there - and keep a copy, because regenerating writes the empty one again. |
What is not here yet
RGB and MIPI-DSI panels. ESPHome drives an RGB panel from one of its own board
presets - ESP32-8048S070, ESP32-S3-TOUCH-LCD-4.3 and the rest - and
reads the timings from that, rather than from the pins and porches the designer holds.
Mapping the presets onto those models is a board-by-board job that wants checking against
each panel, so it is refused rather than guessed. The Arduino export drives all of them.
The six widgets ESPHome has no equivalent for. A Chart is the one most likely to matter; there is no way to draw one, and no arrangement of other widgets that stands in for it. A design that needs a chart wants the Arduino export.
Encoder and button inputs. ESPHome has both, and they are not wired up here yet.