homeassistant_espscreen/docs/EASY_SETUP.md

Installing and managing from ESP Screens

A new screen, from USB to everyday use

With ESP Screen Manager, you choose your tiles in Home Assistant. You search by name, device, room, or entity ID, arrange them in the order you want, and click Save & send to screen. After that, the status stays automatically up to date. You don't need to reflash for different tiles.

This works with Home Assistant OS on a 64-bit Raspberry Pi or an amd64 machine, and one of these exact screen variants. The ESPHome CLI is included in ESP Screen Manager; ESPHome Device Builder is optional:

Choice	Hardware
CYD	ESP32-2432S028, 320×240, ILI9341 and XPT2046
Guition	ESP32-S3-4848S040, 480×480, ST7701S and GT911

Other screens with roughly the same name can have different pins. Use the board profile that matches the hardware. Use a USB cable that supports data. The wallbox relays are not used.

1. Install ESP Screen Manager

1. Open Settings → Apps → Install app (on older HA versions: Settings → Add-ons → Add-on Store).
2. Open the menu in the top right → Repositories and add: https://github.com/MaxGramser/homeassistant_espscreen.
3. Install and start ESP Screen Manager. Turn on Start on boot and Show in sidebar. Open the ESP Screens web interface.

This app includes the tested ESPHome 2026.6.2 CLI and runs within your HA login. A second ESPHome management page, MQTT, blueprint, or long-lived token is not needed. Use the GitHub version for updates; a local test add-on is a separate app.

2. New screen: connecting and installing

1. Connect the screen with a USB data cable to the machine running Home Assistant. With multiple boards: connect them one at a time for the first installation, or check which port belongs to this screen.
2. Click New screen. Choose CYD or Guition and give the screen a name, for example Kitchen. The device name (kitchen) follows from that; use customize to choose a different one.
3. Wi-Fi: if wifi_ssid and wifi_password are already in the ESPHome secrets.yaml, the screen uses them automatically. If they're missing, or the file doesn't exist yet, the window asks for them once and ESP Screens only adds the missing lines to secrets.yaml; comments and other secrets are left alone. If secrets.yaml isn't valid YAML, fix that yourself first.
4. Under Install via, choose this screen's USB port and click Install. ESP Screens stores the profile (kitchen.yaml, with unique API and OTA keys) in the ESPHome folder, builds the firmware, and writes it over USB. The ESPHome log and the current phase (building, writing) are in the same window; a first build takes a few minutes on a Raspberry Pi. You can close the window: the installation keeps running and picks back up when you reopen it.
5. After Done, the window shows the API key with a copy button and the pairing steps from chapter 3. If the build fails, the log stays open and you can Retry.

Every screen gets its own profile: four screens means going through New screen four times, with four different names. The shared board package is the same for every screen; the profile only holds the name, keys, and the Wi-Fi reference. Keep that profile and reuse it for updates. Going through New screen again for an existing screen generates new keys and is not the update route.

No USB port in the list? A cable plugged into your laptop isn't visible to the Raspberry Pi. In that case, choose Later · save profile only: the profile then sits in the same folder ESPHome Device Builder uses, so you can open it there and flash from your browser (Install → Plug into this computer), or install it to the HA machine later via Firmware & USB.

CYD: calibration appears on first boot. Calmly tap the visible crosshair three times, hold each tap briefly, and follow each next crosshair in turn. There are five positions. The center checks accuracy. On a failed measurement, the screen asks you to start over. The correction is stored locally and survives OTA updates. Use the HA device button Calibrate touch to measure again later. For diagnostics and the older manual installation, see: CALIBRATING.md.

Guition: the GT911 touch mapping is baked into the board profile; there's no ADC calibration.

3. Pair the screen with Home Assistant

This happens in Home Assistant itself, outside ESP Screens. As long as a profile hasn't been added to Home Assistant yet, it appears on the left under My screens as a not yet in Home Assistant card, with an Open Devices & services button and Copy API key; the done screen of New screen has the same button. The card disappears once the screen is in the list.

