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

The Guition 4-inch screen on a table: the second page with scenes and scripts, the robot vacuum and a table lamp with a brightness slider The vacuum card on the Guition: start cleaning, return to dock, find my robot and the suction power

**A touch screen for every room that you lay out yourself, and manage from Home Assistant.** **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 two affordable panels, the 2.8-inch CYD and the 4-inch Guition, with up to 48 tiles over eight pages: lights, climate, blinds and curtains, the vacuum, media, the weather, history graphs, clocks and timers. 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 Guition 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](#installing-from-home-assistant)** · [Full reference](README_EXTENDED.md) · [What's new](screen_manager/CHANGELOG.md) ## On the screen

Guition 4-inch screen: an analog clock with the date, a temperature graph, the weather forecast, a lamp and presence Double-width tiles with direct control: the heating setpoint, a dimmer and the Sonos volume An energy graph, the robot vacuum, a coffee machine, a fan and a good-night script with pastel backgrounds

A full-page tile: one big amber light switch that fills the screen, so you push anywhere without looking A full-page heating tile: the room temperature big in the middle, the mode keys at the bottom

Weather card: current weather, the coming hours and the coming days with chance of rain Climate card: the target temperature between big minus and plus keys, the mode keys, and fan and swing choices Light control: color, color temperature and brightness

Vacuum card: docked and charging, start and dock, the cleaning mode vacuum, vac and mop or mop, suction and water Cover card for a venetian blind: its battery, the position slider with the blind hanging from the top, the tilt slider over slats, and open, stop and close A finger on the history graph: the top of the card shows the average of that hour and its time, the graph stays as it is

The media card on the Guition: the album cover, the title, artist and album, a progress bar with the elapsed and total time, previous, pause and next keys and the volume slider A media player over the whole page: the cover at the left, the track, the bar and the keys beside it, the volume row along the bottom The media card in dark mode: the same cover and keys on a black page

_{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. The media card shows what plays with its album cover, fetched by ESP Screens like a camera picture (how). Rendered from the firmware's own LVGL code with a demo home.}

CYD 2.8-inch screen: the weather forecast, a kitchen timer, the coffee machine, a lamp and power usage as a large value Second CYD page: Sonos volume, presence, a scene and an energy graph The weather card on the CYD: current weather, the coming hours and the coming days

The CYD with heating mode keys, playback keys for the radio and a ceiling fan's speed slider The vacuum card on the CYD: state, battery and charging, clean and dock, the cleaning mode, suction and water The history card on the CYD: power over 24 hours with its highest and lowest moment, an axis in watts and clock times

The media card on the CYD: the player's icon where the cover would be, the title, artist and album, the bar with its times, the keys and the volume slider A media player over the whole CYD page: the icon at the left, the track and the keys beside it, the volume row along the bottom The media card on the CYD in dark mode

_{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 on the Guition: the same home page with a black page, graphite cards and soft white text, the clock, the temperature graph, the weather, a lamp and presence Dark mode with direct control: the heating setpoint, the dimmer's slider and the Sonos volume keep their colours Dark mode with pastel backgrounds: the coffee machine and the good-night script keep their colour, deeper

_{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.}

The settings page on the Guition, Screen: the 12 or 24-hour clock, back to page 1 by itself and after how long, also on standby, swiping between pages and the rotation The same Brightness page right after turning Dark mode on: a black page with graphite rows and soft white text

_{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 in Home Assistant: your screens in the sidebar, the pages of the living room screen side by side with their top bar, and the entity library on the right

_{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.}

Choosing tiles: the pages of the screen side by side, next to the library with its search and filters Tile settings of the curtains in the drawer: double-width with open, stop and close on the tile, what a tap does, and the pastel background

_{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.}

Add to the top bar, in the drawer: the time, an analog clock, the date, suggestions from your own home and any entity Settings in ESP Screens: New screen and Firmware & USB, the firmware updates, the Alerts cheatsheet, and the Claude skill

_{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.}

The Screen settings tab in ESP Screens: Brightness with standby, Night with its hours and brightness, and Screen with the clock, back to page 1, swiping and the rotation

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

Override YAML for the living room screen: a small file of its own, loaded after the shared package, here with the example that changes the display controller

_{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.}

## Alerts

An alert on the Guition with the front door camera's picture across the top: someone is at the door, with a Coming button The front door camera full screen on the Guition, with the round back key and the camera's name at the top

_{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.}

An alert on the Guition: someone is at the door, with a Coming button The Alerts cheatsheet in ESP Screens: the action name of every screen, ready to copy

_{Any alert, on one screen or all of them, in a pastel color of your choice. How alerts work.}

## Installing from Home Assistant ### Which screen | Screen | Resolution | Display / touch | | --- | --- | --- | | CYD ESP32-2432S028 | 320 × 240 | ILI9341 / resistive XPT2046 | | Guition ESP32-S3-4848S040, 4 inch | 480 × 480 | ST7701S RGB / capacitive GT911 | Use these exact board variants: similar-looking product names can have different controllers or connectors. Wallbox relays are not controlled. The firmware and built-in CLI are tested with **ESPHome 2026.6.2**. ### 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. | Component | Needed? | What for? | | --- | --- | --- | | ESP Screen Manager app | Yes, for this installation route | Installing firmware, managing tiles, and sending current data to the screen | | ESPHome Device Builder app | No, optional | Alternative editor and firmware installer; the same CLI is already in ESP Screens | | ESPHome integration in HA | Yes, pair every screen | The connection between Home Assistant and the physical screen | 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](docs/DOCKER.md). 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](https://web.esphome.io) 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 in ESP Screens: choose the board, give it a name, pick the USB port and install Choosing tiles: the pages of the screen side by side, next to the library with its search and filters

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

You can install new firmware later from **Firmware & USB → Wi-Fi / OTA** in the sidebar. For an existing screen, always use the existing profile; creating a new installation profile generates new keys. The [complete installation guide](docs/EASY_SETUP.md) walks through every step in more detail. ## More - **[Full reference](README_EXTENDED.md):** 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](docs/GUITION.md) · [CYD calibration and USB diagnostics](docs/CALIBRATING.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Release history](screen_manager/CHANGELOG.md) ## Credits and license The very first version started from Adrian Kuehlewind's [ESPHome-touch-display-mount](https://github.com/akuehlewind/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. ESP Screens is MIT licensed, see [LICENSE](LICENSE).