homeassistant_espscreen/README_EXTENDED.md

ESP Screens: the full reference

The README shows what ESP Screens is and how to install it. This page has the rest: every card and setting, what an automation can do with a screen, the top bar, the settings page on the screen itself, and how updates work.

• What you can configure
• Alert from an automation
• Wake and sleep from an automation
• Customizing tiles and colors
• Top bar
• Settings on the screen
• Updates and keeping your settings
• Guides and installation help

What you can configure

• Up to 48 tiles, spread across up to eight fixed pages of six tiles each (firmware 0.2.62+; twenty before). Search by entity, device, or room, and drag to reorder.
• Per-tile settings: a custom name, click behavior, a small slider where supported, or a large value for things like temperature and power usage. From firmware 0.2.13, the large value shows a small domain icon next to the title; a number that's too long is truncated with an ellipsis, the unit stays visible.
• Pastel backgrounds per tile: choose red for an all-off script, green for all-on, or any other color. The title and status stay dark and readable; in Dark mode the colour turns deep and the text light. The color also appears in the screen preview; Default restores the normal colors. Requires firmware 0.2.10 or newer. None drops the card entirely: the content then sits at the same size directly on the screen background (firmware 0.2.16).
• Clock: digital or analog. The analog clock has a mark for every hour (numerals at 12, 3, 6, and 9 on the Guition) and a red second hand while the screen is awake. On a single tile it shows a calendar block next to the dial (weekday, day and month; the CYD the day and month); double-width shows the digital time with the date beside it, and a full-page clock is the dial alone.
• Light control: brightness, rainbow color, and white temperature according to the light's capabilities. Open the detailed control with a long touch.
• Effects (firmware 0.2.70+): a light that offers effects (a WLED, a Hue with its candle effect) gets a sparkles key at the top right of its colour card. It opens a page with a row per thing the lamp offers, named and ordered as Home Assistant lists them: the light's effect and the select entities of its device (a WLED's colour palette, preset and playlist), plus a slider per number entity (speed, intensity). A row opens a drum picker with every name Home Assistant has at that moment; the check at the top right sends the choice. While an effect runs, the tile names it instead of the brightness.
• More cards: climate, vacuum, fan, cover, media player, sensors, select/input_select, number/input_number, switches, scenes, scripts, and buttons.
• Special cards (firmware 0.2.14+): a clock (digital or analog) as a built-in tile, a weather forecast with five days on a double-width card, a graph of the sensor history in the tile, a sun path (sun.sun: horizon with the sun between sunrise and sunset), a timer (timer.*, tapping starts or pauses it), and presence (person.*). Pick them in the library like any other tile, or drag them straight into the screen mockup; Double-width is an option for every tile, and so is Full page (firmware 0.2.62+; not for a Go to page tile): the tile takes the whole page and is one big button, so a screen by the door switches the light when you push anywhere on it. It is white or its own pastel like every other tile, and its icon shows the state (firmware 0.2.77+; before that the whole tile took its state colour while on). Its small slider, direct controls or graph sit at the bottom of the page. A Go to page tile (screen.page_1 to screen.page_8) opens another page: a full-page light switch on page 1, a menu on page 2. Under Goes to page the editor offers the pages the screen has and the next, empty one, where a new sub-page starts. From firmware 0.2.65 the same page tile may sit on several pages of a screen, such as a tile back to the menu on every sub-page; older firmware takes each page tile once.