1. Open Settings → Devices & services. Add the discovered ESPHome device. Not discovered? Manually add the ESPHome integration with the screen's IP address, port 6053.
2. Does HA ask for an encryption key? Paste the API key the window shows after installation (also found as api → encryption → key in the profile). Don't use the OTA password.
3. On the ESPHome integration, open Configure and enable Allow the device to perform Home Assistant actions. Without this permission, values still show up, but the screen can't control lights and devices.
4. Open ESP Screens. The screen appears within about 30 seconds.

4. Choose and edit your tiles

Tip: in your ESPHome YAML, add the line power_save_mode: none under wifi: (new wizard YAMLs already have it); the screen is mains-powered, so this keeps it responding to Home Assistant without Wi-Fi sleep delay.

Select your screen, fill in the title, and search for entities. The picker has domain filters with colored icons. You can add up to twenty tiles. The screen preview shows their placement: two columns, six slots per page, up to eight pages. Every tile has a fixed slot that only changes if you drag it; empty slots stay empty, wherever you leave them. Drag a tile onto an empty slot and it stays there; drag it onto another tile and the two swap (the other tile takes the freed-up slot, or otherwise the nearest free slot); everything else stays put. While dragging, the preview already shows where everything will land; an empty page then stands ready below the last page. Add page creates an empty page that's kept; an empty page gets Remove page. Click an empty slot to place the next tile from the picker there. Use the arrow keys to move a focused tile. Click a tile for a custom name and Configure control & display: click behavior, a mini-slider, a large value, a graph (sensors), a weather forecast (weather), or the Double-width setting. A double-width tile for a climate, switch, light, fan, vacuum, cover, media player, number, select, timer, scene, script, or button gets direct control on the right, like the rows in Home Assistant (for example temperature − / +, open/stop/close, volume with mute, a toggle); under Direct control on the tile, choose which set, or None (firmware 0.2.19+). Open control on a weather tile shows the weather card with the coming hours and days (rain included); on a climate tile, the card with an on/off button and the mode, fan, and swing settings. The built-in Clock sits at the top of the picker; find sun, timers, and people via the filters. Under Pastel background, choose a custom color with dark text; Default restores the normal look, and None drops the card, so the content sits the same size directly on the screen background (firmware 0.2.16+). This requires firmware 0.2.10+. Adding without a chosen slot fills the first free slot. Fixed slots and empty slots work on the screen from firmware 0.2.26 on; older firmware shifts the tiles up to the first free slot, and the editor notes that below the preview. The preview shows the layout, not live sensor values. Click Save & send to screen to send your changes.

• Light, switch, input_boolean, and fan: tap to turn on/off.
• Long press a light: brightness, rainbow color, and white temperature, as far as the light supports those features.
• Climate, vacuum, and cover: tap to open the control card.
• Long press a fan: speed, if the device supports percentages.
• Scene/script: tap to run; button/input_button: tap to press.
• Sensor: tap for the history card; set 1, 6, or 24 hours on the tile.
• Binary sensor: view status. Select/input_select: open the picker menu.

From firmware 0.2.7, twenty tiles fit across up to four pages. Older firmware keeps the limit of ten until you update. Under General settings → Swipe between pages, you can enable swiping. On the Guition (firmware 0.2.24+), you then swipe inward from the left or right edge, like the back-swipe gesture on a phone; slow or fast, and a swipe starting in the middle of the screen does nothing, so tapping and dragging tiles never accidentally changes pages. On the CYD, it stays a quick swipe across the screen. Sliders only control their value; detail menus and standby don't change pages.

Six tiles sit on a page. With six or fewer, Previous/Next disappear. The default standby time is ten minutes. For offline devices, the screen blocks actions. If the connection to Home Assistant drops, the screen immediately shows "HA not connected"; if the app sends nothing for two rounds (about five minutes), it shows "ESP Screens not active". In both cases, control is blocked until data is received again.

You can save layouts while a screen is offline. The app sends them as soon as the screen comes back. The app must keep running for current tile data.

5. Updates without losing your settings

