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.

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

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

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.yaml

That 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, and Join Home Assistant in File > Project settings changes the answer later. 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. The one exception is a design that reads web data or MQTT: that joins Wi-Fi either way, since it has to.

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.

What Home Assistant is shown

With Join Home Assistant on, the panel is one device there, and these are its entities with nothing more to do. The export’s README lists them by name for your own design.

A widget with no binding is not an entity, and nor is a variable by itself: a battery percentage worked out from a voltage reaches Home Assistant only as the text of a label bound to it, unless the variable is reported.

Setting a slider’s number from Home Assistant moves the slider and writes the variable the slider is bound to, as a finger does - and the same goes for an arc, a spinbox, a switch, a checkbox, a dropdown and a roller whose binding writes a variable. ESPHome tells the widget with an update event of its own, not the one a finger sends, so such a widget has an on_update in the YAML beside its on_change. It writes the variable only when the variable does not already hold the value, so the variable’s script, the widgets bound to it, an automation on it changing and its report to Home Assistant each run once. A value the panel itself puts on the widget - from the variable of a two-way binding, or from a Set Property action - is not written back: the YAML counts those in a global called lw_set_here, and the README names the widgets this applies to. Read in the C++ ESPHome generates, not run against Home Assistant.

Reporting a variable

On the Data tab, open the variable and tick Report to Home Assistant. A number becomes a sensor, an on/off a binary sensor, text a text sensor. Three fields appear:

• Called - its name in Home Assistant. Left empty, the variable’s own name.
• Device class - what kind of reading it is: battery, temperature, humidity, power. It chooses the icon and how Home Assistant shows it. The list is the one the ESPHome release this export is built for accepts, read from that release.
• State class, for a number - whether Home Assistant keeps long-term statistics. Measurement is a reading that goes up and down; Total, only ever rising is a count.

The unit and the decimals are the variable’s own. So a battery gauge is an analog input, a variable that reads it with a formula such as clamp((raw - 3.3) / 0.9 * 100, 0, 100), a unit of %, device class battery - and one tick.

In the YAML it is a platform: template entity with no lambda of its own, and the last step of the variable’s script sends it:

sensor:
  - platform: template
    id: rep_battery_pct
    name: "Battery level"
    unit_of_measurement: "%"
    accuracy_decimals: 0
    device_class: battery
    state_class: measurement
    update_interval: never

• It is sent when the variable changes, and at no other time. Nothing republishes a value that has not moved.
• A variable that reads an analog input or a device is first sent with that sensor’s first reading, so Home Assistant is never told the 0 it holds before one. Any other variable is sent from power-up, as what it starts with.
• A variable that reads Home Assistant is not offered the tick. That would be your own entity handed back under another name.
• Two entities of one kind cannot share a name. A reported variable called what an analog input is called is refused before anything is built, in a sentence that names both.
• In an Arduino project the same thing is the MQTT section’s Announce variables to Home Assistant; this tick is the ESPHome export’s.

Changing something in Home Assistant

The other direction is an action, like everything a design does: Call a Home Assistant action, on any event or in an automation. To have a slider set a thermostat, give the slider an event on Released with:

Data is a line for each thing the action takes, a name and a value with a colon between. A variable’s name in braces puts its value in, and {widget} is the value of the widget the event is on - or of the one chosen under Widget for {widget}, which an automation needs since it is on no widget. A slider, an arc, a bar and a spinbox give their number; a switch and a checkbox give true or false. Developer tools > Actions in Home Assistant lists every action with the data it takes.

• It is ESPHome’s own homeassistant.action, sent over the link api: makes, so Join Home Assistant has to be on. Off, the action is written as a comment and the Errors tab says so.
• Everything sent is text, which is how ESPHome sends data, and Home Assistant turns it into the number or the on/off an action asks for. A list - a colour as three figures - cannot be sent this way.
• Nothing comes back. The panel is not told whether the action worked. To show the thermostat’s real setting, read it into a variable as an entity.
• In Preview the call is written to the Console tab with its values filled in, and sent to nobody.
• In an Arduino or MicroPython project the action is greyed: there the same thing is said with Publish to MQTT or a Web request to Home Assistant’s REST API.

None of this has been run against a Home Assistant: the YAML passes esphome config and the C++ ESPHome writes from it has been read.

ESPHome restarts a board that nothing has connected to for fifteen minutes. That is ESPHome’s own default for its API, and the export leaves it as it is: it is how a device that has lost Home Assistant comes back. A panel that should carry on by itself whether Home Assistant is there or not wants reboot_timeout: 0s under api:; the YAML has that line as a comment where it goes, and the README says the same.

Material Design Icons

An ESPHome project has a second icon set beside the built-in library: Material Design Icons, the set Home Assistant uses - about 7,200 of them. Writing ESPHome by hand, putting one on a screen means finding its code point on Pictogrammers' site, adding it to a font: block and typing it again as a label's text. Here you choose the icon by its name and the export writes all of that.

Choosing one

