ESPHome Manual Setup for EspFrame

For advanced users: install via the ESPHome dashboard instead of the web installer to control substitutions and YAML.

Create a configuration

Identify your display, then create esphome.yaml in the ESPHome dashboard. Use this example for V1:

substitutions:
  name: "immich-frame"
  friendly_name: "Espframe for Immich"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

packages:
  espframe:
    url: https://github.com/jtenniswood/espframe
    files: [devices/guition-esp32-p4-jc8012p4a1/packages.yaml]
    ref: main
    refresh: 1s

For your chosen hardware version, replace the files line as follows:

Hardware version	Package line
V2	files: [devices/guition-esp32-p4-jc8012p4a1-v2/packages.yaml]
V3	files: [devices/guition-esp32-p4-jc8012p4a1-v3/packages.yaml]

For V3, also use name: "immich-frame-10inch-v3" and friendly_name: "Espframe 10inch V3".

Add secrets.yaml with wifi_ssid and wifi_password, then:

esphome run esphome.yaml

First build takes a few minutes; OTA updates are faster.

Optional user-managed Home Assistant key

By default, Home Assistant 2026.8+ provisions a unique ESPHome API encryption key on first connection and the frame preserves it across OTA updates. Advanced users who want to manage that key in their ESPHome configuration can override the package configuration:

api:
  encryption:
    key: !secret api_encryption_key

Add a unique 32-byte base64 key as api_encryption_key in secrets.yaml; generate one with openssl rand -base64 32. Never reuse the Immich API key here. Changing this value later requires reconfiguring the ESPHome integration in Home Assistant.

ESPHome version

Use ESPHome 2026.10.2 for local builds.

Substitutions

Substitution	Default	Description
name	—	Device name (required)
friendly_name	—	Web UI display name (required)
immich_base_url	(empty)	Pre-fill Immich URL to skip setup
immich_api_key	(empty)	Pre-fill API key to skip setup
immich_slide_interval	15 seconds	Slideshow interval
immich_verify_ssl	false	Set true to verify TLS certificates
ntp_server_1	0.pool.ntp.org	First NTP server used for clock sync
ntp_server_2	1.pool.ntp.org	Second NTP server used for clock sync
ntp_server_3	2.pool.ntp.org	Third NTP server used for clock sync

Pre-filling Immich credentials

To skip the first-boot wizard, provide a valid Immich URL and API key in substitutions:

immich_base_url: "https://photos.example.com"
immich_api_key: !secret immich_api_key

Add immich_api_key to secrets.yaml. The URL can also be a direct local address such as http://192.168.1.30:2283. You can still change these later in the web UI.

Custom NTP servers

You can change NTP servers later in the EspFrame web settings under Clock. To pre-fill them before flashing, add substitutions:

ntp_server_1: "172.20.32.1"
ntp_server_2: "172.20.41.1"
ntp_server_3: "172.20.32.1"