FIRMWARE & USB
Build and install screen firmware
✕
The built-in ESPHome CLI uses your own profile (YAML with keys)
and secrets. Choose the screen's profile, then a USB port (screen
connected to the Home Assistant machine), Wi-Fi / OTA with the hostname,
or Download to put the firmware on the screen from your own computer.
Check only validates, Build only compiles,
Build & install puts the firmware on the screen. Your tiles
stay as they are in ESP Screens. The first build takes a few minutes.
ESPHome profile
Install to
Wi-Fi / OTA
IP address or hostname
Check Build only Build & install
Download firmware
Put it on the screen with
ESPHome Web
in Chrome or Edge: Connect, choose the screen's USB port, Install, and select this file.
It holds your Wi-Fi password and the screen's keys: keep it to yourself.
ADVANCED · LOCAL OVERRIDE
Override YAML
✕
This small file is yours. It is loaded after the shared screen package and stays in place when
ESP Screen Manager updates. Change hardware-specific details here, such as a display model.
⌘
What is safe to change?
Display, touchscreen, substitutions, pins and other device details. Name, Wi-Fi, API, OTA and package links remain managed.
Use example
Clear
Save & check
Save override
ALERTS · CHEATSHEET
A full-screen notification, from an automation.
✕
Every screen has the show_alert action. It places a card over everything,
wakes the screen, and keeps the backlight at normal brightness until someone taps
the button or the timeout runs out. Home Assistant itself shows no explanation or
dropdowns for ESPHome actions; everything you can fill in is listed here.
Someone is at the door
Door 3, back
Coming
Your screens
In an automation
All screens
The fields
Icons
Colors
Behavior
Events
Tips
Your screens
Every screen has its own action, with the device name in it. From firmware
0.2.31; update an older screen with its
Update button under My screens.
In an automation
Add action and search for ESPHome . Choose your screen's action:
Home Assistant calls it "Performs the action show_alert of the node
device name ".Fill in the fields. Home Assistant asks for all seven; leave what you don't
use empty ("", 0, off).Prefer YAML? Choose Edit in YAML on the action and paste the example
below.
All screens at once
Fire the event esp_screens_show_alert with the same
fields, and ESP Screens passes the alert on to every screen that is online, including
screens you add later. esp_screens_dismiss_alert
clears it everywhere. In an automation, add the Event action or paste the example
under Edit in YAML . Leave out the fields you don't use. ESP Screens has to be
running for this.
The fields
Text is free-form; the limit is in bytes, and an accented letter counts as two.
What doesn't fit gets an ellipsis (title) or is dropped (subtitle).
Icons
Fill in the name in icon, for example doorbell.
mdi:doorbell and the hex codepoint (F12E6) also work.
Only these icons are included in the firmware; any other name shows the
warning triangle. Tap an icon to copy its name.
Handy for notifications
Search for an icon
Colors
Fill in the name in color. These are the pastel shades of the tiles,
with dark text. Empty or unknown gives the white card. Tap to copy.
Behavior
Wakes the screen. An alert immediately wakes a dimmed or dark screen and
appears above every page, every open light card, and the standby layer.On until the button. As long as the card is showing, the backlight stays at
normal brightness. Standby and night hours wait. After the button, the regular
standby time starts again.Timeout. timeout: 0 waits for the button, however long that
takes. With timeout: 60 the card disappears after a minute, but the
button closes it sooner.Blinking. flash: true blinks the backlight four times
when the alert arrives (about a second) and leaves the screen on afterward.Replacing. A new alert replaces the current one; there's no stack.
The replaced alert reports itself as replaced.Closing remotely. dismiss_alert clears the card,
for example if the door is already open. Without an alert, that action does nothing.Tapping beside the card does nothing; only the button closes it. That way a
wake-up tap never accidentally dismisses the alert.
Events
Every end fires the event esphome.screen_alert
with action, title, screen (the device name)
and the device_id that Home Assistant adds. Visible under
Settings → Tools → Events.
Waiting until someone presses the button
Tips
Use a color per kind of notification : orange for the door, red for
smoke or water, green for "done". The text always stays dark and readable.
Keep the title short ; a screen shows about twenty characters on one line and
ends a longer title with an ellipsis. Put details in the subtitle.
A custom button text turns the notification into a question: "Coming", "Seen",
"Turn off". The event then tells you who responded.
For an alert that resolves itself (the door opens, the laundry gets taken out)
close it in the same automation with dismiss_alert.
Every screen? Fire esp_screens_show_alert once (see All screens at
once). The screens still work independently and each reports with its own
screen.
Rather ask Claude for the automation? Install the ESP Screens skill under
Settings → Claude.