• Direct control on double-width tiles (firmware 0.2.19+), like the rows in Home Assistant: temperature − / + or mode buttons (climate), a toggle (switch, light, fan), start/stop/dock (vacuum), open/stop/close or a position slider (cover), volume with mute or previous/play/next (media), − / + or a slider (numbers), previous/next (select), start/pause and cancel (timer), and a single button for scenes, scripts, and buttons. Configurable per tile; None keeps the regular card.
• On tap (app 0.2.67 / firmware 0.2.58): Automatic, Open control, View only, On / off for everything Home Assistant can toggle, covers included, or Perform action: any action Home Assistant has for the tile's entity, under Home Assistant's own names and with its fields, such as Set cover position at 50 %. Holding the tile still opens its card, and the tile settings only offer what Home Assistant supports for that entity.
• Home Assistant's words and icons (app 0.2.67 / firmware 0.2.58): a blind says Open or Closing, a speaker Playing and a door Open or Closed, a sensor shows the decimals Home Assistant shows, and a tile without an icon of its own gets the one Home Assistant shows, following its state.
• Home Assistant's colours (firmware 0.2.71+): a tile turns grey whenever Home Assistant calls its entity inactive, by the same rule its own cards use: a light, switch or fan that is off, an airco that is off (its tile then says Off), a closed blind, a docked robot, a player in standby, a paused timer. Otherwise it takes Home Assistant's colour for the state: an airco per mode, an alarm sensor red, a battery green, orange or red by its charge, the weather by its condition. Scenes, selects, numbers and sensors keep a colour of their own per kind.
• Weather card with current weather, the coming hours and days including chance of rain or millimeters; climate card with an on/off button, mode, fan, and swing settings. The target temperature sits big between − / + keys with one row of mode keys below; the Guition shows fan and swing right away on a card of their own, the CYD behind ···.
• Vacuum card with the state, battery and charging, start and dock, and how the robot cleans: vacuum, vacuum and mop, or mop only for robots that offer a cleaning mode in Home Assistant (such as Roborock), then suction and water. Only the rows the chosen mode uses are shown (app 0.2.46 / firmware 0.2.39). Scenes, scripts, and buttons show when they last ran. A tile that waits longer than a moment on Home Assistant shows a small spinner over the tile (see below).
• Cover card for blinds, curtains, shutters, and garage doors, like Home Assistant's own: a tall position slider on which the blind hangs from the top, a tilt slider over slats for venetian blinds, open, stop, and close, and the battery of a battery-powered blind (such as Motionblinds). A cover shows only what it supports (app 0.2.58 / firmware 0.2.50).
• Media card like a phone's "now playing" (app 0.2.77 / firmware 0.2.64): the album cover, the title, artist and album, a progress bar with the elapsed and total time, previous, play or pause and next, and a volume row with mute. Keys the player doesn't offer are faded, and a player that is off shows a power key. A Guition fetches the cover through ESP Screens, like a camera picture (docs/CAMERA.md); the CYD shows the player's icon in its place. A media tile of size Full page is the same card on the page, with the keys and the volume working on the tile.
• Cameras on a Guition (app 0.2.66 / firmware 0.2.57): a camera.* entity, or an image.* one such as a doorbell's last ring, is a tile like any other. A tap opens the picture full screen, refreshed every four seconds, with the round back key; standby and Back to page 1 close it. The same camera can bring its picture to an alert (With a camera picture). The CYD has no memory for pictures and the editor doesn't offer it camera tiles. How the picture travels: docs/CAMERA.md.
• History card for sensors, numbers, binary sensors, people, and switches, the way Home Assistant shows history: a line with an axis in round steps and clock times for numbers, with the highest and lowest moment, and a timeline with the time in each state for on/off, home and away, and a status. Choose 1 hour, 24 hours, or 1 week; hold a finger on the graph to read the value and time of that moment at the top (app 0.2.59 / firmware 0.2.51).
• Top bar per screen (firmware 0.2.32+): the name on the left, up to six items of your choice on the right: the time, an analog clock, the date, or an entity from Home Assistant with an icon, such as temperature, humidity, power usage, a door (open/closed), the alarm, who's home, or when something or someone last changed ("5 min ago", "Yesterday"). See Top bar.
• Screen settings: standby time, normal and dimmed brightness, night hours, Dark mode (firmware 0.2.54+), 24- or 12-hour clock, back to page 1 by itself and on standby, optional swiping between pages, and Page buttons (firmware 0.2.69+): switched off, the bar under the tiles goes and the tiles take its room. Change them in ESP Screens, where they apply at once, or on the screen itself. With firmware 0.2.49+ the screen keeps them, and every one of them is also an entity in Home Assistant, so an automation can switch Night mode or Auto standby (firmware 0.2.41+), for example to keep a screen on while someone is home, turn Dark mode on at bedtime (firmware 0.2.54+), and wake a screen or put it to sleep with its Wake and Sleep buttons (firmware 0.2.45+). See Wake and sleep.
• Settings on the screen itself (firmware 0.2.44+): hold the top bar for about a second and a half and the screen opens its own settings page — brightness, night, the clock, back to page 1, swiping, the page buttons, rotation, and what this screen is (name, IP address, firmware, whether Home Assistant is connected, and Restart). Changes show up in ESP Screens within a second. See Settings on the screen.
• Guition rotation: 0°, 90°, 180°, or 270°, directly from the management page. Native LVGL rotation turns the display and touch together. The CYD keeps its fixed orientation and its own calibration.
• Read current data (the ··· menu of a screen): what Home Assistant reports for every tile right now, and how each tile is set. The same menu has Identify, which blinks the screen so you know which one it is (firmware 0.2.31+), Copy layout from… another screen, and Export and Import of a layout as JSON (app 0.2.73); nothing reaches the screen before Save & send.
• Override YAML per screen (app 0.2.61): your own ESPHome YAML for one screen, such as another display controller, kept through updates. See Updates and keeping your settings.