1. Select an Icon widget, or a button, and open its Icon setting in the Inspector.
2. Under the built-in icons, press Material Design Icons. The viewer opens with the whole set.
3. Type in the search box. It looks at each icon's name, the other names it goes by and what it is for, so temperature finds the thermometers and bulb the lights. The list beside it narrows to one kind of icon - Weather, Home Automation, Battery.
4. Press an icon to see it large and at 48, 32, 24 and 16 px, then Use this icon - or double-click it. From the keyboard: Down from the search box moves into the icons, the arrow keys move between them and Enter uses the one you are on.

The viewer is also on the Icons tab of the bottom panel, where it offers Add Icon widget instead, and Use on whichever Icon or button is selected. Either way it shows three things with a Copy button each, for a YAML file of your own: the icon's name, weather-cloudy, which is what a comment beside a code point says; its id as Home Assistant spells it, mdi:weather-cloudy, and its code point as ESPHome writes it, "\U000F0590".

An icon is drawn in the Text colour, like the built-in ones: an Icon widget in its own, under Style settings, and an icon on a button in the button's text colour - so a Pressed or Checked text colour changes the icon and the caption together. Any size from 8 to 160 px; these icons are drawn on a 24 px grid, so 24, 48 and 72 px are the sharpest.

What the export writes

One font: entry for each size the design draws these icons at, holding exactly the icons used at that size, each with its name beside it:

font:
  - id: mdi_48
    file: "https://raw.githubusercontent.com/Templarian/MaterialDesign-Webfont/v7.4.47/fonts/materialdesignicons-webfont.ttf"
    size: 48
    bpp: 4
    glyphs:
      - "\U000F0590"  # weather-cloudy
      - "\U000F0594"  # weather-night

and each icon as a label in that font whose text is the glyph:

- label:
    id: ui_sky
    width: 48
    height: 48
    text_color: 0xFFB300
    text_font: mdi_48
    # mdi:weather-cloudy
    text: "\U000F0590"

The font is not in the download. file: is an address: ESPHome fetches Pictogrammers' own font from their repository when it builds, converts the glyphs listed and keeps the file in its cache. The first build therefore needs a network. To build without one, save that file as fonts/materialdesignicons-webfont.ttf beside the YAML and put that path after file: instead. The address is pinned to release 7.4.47, which is the one the code points are from, so a later release cannot move an icon under you.

On a button the icon and the caption sit in a container with nothing written for their colour. That is on purpose: text colour is inherited, a container has no style of its own to get in the way, and so both take whatever text colour the button has in the state it is in.

Glyphs for a lambda

A font holds only the icons the design draws. If a lambda of your own changes an Icon's text to another icon - a weather icon that follows the forecast, say - that icon has to be in the font too, with no widget drawing it. In the viewer, choose the icon, pick the font under Add to the font (it starts at the icon font the design already uses most, or 32 px) and press Add to mdi_32. A size no icon is drawn at gets a font of its own. Everything added is listed on the Icons tab by font, each glyph with its code point to copy and a button to take it out again; Undo takes back an addition like any other change.

The export lists the added glyphs in their font after the drawn ones, under a comment, and the README names each with its font's id and code point. An Icon widget at that size is already a label in that font, so either of these changes it:

lv_label_set_text(id(ui_sky), "\U000F0599");

- lvgl.label.update:
    id: ui_sky
    text: "\U000F0599"