What changes?	What do you do?	What's kept?
Different entities, names, or order	Save in ESP Screens	Wi-Fi, keys, calibration
New management page/app version	App store → ESP Screen Manager → Update	All layouts in /data/screens.json
New screen feature/card	The Update button on the screen, or the Update automatically every night checkbox (manually: Firmware & USB → Wi-Fi / OTA)	Own YAML, keys, and CYD calibration; the app resends tiles

The device's own YAML references the firmware packages on main. On a new build, ESPHome fetches the latest published package and component code. So you don't replace your own YAML with a new downloaded file. Wi-Fi, name, and keys live outside the shared package and stay the same.

Make a Home Assistant backup before updates, including ESP Screen Manager and the device's own ESPHome configurations. Removing/reinstalling an app is not the same as updating; that can wipe the data folder. Keep the device name and the entity ID of Tile settings the same, so the existing layout stays linked.

For a newly supported card, update the app first, then the firmware. The maintainer keeps protocol and data migrations backward compatible; see RELEASING.md. To roll back, you can temporarily replace ref: main in your own YAML with an earlier release tag, without changing the keys.

If something doesn't work

• No screen in the list: check that the new Easy Setup firmware is running, the ESPHome integration is connected, and the Tile settings text entity isn't disabled. The old manual firmware doesn't publish that by default.
• Tiles show but no actions: grant the device permission for HA actions.
• Unavailable: check that the selected entity exists in HA and is available. A renamed entity ID needs to be chosen again.
• No OTA: check Wi-Fi/IP and the original OTA password. If needed, use the same own YAML over USB. Don't generate a new identity.
• Build fails: read the first error, check the ESPHome version and internet for GitHub/font downloads. If the Raspberry Pi is low on memory, temporarily use a more powerful computer to compile; the YAML stays the same.
• Migrating an existing manual screen: keep the old YAML and carry over the existing device name, API key, and OTA password into the new installation profile. Then choose the tiles in the app. The old fixed tile substitutions aren't automatically imported into the new management page.

HA Container without Supervisor has no App store. This installation guide targets Home Assistant OS; the development server is not a production route for a standalone public portal.

HA mechanisms used: Ingress, the internal HA API, and ESPHome packages.

Adjusting screen settings (from 0.1.2)

Update ESP Screen Manager to 0.1.2 and install the new firmware once via your existing ESPHome device → Install → Wirelessly. Keep your own YAML with Wi-Fi and keys. Then open the screen in ESP Screen Manager and expand Screen settings. After adjusting, click Save & send to screen. After this, changes to these settings don't need a new firmware flash.

Setting	Options	Default
Auto standby	On/off	On
Standby after	1–1440 minutes after the last touch	10 minutes
Normal brightness	5–100%	100%
Standby brightness	0–100%, capped at normal brightness	20%
Night mode	On/off; applies during standby	On
Night start/end	Hour and minute, can span midnight	22:00–07:00
Night brightness	0–100%, capped at normal brightness	10%
Show clock	On/off	On
Time format	24 or 12 hour, without AM/PM	24 hour
Return to page 1	Also closes detail menus on standby	Off
Swipe between pages	Native horizontal swipe, firmware 0.2.7+	Off
Guition rotation	0°, 90°, 180°, 270°, firmware 0.2.9+	0°

Night hours use the ESPHome device's timezone and the time from HA. Without a valid time, the screen uses the regular standby brightness; matching start and end times turn the night window off. At 0%, only the backlight turns off: this is not deep sleep and not a screensaver. The first tap wakes the screen without controlling a device.

The add-on stores everything per screen in its persistent data. The screen also stores the last received settings in preferences; ESPHome batches those write operations (normally up to a minute). So don't unplug the power right after saving. Existing CYD calibration, tiles, API, and OTA keys are preserved. An offline screen gets the changes as soon as it comes back. Regular HA status updates don't wake the screen and don't reset the standby timer.

With older firmware, the management page shows that an update is needed first. The tiles remain usable. Manual YAML profiles keep using their substitutions; to manage through this app, use the Easy Setup package.

The current Guition uses the native ST7701S configuration; see the hardware comparison. Settings and tile colors don't change panel timings. Physically check the display and touch.