Files

T

Max Gramser d60a0f122b Show who is at the door: camera images on the Guition (0.2.66)

An alert from esp_screens_show_alert takes a `camera` (a camera.* or image.* entity): a Guition with firmware
0.2.57 shows that moment's picture across the top of the card, and a tap opens the camera full screen. A camera
or image tile opens the same full-screen view, refreshed every four seconds at a steady pace.

ESP Screen Manager fetches the snapshot with its own access, sizes it for the screen and serves a 24-bit BMP
under a random, short-lived link on port 8098; the screen loads it with ESPHome's online_image and holds no
Home Assistant token. BMP because ESPHome decodes it per chunk, where a full-screen JPEG held the loop 0.6 s.
The CYD keeps its alerts without the picture and gets no camera tiles.

The Guition also builds with ESPHome 2026.8+ again: backlight_fade.h derived from ESPHome's LEDC output, which
2026.8 made final, so the backlight now dims through ESPHome's own light transition.

Tested on the bench boards and a local add-on on the Home Assistant Yellow; docs/TEST_RESULTS_0266.md.

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

2026-09-17 15:31:11 +02:00

4.9 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: Settings → 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.
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 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 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

4.9 KiB Raw Blame History