Home Assistant ESP Screens

Thank you! I work on this project with a lot of love, and every bit of support helps. I truly love the Home Assistant community.

A touch screen for every room that you lay out yourself, and manage from Home Assistant. Incredibly easy to set up and to use.

Why. Your phone is in the other room and a tablet on the wall is expensive. A small ESP32 touch panel costs a fraction of that, sits on a table or in a wall box, and is always at hand for the lights, the heating or the vacuum.

What. Firmware for affordable panels, five of them today, from the 2.8-inch CYD to the 10.1-inch Guition, with tiles over up to eight pages, as many per page as the glass holds: lights, climate, blinds and curtains, the vacuum, media, the weather, history graphs, clocks and timers, and on every screen but the CYD your cameras. A tile can take the whole page, one big switch you push without looking, and a tile can go to another page. An automation can put an alert on every screen when someone rings the bell, and a screen with room for pictures shows who is there with the doorbell camera's picture. A tap can run any action Home Assistant has for a tile, and Dark mode suits a screen beside the bed.

How. ESP Screen Manager is an app inside Home Assistant. It flashes a new screen over USB, updates it over Wi-Fi and sends it your tiles. Changing a screen is pick, drag and Save & send: no reflash, no YAML to write, no blueprint, MQTT or token. Brightness, night hours and Dark mode can also be changed on the screen or by an automation, and your own YAML for one screen survives every update.

Install it · Full reference · What's new

In real life

A Guition in the living room, 37 seconds in one take: tapping tiles, swiping through the pages, opening cards and a history graph, while the lamp behind it goes from purple to orange.

https://github.com/user-attachments/assets/f9f6a933-d388-4c8b-9c9a-011dfa37617b

_{Real photos, not renders: the 4-inch Guition next to the lamp it controls.}

Five screens supported, 2.8 to 10.1 inch

One home, five panels. A screen is built for the glass it runs on: it measures its own canvas at boot and gives a page the cells that board has, six tiles on the 2.8-inch CYD and twenty on the 10.1-inch Guition, while a tile stays about the same size in millimetres. The same tiles, the same cards, the same editor; the bigger the glass, the more of your home fits on one page.