A label of your own needs text_font: mdi_32 (the font's id) before it can show one. Scaling the design to another display moves the added glyphs to the new size with the icons they sat beside, so they stay in the same font.

ESPHome projects only. In an Arduino or a MicroPython project the Material Design Icons button is still there, greyed, and says why; a design that already holds one of these icons - a copy of an ESPHome design, say - shows it on the canvas and has an error on the Problems tab for each, since those exports draw their icons from the built-in library and would draw nothing there. An icon cannot be put inside a line of ordinary text yet: it is a widget of its own, or a button's icon.

Web data, MQTT and Home Assistant entities

A panel can read three things over the network. Each is set up in the designer as it is for the other exports, and each is written as ESPHome’s own component, with ESPHome’s own defaults left as they are.

Web data

A web source on the Data tab is an address, how often it is asked, and the values to take out of the JSON that comes back. In the YAML it is an http_request, a script that makes the request, and an interval: at the source’s own period. Every ready-made source that does not fill a list works here, MET Norway’s forecast among them.

• The screen stands still while a request is out. ESPHome makes a request from its main loop, so nothing is drawn and no touch is read until the answer has come: a second or two over https, and up to ESPHome’s timeout of 4.5 seconds for each step when a server does not answer. The Arduino export asks from a task of its own. Ask as seldom as the data changes.
• An answer of any size. ESPHome’s own JSON parser holds a whole answer in memory, twice, and then a parsed copy of it. A forecast of 38 KB needs more than 75 KB that way, which a board without PSRAM does not have to spare. So the export ships lw_read.h, which reads the answer as it arrives and keeps only the values a variable reads. Reading that forecast for five values takes under 1 KB.
• https is checked. ESPHome verifies the server’s certificate against the common certificate authorities it carries. That is safer than the Arduino export, which does not check. If a service is refused, add use_full_certificate_bundle: true under esp32: framework: advanced:.
• A source is asked when the board joins Wi-Fi, then at its interval. One asked less often than once a minute is tried again 20 seconds after a failure, three times at most.
• A source’s key is never in the YAML. It is a name in your secrets.yaml, and secrets.yaml.example has a line for it.
• “Asking now” stays off, since no screen is drawn while a request is out. A source that fills a list is refused: lists are the Arduino export’s.

MQTT

The MQTT section of the Data tab becomes ESPHome’s mqtt: component. Each topic the design listens to is an on_message, read as a number, an on/off or text, or one value out of a JSON payload. Publish to MQTT is mqtt.publish.

• The password goes in secrets.yaml, as mqtt_password.
• TLS needs the broker’s certificate pasted in. ESPHome has no bundle of authorities for MQTT, so a broker set to TLS with no certificate is refused before the export is made.
• ESPHome’s own habits are kept. It restarts the board after 15 minutes without a broker, announces the device’s entities to Home Assistant over MQTT, says online and offline on <device name>/status unless the design names a status topic, and sends its log to <device name>/debug. The YAML has a commented line that changes each one.
• Announcing variables to Home Assistant, the Pro part of the MQTT section, is left out and the export says so. ESPHome announces its own entities: switch on Join Home Assistant in File > Project settings and every bound widget becomes one.

Reading a Home Assistant entity

A variable can read an entity of your Home Assistant: a thermometer in another room, a door, who is home. On the Data tab choose An entity of Home Assistant as the variable’s Source and type the entity’s id, such as sensor.outside_temperature. Developer tools > States in Home Assistant lists every entity with its id, its state and its attributes. Add an attribute to read that instead of the state, such as a thermostat’s current_temperature. A number is read by a sensor, an on/off by a binary_sensor and text by a text_sensor, each of platform: homeassistant:

sensor:
  - platform: homeassistant
    id: ha_sensor_outside_temperature
    entity_id: "sensor.outside_temperature"
    on_value:
      - then:
          - lambda: |-
              if (std::isnan(x)) return;
              {
                auto was = id(v_outside);
                id(v_outside) = x;
                if (id(v_outside) != was) id(lw_v_outside_changed).execute();
              }

The reading goes into the variable through its formula, and the variable’s script then updates every widget bound to it and runs its “variable changes” automations, as any other reading does.

The weather, by way of Home Assistant. This is the short road to a forecast on an ESPHome panel. Home Assistant already fetches the weather. Make template sensors there for the numbers you want on the screen - sensor.forecast_temperature, sensor.forecast_rain, a text one for the sky - then give the design a variable for each and bind a label to it. The board asks nobody: there is no request, no key and no JSON on it, and the screen never waits for a server. A web source does the same job with no Home Assistant, at the cost of a long script in the YAML and a pause while each request is out.

• Join Home Assistant has to be on. The entities reach the board over ESPHome’s own link. With it off the Variables tab says so and offers the switch, and the export is refused with the same sentence. It is also in File > Project settings.
• Before Home Assistant has spoken a variable holds what it starts with, which is the Until it is heard field under the entity: 0, off or no text unless you give it something else. A label bound to a temperature reads 0.0 for the first seconds after power-up. The first time the device is added to Home Assistant, nothing arrives until it has been allowed there.
• While an entity is unavailable or unknown the variable keeps the last thing it was told. ESPHome hands a number sensor not-a-number and a text sensor the word itself; neither is put on the screen. An attribute’s text is taken as it comes.
• A variable that reads an entity only reads it. Writing to the variable sends nothing back, so a binding from one goes one way, and a Set variable aimed at one lasts until Home Assistant next speaks - the Errors tab warns of it. To change the entity, use Call a Home Assistant action.
• What shows an entity is not published back. With Join Home Assistant on, every widget bound to a variable becomes an entity of the panel. A widget that only shows what Home Assistant said would be your own entity handed back under another name, so it is left out; the README names them. The homeassistant components are internal, which is ESPHome’s default.
• It is this export’s alone. In an Arduino or MicroPython project the choice is greyed, and the same reading can come from MQTT or a web source.
• In Preview each entity is a field in the drawer’s Simulated inputs. Until you type into it, the variable holds its starting value, as on the board.

Whatever arrives, a variable is written only when the value differs from the one it holds. A label bound to it is not given the same text again, so a scrolling one keeps its place.

Where it differs from the Arduino export

Most of the design comes across unchanged. Ten things behave differently enough to be worth knowing before you wonder why:

What is not here yet

ST7701 panels on a wiring of your own, GC9503V, and MIPI-DSI. An ST7701 or a GC9503V takes its pixels over the RGB bus but shows nothing until its registers are loaded over SPI, and that sequence belongs to the glass rather than to the controller - there is no generic one to fall back on. ESPHome keeps the sequence inside its model for a handful of named boards, so this export drives an ST7701 on one of those - the Guition ESP32-4848S040 is the 480x480 square - and refuses any other ST7701 wiring rather than sending a sequence that was written for different glass. There is no GC9503V model at all, and MIPI-DSI is not written yet. The Arduino export drives all of them: it ships nine ST7701 sequences and two for the GC9503V, and the Display tab is where you pick which one your panel wants.

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.