Files

T

Max Gramser 3b15e7f7a3 Build the screens with ESPHome 2026.9 and keep its build memory in the app's own storage, give the CYD 94 KB more room, and stop a timer from counting one second too many (0.2.89)

The add-on ships ESPHome 2026.9.0: it builds an ESP32 with ESP-IDF itself
and keeps a compiler cache. firmware.py gives the CLI its own storage in
/data (ESPHOME_DATA_DIR /data/esphome, which the ESPHome Device Builder no
longer wipes on start; ESP-IDF and ccache in /data/idf, at most 1 GB;
compilers limited to the core count as PlatformIO ran them), removes the
unused PlatformIO once before the first ESP-IDF build, and leaves the new
folders out of backups.

Firmware 0.2.75: assertion_level SILENT in every board's esp32 block, the
core logs from INFO, and clock_parts() in runtime_model.h replaces sscanf.
timer_left() caps a running timer at its duration (the screen's clock runs
up to a second behind Home Assistant's). The packages keep min_version
2026.6.2, the top-level online_image and OTA passwords for new screens, so
an add-on or Device Builder that isn't updated yet keeps building every
screen; CI now builds both boards with the add-on's ESPHome and with
min_version. ESP-IDF's error names stay on, and build_flags stay under
platformio_options, because ESPHome 2026.9's LVGL reads only those.

tools/check.sh: 478 Python tests, 19/19 C++, editor; --firmware PASS with
ESPHome 2026.6.2 (CYD 87.7 %), 2026.8.1 (88.3 %) and 2026.9.0 (86.4 %,
was 91.5 %). Both bench screens OTA'd and watched for half an hour;
ESP Screens as a local add-on on the Yellow built both profiles
(CYD 1,037 s first build, 41 s unchanged). Details:
docs/TEST_RESULTS_0289.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-19 12:35:49 +02:00

5.2 KiB

Raw Blame History

ESP Screens with Home Assistant Container (Docker)

Home Assistant Container has no App store, so ESP Screen Manager can't be installed as an app there. This guide runs the same app as its own container next to Home Assistant, with the ESPHome CLI included. On Home Assistant OS, follow the normal installation instead.

This route is new. If something doesn't work on your setup, please open an issue.

What you need

Home Assistant Container on a Linux host (aarch64 or amd64) with host networking, as in the Home Assistant installation docs.
Docker with Compose on the same host.
The ESPHome integration in Home Assistant, to pair the screens. ESPHome Device Builder is optional: the ESPHome CLI is already in this image.

Install

Create a folder, for example esp-screens, and put docker/compose.yaml in it.
In Home Assistant, open your profile → Security → Long-lived access tokens and create a token, signed in as an administrator. Save only the token in a file named ha_token next to compose.yaml, readable for you only (chmod 600 ha_token).
Check two lines in compose.yaml:
- HA_API: http://127.0.0.1:8123/api works when Home Assistant runs on the same host on port 8123. Keep /api at the end.
- The ESPHome folder: ./esphome works as is. Already using ESPHome Device Builder? Use its folder instead, so both see the same device profiles.
Start it:
```
docker compose up -d --build
```
The first build downloads the official ESPHome image. docker compose logs -f shows Home Assistant connected once the token works.

Open ESP Screens

The page has no login of its own, so it only listens on 127.0.0.1:8099 of the Docker host. Don't make port 8099 reachable from your network without a login in front of it.

In the Home Assistant sidebar (recommended). Install hass_ingress from HACS, add this to configuration.yaml, and restart Home Assistant:

ingress:
  esp_screens:
    title: ESP Screens
    icon: mdi:monitor-dashboard
    require_admin: true
    url: http://127.0.0.1:8099

Home Assistant then handles the login, like the app panel on Home Assistant OS.

Through an SSH tunnel. From your computer:

ssh -L 8099:127.0.0.1:8099 you@docker-host

Then open http://localhost:8099. The Open Devices & services button only works in the sidebar panel; here, open Home Assistant yourself.

Using it

From here it works like the app: New screen installs a screen, you pair it under Settings → Devices & services in Home Assistant, and then choose the tiles. See the installation guide.

USB (Linux only): connect the screen, uncomment devices: in compose.yaml with its port (/dev/ttyUSB0 or /dev/ttyACM0), and run docker compose up -d again. Installs over Wi-Fi (OTA) and the nightly updates need nothing extra.
Without USB passthrough (app 0.2.68+): in New screen, choose Download · flash from your own computer. The container builds the firmware, and you put it on the screen with ESPHome Web in Chrome or Edge on the computer the screen is plugged into.
Backups: Home Assistant backups don't include this container. Keep a copy of data/screens.json and data/updates.json (layouts and update settings) and of the ESPHome folder. data/build, data/esphome, data/idf and data/platformio are caches.
Claude: Install for Claude Code is meant for the Claude Code app on Home Assistant OS. Use Download for claude.ai instead.
Camera images (Guition, app 0.2.66+): the screens load camera pictures, and from app 0.2.77 the album covers of the media card, from port 8098 of this host, on all its addresses, so keep that port open to the screens. The app uses Home Assistant's own LAN address; when the screens reach this host under another one, set SCREEN_CAMERA_URL (see below). The links are random and short-lived. docs/CAMERA.md

Updating

docker compose build --pull
docker compose up -d

This builds the latest version from main, the same one the App store offers. To stay on one version, replace main in compose.yaml with a release tag, such as screens-v0.2.49. After an update, ESP Screens shows per screen whether newer firmware is available, as usual.

Settings in compose.yaml

Setting	What it does
`SCREEN_DEV: "1"`	Runs the app outside the Supervisor: it reads the token from `HA_TOKEN_FILE` and serves its page on 127.0.0.1 only (camera images still on port 8098 for the screens)
`HA_API`	Home Assistant's address, ending in `/api`
`HA_TOKEN_FILE`	The token file inside the container (the `ha_token` secret)
`ESPHOME_CONFIG`	The ESPHome folder inside the container
`SCREEN_DATA`	Layouts, update settings, and build caches
`SCREEN_CAMERA_URL`	Optional: where screens load camera images, such as `http://192.168.1.20:8098`; by default Home Assistant's own LAN address
`SCREEN_CAMERA_PORT`	Optional: the camera image port instead of 8098

5.2 KiB Raw Blame History