Max Gramser
3e959b3df9
Everything a user sees or reads is now English: both boards' labels, status replies and logs, the ESP Screens editor and Alerts cheatsheet, and the README and guides (docs/TILES.md, CALIBRATING.md, ACCEPTANCE.md and TROUBLESHOOTING.md replace the Dutch file names). Labels follow Home Assistant's own English names (Heat/Cool modes, Heating/Cooling actions, Away, Returning to dock, weather conditions), dates use English abbreviations and the top bar writes numbers the English way. Docs use HA 2026.9's menu names (Settings -> Apps, App store, Settings -> Tools). Unused legacy files (home-like.yaml, buttons.yaml, a.out) are removed. Firmware 0.2.34 names its entities in English. Home Assistant registers a renamed ESPHome entity under a new entity ID, so the inbox text.<screen>_tegelinstellingen becomes text.<screen>_tile_settings and the layout stored under the old ID would be lost. The manager now recognises the screen by its device, during a run or after a restart, and moves its layout and update history along; the Update button and the nightly round follow the screen through the rename. Screens that still run 0.2.33 or older keep working: both languages are matched. Main is the only release branch from now on. Tested on a Home Assistant Yellow (HA 2026.9.1) with both bench boards: see docs/TEST_RESULTS_0240.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
261 lines
15 KiB
Markdown
261 lines
15 KiB
Markdown
# 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](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](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](https://developers.home-assistant.io/docs/apps/presentation/),
|
||
[the internal HA API](https://developers.home-assistant.io/docs/apps/communication/), and
|
||
[ESPHome packages](https://esphome.io/components/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](GUITION_FACTORY_REFERENCE.md). Settings and
|
||
tile colors don't change panel timings. Physically check the display and touch.
|