_{To scale, each with the page it fills: the same home on the 2.8-inch CYD, the 4-inch Guition, the 4.3-inch and 7-inch Waveshare, and the 10.1-inch Guition. Rendered from the firmware's own code, one board at a time.}

_{The same home standing up. Which way a screen hangs is chosen when it is built, and every board that is not square hangs either way, with a grid of its own: the 10.1-inch Guition 4 × 5 instead of 5 × 4, the 7-inch Waveshare 2 × 7 instead of 4 × 4. Which board is which, and what to look for when you buy one: Which screen.}

On the screen

_{Tap a tile to switch it, hold it for the full card. Keys and sliders right on the tile, pastel colors, a clock, the weather and history you can read with a finger. A lamp with modes (a WLED) gets an effects page with a drum picker, named and filled from what Home Assistant lists for it. The media card shows what plays with its album cover, fetched by ESP Screens like a camera picture, and a media tile can show that cover in the icon's place (how). Rendered from the firmware's own LVGL code with a demo home.}

_{Cameras are tiles too, not only part of an alert: any camera or snapshot in Home Assistant (a doorbell's last ring, for example) goes on a screen like any other tile. Tap it for the picture full screen, refreshed every four seconds, or let the tile itself show a small live picture in the icon's place (Display → Live picture, every 15 or 30 s); an alert can carry the same picture. Every screen but the CYD, which has no memory for pictures (how it works).}

_{The same cards on the 2.8-inch CYD, 320 × 240. The CYD has no memory for pictures: its media card shows the player's icon in the cover's place.}

_{Dark mode, for a screen beside the bed: the same pages, darker. It is a switch on the screen, in ESP Screens and in Home Assistant, so an automation can turn it on at bedtime.}

_{Settings on the screen itself: hold the top bar. The same brightness, Dark mode, standby, night hours, clock and rotation as in ESP Screens, and every one of them is an entity in Home Assistant.}

Managed from Home Assistant

_{ESP Screens, a page in Home Assistant: your screens on the left, the pages of the chosen screen in the middle with the values Home Assistant reports right now, the library on the right.}

_{Search your home, drop a tile on the preview, tap it for its name, width, control and color, and for what a tap does: open its card, switch it, or run any action Home Assistant has for it, such as the curtains to 50 %. Save, and the screen has it. ⌘K searches screens, entities and actions; Identify blinks a screen so you know which one it is.}

_{A top bar built from your own home, firmware updates over Wi-Fi (every night if you like), and a skill so Claude can rearrange your screens.}

_{Screen settings apply at once, and a change made on the screen or by an automation shows up here too.}

_{Other hardware, such as a different display controller? Every screen has an Override YAML of its own, checked by ESPHome before a build and kept through every update.}

In your language

_{The same home in German, French and Polish. The screens follow your Home Assistant: its language, its words for a light or a robot, and how your country writes a date, a time and a number — 75 % in German and French, 75% in Polish and English.}

The screens, the editor and its messages speak English (US and UK), Nederlands, Deutsch, Français, Italiano, Español, Português and Polski. Nothing to set up: ESP Screens takes the language of your Home Assistant.

_{Settings → Language & region, when you want something else than Home Assistant's own.}

• The editor follows the language of your Home Assistant profile, so two people in one house each read their own.
• A screen carries one language, built into its firmware: change it and press Update on the screen (or let the nightly round do it). The clock (24 hours or 12 with AM/PM) and the number format change straight away, on every screen at once.
• Words from Home Assistant stay Home Assistant's: what a door, an airco or a robot says on a tile and in its card is the word its own dashboard shows, in your language.

Most languages still need someone who speaks them to read the texts through, and a new language is one file. Translating ESP Screens walks through both; a language without a file falls back to English while it keeps your country's clock and numbers.

Alerts

_{Someone at the door? One event in an automation wakes every screen and shows it. Add the doorbell camera and a Guition shows who is there; tap the picture, or a camera tile, for the camera full screen, refreshed every few seconds. Camera images.}

_{Any alert, on one screen or all of them, in a pastel color of your choice. How alerts work. An automation can also put a page in front, such as the page with the full-page player when the music starts: Open a page from an automation.}

Installing from Home Assistant

Which screen

Use these exact board variants: similar-looking product names can have different controllers or connectors. Wallbox relays are not controlled. ESP Screens builds with its own ESPHome 2026.9.0. The firmware also builds in your own ESPHome Device Builder with ESPHome 2026.6.2 or newer; the 10.1-inch Guition asks for 2026.8.0 or newer, because its touch panel is newer than that.

The 10.1-inch Guition is new in this release and has not yet been through our own acceptance test: its hardware was worked out and flashed on a real panel, and the screens' own software is the same on every board, but the two have not stood on one desk together. Tell us how it goes. It needs a panel with pre-v3 silicon (the boot log says chip revision: v1.3 or another below v3.0), which is what these panels have shipped with so far; rev3 silicon needs a firmware of its own.

Do I need ESPHome?

You don't need to install the separate ESPHome Device Builder app. ESP Screen Manager already includes the ESPHome CLI and can build firmware itself, install it via USB or give you the file to put on the screen from your own computer, and later update it wirelessly over OTA.

You do need to pair the flashed screen via the ESPHome integration in HA. That pairing lives under Settings → Devices & services, not in the App store. Add the discovered device there. If it doesn't appear automatically, choose Add integration → ESPHome and enter the screen's IP address. If asked for a key, use the api.encryption.key from your own device YAML, and grant the device permission to perform Home Assistant actions.

So a fresh installation without ESPHome Device Builder also works. If there's no ESPHome secrets.yaml yet, our wizard asks for Wi-Fi once and stores it locally. Existing Wi-Fi secrets are reused. API and OTA keys are generated per new screen and stay in that device's own profile.

Step by step

For Home Assistant Container (Docker) without the App store, follow ESP Screens with Docker.

For Home Assistant OS with Apps/Add-ons on aarch64 or amd64:

1. Open the App store and add this repository: https://github.com/MaxGramser/homeassistant_espscreen.
2. Install ESP Screen Manager, start the app, and open ESP Screens. ESPHome Device Builder is optional: the ESPHome CLI is already in this app.
3. Connect the screen with a USB data cable to the Home Assistant machine and choose New screen in the sidebar: CYD or Guition, a name, the USB port, and Install. If Wi-Fi is missing from the ESPHome secrets.yaml, the window asks for it once and ESP Screens only adds the missing lines. The profile with unique API and OTA keys goes into the ESPHome folder; the build and flash run in the same window (a first build takes a few minutes on a Raspberry Pi). Each screen gets its own profile. Is Home Assistant on a server or in a virtual machine, out of reach of the screen? Choose Download under Install via: ESP Screens builds the firmware, and you put it on the screen from your own computer with ESPHome Web in Chrome or Edge. After that, updates go over Wi-Fi as usual.
4. CYD: go through the calibration on the screen. Guition: uses GT911 without resistive calibration. Then pair the discovered ESPHome device in Settings → Devices & services using the API key the window shows after installation (copy button). Grant the device permission to perform Home Assistant actions.
5. Select the screen in ESP Screens, choose your tiles, and click Save & send. Then test the physical controls.

_{New screen (step 3) and choosing your tiles (step 5).}

New firmware goes on over Wi-Fi with the Update button of a screen in ESP Screens, or by itself every night if you turn that on under Settings; Firmware & USB → Wi-Fi / OTA in the sidebar installs it by hand. For an existing screen, always use the existing profile; creating a new installation profile generates new keys.

The complete installation guide walks through every step in more detail.

More

• Full reference: every card and setting, alerts and wake/sleep from an automation, the top bar, the settings page on the screen, and how updates keep your settings.
• Guition hardware, mounting, and rotation · CYD calibration and USB diagnostics · Troubleshooting · Release history

Credits and license

The very first version started from Adrian Kuehlewind's ESPHome-touch-display-mount. Little of that code is left, but his repository has 3D-printable desk, under-desk, wall and flush mounts for the CYD.

The front door in the camera pictures is a photo by Virginia Marinova on Unsplash.

ESP Screens is MIT licensed, see LICENSE.