_{What a tile can do: keys and sliders on double-width tiles, previous and next for a choice, large values, small sliders, pastel colors, a clock and a timer.}

Features depend on the capabilities Home Assistant reports for an entity. The app must keep running to keep the screens supplied with current data.

A short tap on a switch switches immediately; the off state gets a gray icon. A long press opens its history card with the toggle at the top right (firmware 0.2.51+). The tile shows the new state at once and Home Assistant's own report confirms it; a refusal puts the old state back. A spinner only appears when Home Assistant takes longer than about 0.4 seconds, and no wait lasts longer than three (firmware 0.2.59+). Tiles with a mini-slider keep their icon; on the CYD, the icon and text block are vertically centered.

Alert from an automation

Every screen has the action esphome.<screen>_show_alert (firmware 0.2.31+). It places a card over the entire screen, wakes the screen, and keeps the backlight at normal brightness until someone taps OK. In an automation:

action: esphome.kitchen_screen_show_alert
data:
  title: "Someone is at the door"
  subtitle: "Door 3, back"
  icon: doorbell
  color: orange
  button_text: "Coming"
  timeout: 0
  flash: true

• title and subtitle: a single-line title (truncated with an ellipsis if too long) and an explanation that wraps across multiple lines. Empty is allowed; an empty title becomes "Notification".
• icon: a name from the tile picker, such as doorbell, bell, alert-outline, lock, door-open, motion-sensor, smoke-detector, water-alert, mailbox, car, or account. mdi:doorbell and the hex codepoint (F12E6) also work, as long as the glyph is included in the firmware. Unknown falls back to the warning triangle.
• color: red, orange, yellow, green, mint, blue, purple, pink, or gray — the same pastel shades as the tiles. Empty gives the white card.
• button_text: the text on the button; empty is "OK".
• timeout: seconds after which the card disappears on its own; 0 means it waits for the button, however long that takes. The button always closes the card immediately, even with a timeout. Standby and night mode wait as long as the card is showing.
• flash: true makes the backlight blink four times when the alert arrives.

In ESP Screens, Alerts in the sidebar opens a cheatsheet with the exact action name for each screen, a ready-to-paste example, and all fields, icons, and colors. It starts with Try it (app 0.2.73): fill in the same seven fields, choose one screen or all of them, and send a test alert. Home Assistant asks for all seven fields; leave a field empty ("", 0, false) if you don't use it. A new alert replaces the current one. Every end is reported as the event esphome.screen_alert with action (ok, timeout, replaced, or remote), title, screen, and the device_id that Home Assistant adds, so an automation can wait for OK. esphome.<screen>_dismiss_alert clears the card remotely. With the event for every screen, the button can also perform a Home Assistant action of your choice (below).

All screens at once

From app 0.2.45, one event reaches every screen that is online, screens you add later included. ESP Screen Manager passes it on to each screen's show_alert action. The fields are the same; the ones you leave out stay empty:

