Max Gramser
dfd1a26d69
Wake from Home Assistant counted as a tap: it reset last_touch_ms, the one clock that standby and Back to page 1 both read. An automation pressing Wake on every motion therefore held an open card or page 2 up for as long as someone moved in the room. Back to page 1 now has its own clock, last_use_ms, written only by the boot, the touchscreen triggers, open_settings from Home Assistant and the UI self test. Wake, an alert ending and Auto standby on still restart the standby time, and Wake still brings back the brightness and the second hand. The rule moved from the interval into the script back_to_page_1_when_due. Wake runs it right after waking a dimmed screen, so a page whose time ran out during standby lights up on page 1 instead of jumping there a second later. ESP Screens no longer opens the first screen by itself. Until one is picked the page says "Choose a screen", and with no screens it still offers the install; both cards start hidden so neither flashes while the page loads. Checked with 48 host API checks per board, both ESP32 builds, 314 Python and 16 C++ tests, and the editor on the demo home. Firmware 0.2.56. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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:
- Open the App store and add this repository:
https://github.com/MaxGramser/homeassistant_espscreen. - Install ESP Screen Manager, start the app, and open ESP Screens. ESPHome Device Builder is optional: the ESPHome CLI is already in this app.
- 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. - 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.
- 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.