Max Gramser
3b15e7f7a3
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>
113 lines
5.2 KiB
Markdown
113 lines
5.2 KiB
Markdown
# 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](../README.md#installing-from-home-assistant) instead.
|
|
|
|
This route is new. If something doesn't work on your setup, please
|
|
[open an issue](https://github.com/MaxGramser/homeassistant_espscreen/issues).
|
|
|
|
## 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
|
|
|
|
1. Create a folder, for example `esp-screens`, and put
|
|
[`docker/compose.yaml`](../docker/compose.yaml) in it.
|
|
2. 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`).
|
|
3. 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.
|
|
4. Start it:
|
|
|
|
```sh
|
|
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](https://github.com/lovelylain/hass_ingress) from HACS, add this to
|
|
`configuration.yaml`, and restart Home Assistant:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```sh
|
|
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](EASY_SETUP.md).
|
|
|
|
- **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](https://web.esphome.io) 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](CAMERA.md)
|
|
|
|
## Updating
|
|
|
|
```sh
|
|
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 |
|