actions:
  - event: esp_screens_show_alert
    event_data:
      title: "Mail!"
      subtitle: "There is post in the mailbox"
      icon: mailbox
      color: orange
      timeout: 0
      flash: true

esp_screens_dismiss_alert clears the alert on every screen. The app has to be running for these two events; the per-screen actions work without it.

With a camera picture

From app 0.2.66, the event takes one more field: camera, a camera.* or image.* entity. A Guition with firmware 0.2.57+ shows that camera's picture of the moment across the top of the card; a tap on it opens the camera full screen over the alert, and Back returns to the alert. Other screens show the same alert without the picture. The per-screen actions have no camera field.

actions:
  - event: esp_screens_show_alert
    event_data:
      title: "Someone is at the door"
      subtitle: "Front door"
      icon: doorbell
      color: orange
      button_text: "Coming"
      camera: camera.front_door

A camera or image entity also works as a tile on a Guition: a tap opens it full screen, refreshed every four seconds. From app 0.2.91 with firmware 0.2.77 a camera tile can show a live picture in the icon's place: in the tile's settings choose Display → Live picture and a pace, every 15 or 30 seconds. The picture is a small square with the tile's rounded corners, the middle of the camera's view, and it refreshes while that page is on the screen; a tap still opens the camera full screen. The camera tiles of one page share one download, so six live tiles cost the screen no more than one. A media player tile can show its album cover the same way (app 0.2.92, firmware 0.2.78): Display → Album cover puts the cover of what plays in the icon's place, refreshed when the track changes, with the tile's controls kept. How the image travels (port 8098 of the app, no token on the screen) is in docs/CAMERA.md.

With a button that does something

From app 0.2.91 the event takes an action: a Home Assistant action the app performs when the button is pressed, on whichever screen, once per alert. data gives the action's fields. The screen itself only reports the press (the esphome.screen_alert event it always sent), so this works with every screen from firmware 0.2.31 and needs no update. A timeout, a new alert over it or esp_screens_dismiss_alert leaves the action unperformed. The per-screen actions have no action field.

actions:
  - event: esp_screens_show_alert
    event_data:
      title: "Someone is at the gate"
      subtitle: "Open it?"
      icon: doorbell
      button_text: "Open"
      timeout: 120
      action: script.open_gate
  - event: esp_screens_show_alert
    event_data:
      title: "Lights are still on downstairs"
      button_text: "Turn off"
      action: light.turn_off
      data:
        entity_id: light.downstairs
        transition: 3

Ask Claude

Use Claude Code in Home Assistant? Settings → Claude → Install for Claude Code writes an ESP Screens skill to /homeassistant/.claude/skills/esp-screens, so Claude knows the events, the tile settings and every field, color and icon. Then ask, for example: "Put the vacuum on the living room screen", "Give the living room lights a brightness slider and make that tile wide", "Move the vacuum to page 1" or "Show an alert on all my screens when the mailbox is full." Claude reads what a screen shows from sensor.esp_screens_<screen> and asks before it changes anything. Download for claude.ai gives the same skill as a zip to upload in Claude under Customize → Skills. Nothing is written until you press the button.

Wake and sleep from an automation

Every screen has two buttons in Home Assistant (firmware 0.2.45+). An automation presses them with the button.press action:

• button.<screen>_wake lights the screen up: a screen in standby goes to its normal brightness (the second hand of an analog clock runs again), and the standby time starts counting again. On a screen that is already on, only the count starts again. Wake is not a touch: Back to page 1 keeps counting from the last touch, so pressing Wake on every motion doesn't keep an open card or a later page up, and a screen whose time ran out during standby lights up on page 1 (firmware 0.2.56+).
• button.<screen>_sleep puts the screen in standby right away, the same as when the standby time runs out, and also works with Auto standby off. The screen stays in standby until someone taps it, Wake is pressed or an alert comes in; switching Auto standby off doesn't end it. An alert that is showing closes (reported as remote).

