homeassistant_espscreen/README.md

Home Assistant ESP Screens

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 twenty tiles over four pages: lights, climate, blinds and curtains, the vacuum, media, the weather, history graphs, clocks and timers. An automation can put an alert on every screen when someone rings the bell.

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 to screen: no reflash, no YAML to write, no blueprint, MQTT or token.

Install it · Full reference · What's new

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. Rendered from the firmware's own LVGL code with a demo home.}

_{The same cards on the 2.8-inch CYD, 320 × 240.}

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

Managed from Home Assistant

_{ESP Screens, a page in Home Assistant: every screen on the left, its top bar and tiles on the right.}

_{Search your home, drop a tile on the preview, tap it for its name, width, control and color. Save, and the screen has it.}

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

Alerts

_{Someone at the door? One action in an automation wakes the screen and shows it, on one screen or all of them. 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, 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.

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 Settings → New screen: 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.
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 to screen. Then test the physical controls.

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

You can install new firmware later from Settings → Firmware & USB → Wi-Fi / OTA. 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.

ESP Screens is MIT licensed, see LICENSE.