Neither button saves anything on the screen, so an automation may press them as often as it likes, on every motion too. That is the difference with the Auto standby switch, which is a setting. To reach several screens at once, list their buttons:

actions:
  - action: button.press
    target:
      entity_id:
        - button.kitchen_screen_sleep
        - button.living_room_screen_sleep

Don't target an area or a device with button.press: that presses every other button there too, the Wake and Sleep of the same screen included.

Customizing tiles and colors

Click a tile in the screen preview and its settings open in a drawer beside it. Under Pastel background, choose a color, such as red or green. Optionally adjust the name, the size, what a tap does (On tap), the small slider, or a large value. Click Save & send to apply the changes. After the first supporting firmware update, this requires no new flash.

_{The settings of the Curtains tile, and that tile on the screen: open, stop and close on the tile, and a tap on its name sets the curtains to 50 %.}

A color is a fixed choice for that tile: it stays red, for example, even when you run the all-off script. The entity status and action feedback stay separately visible.

Top bar

Tap the top bar of any page in the editor's preview and the drawer shows the screen's Top bar: the name on the left, up to six items on the right. ＋ Add offers the time, an analog clock, and the date (which keep ticking on the screen itself, even without Home Assistant), suggestions from your own home (temperature and power usage from the screen's room, the weather, how many people are home, sunrise and sunset), and a search field for any entity, including a phone (device_tracker), a lock, the alarm panel, or zone.home. Drag the items to change their order; tap one to configure it:

• What to show: the state as Home Assistant writes it (21.3 °C, 65%, 1,249 W, Open/Closed, Home/Away, Armed away), or Last changed: "Just now", "5 min ago", "Yesterday". A timestamp sensor can also count forward ("In 2 hours").
• Icon: automatic, matching Home Assistant (an open door gets an open- door icon), a custom icon from the list, or no icon.
• Show: always, or only when active: the item only appears when it's on, open, home, or greater than 0. Handy for an open door or a running washing machine. Active items are colored like in Home Assistant (open door amber, alarm armed green, alarm triggered red).

The screen preview draws the bar with the same letters and rules as the screen: all values on one line with the name, icons aligned to digit height, equal spacing. If not everything fits next to the name, the name gets an ellipsis and the screen drops the leading items; the editor marks those with dashes. Until updated, older firmware shows only the name and the time (if that's in the bar).

Settings on the screen

Everything you would want to change while standing in front of the panel is on the screen itself (firmware 0.2.44+). Tiles, the top bar and the pages stay in ESP Screens, where you have a mouse.

Opening it: hold the top bar — the strip with the screen's name and the clock — until the blue line along the top edge is full, about a second and a half. Letting go early cancels. Rather have a button? Put the built-in Settings card on a page like any other tile. From Home Assistant, esphome.<screen>_open_settings opens it too (page 0 menu, 1 Brightness, 2 Night, 3 Screen, 4 This screen, -1 closes it).

Group	What is on it
Brightness	Brightness, Dark mode, Auto standby, Standby after, Standby brightness
Night	Night mode, Starts, Ends, Night brightness
Screen	Back to page 1 by itself and after how long, also on standby, swiping between pages, page buttons, rotation (boards that turn)
This screen	Name, IP address, firmware version, Home Assistant connected, Restart

The language, the 12 or 24-hour clock and how numbers are written are the same on every screen: Settings → Language & region in ESP Screens (app 0.2.90, firmware 0.2.76). They follow Home Assistant's language unless you choose otherwise. ESP Screens writes the language into each screen's YAML (LANGUAGE: "nl" under substitutions:), and the screen shows it after its next firmware update. A screen whose YAML ESP Screens can't reach, such as one you build with ESPHome on another machine, gets that line from you: a code from screen_manager/translations; English is the default. Translating ESP Screens says how to add or check a language.

Tap a toggle to flip it, - and + to change a number or a time — hold them and a time walks whole hours — and tap a chip like the clock to cycle it. Every change is saved on the screen, takes effect at once, and appears in ESP Screens within a second, so both sides always show the same value. The Screen settings cards in ESP Screens have the same rows.

In Home Assistant (firmware 0.2.49+), every setting is an entity on the screen's device, under Configuration: number.<screen>_normal_brightness, switch.<screen>_night_mode, time.<screen>_night_starts, switch.<screen>_dark_mode, select.<screen>_rotation on a Guition, and the rest. An automation, the settings page and ESP Screens all change the same value, and setting a value the screen already has costs nothing. The full list is in docs/SETTINGS.md.

Updates and keeping your settings

Change	Action
Tiles, names, colors, or order	Save in ESP Screens; no firmware flash
Screen settings	Change them in ESP Screens (they apply at once), on the screen, or on their entities in Home Assistant
New version of the management page	Update ESP Screen Manager in the HA App store
New feature on the physical screen	The Update button on the screen (badge Update x.y.z), or Update automatically every night under Settings
Your own YAML for one screen	Override YAML in ESP Screens; kept through updates (app 0.2.61)

Every app version belongs to one firmware version. After an app update, the list shows per screen whether newer firmware is available. Update builds that screen's own profile with the built-in CLI, installs it wirelessly, and waits until the screen is back. With the checkbox enabled, that happens automatically at night, one screen at a time; a failure stops the round and posts a notification in Home Assistant. Firmware 0.2.17+ reports its own device name and IP address for this; an older screen asks for the IP address once. You can still do it manually via Firmware & USB in the sidebar → Wi-Fi / OTA.

The device's own YAML and Wi-Fi/API/OTA settings stay in the ESPHome config folder. Tile layouts and options live in the app's persistent data. CYD calibration and screen preferences stay stored on the device. Updates don't replace this user data. Do still make normal Home Assistant backups and keep your device profiles; removing an app or wiping flash memory is not an update.

Your own YAML for one screen (app 0.2.61). Override YAML in ESP Screens edits a small <screen>.local.yaml beside the screen's profile, for hardware-specific changes such as another display controller. It is loaded after the shared board package and stays in place when the app or the firmware package updates. The screen's name, Wi-Fi, API, OTA, packages, external components and captive portal stay managed and are refused there. Save & check runs ESPHome's full validation of the complete profile, and a build never starts from an invalid one.

Efficient, even with many screens (0.2.39 / firmware 0.2.33). The app sends a screen only the tile that changed, as a single action (esphome.<device_name>_screen_message) instead of chunks in a text field. Every two minutes, a small ping follows with the layout revision; if the screen reports that it doesn't match (after a restart, for example), everything is resent. Firmware 0.2.49+ answers that ping, and a new layout, directly, so a screen that still lacks a tile gets it again after 30 seconds instead of two minutes. Graphs on sensor tiles come from Home Assistant's statistics, in one query for all screens. Older firmware still works via the text field and the full resend every two minutes. The diagnostic sensor Uptime has been replaced by the Last boot timestamp.

See the release history and releases and protocol compatibility.

If you publish your own fork: every push to GitHub is a release. Always also bump the add-on version in screen_manager/config.yaml and log the change in the CHANGELOG, otherwise the HA App store won't offer an update. A change to the screen also gets a new SCREEN_FIRMWARE_VERSION in packages/core.yaml, the one place both boards take it from, and the same FIRMWARE_VERSION in screen_manager/app/core.py.

Guides and installation help

• Complete installation from ESP Screens
• ESP Screens with Home Assistant Container (Docker)
• Guition hardware, mounting, and rotation
• Elecrow CrowPanel 7.0" hardware, touch and flash
• CYD calibration and USB diagnostics
• Camera images and album covers
• Troubleshooting
• Instructions for developers and LLMs, with how a screen's YAML is put together, settings, colours and Dark mode and releases

Give a developer or LLM a clean copy of this repository and, for example:

Read AGENTS.md, README.md, and docs/EASY_SETUP.md. Help me install this CYD or Guition screen via USB on my Home Assistant. Identify the board and use my existing profile if one already exists. Guide me through calibration, HA pairing, tile selection, and physical tests. Keep keys local, and state which checks were actually carried out.

A successful build doesn't prove the physical touch or panel image is correct. The owner must check the display and perform the requested taps.