Skip to content

Home Assistant Integration

ant1fr edited this page Nov 19, 2026 · 3 revisions

Home Assistant Integration

Smart Frame Engine talks to Home Assistant over plain REST, so it works today with rest_command and automations. A dedicated integration is planned (see below).

Contract and compatibility

Anything that talks to the engine (these REST commands, the planned dedicated integration, Node-RED, scripts) should rely on the versioned API Contract and openapi.json: they are the single source of truth for endpoints, request and response shapes, authentication and errors.

  • Pre-flight check. GET /api/health needs no credentials. Compare api_version and min_api_version with the contract your client implements, and read capabilities to enable optional features (for example ambient_context, family_mode, title_card).
  • Discovery. The engine advertises _smartframe._tcp.local. (needs host networking in Docker). The TXT record carries version, api_version, min_api_version, path and auth, so an incompatible engine can be rejected before connecting. The capability list comes from /api/health.

Today: REST commands and automations

  1. Camera (optional). Settings → Devices & services → Add integration → Generic Camera: still image URL http://<engine>:8080/api/current.jpg. It works without a key while PUBLIC_IMAGE_ENDPOINTS=true.
  2. API key. If ADMIN_PASSWORD or APP_API_KEY is set, store the key in secrets.yaml (smart_frame_api_key) and send it as X-API-Key.
  3. Context from presence and weather. POST /api/context tells the engine who is home, the weather, the season or that guests are over, each with a lifetime (see the API Reference examples).
  4. TV posters and now-playing covers. See the automations below.

The engine must be able to reach Home Assistant to download entity_picture images.

Automations: TV and music

The app must be able to reach Home Assistant to download entity_picture (add its host to URL_ALLOWLIST when BLOCK_PRIVATE_URLS=true). Replace media_player.living_room and http://homeassistant.lan:8123 with yours. Picture URLs embed short-lived access tokens; the app never writes them to its logs.

rest_command:
  frame_now_playing:
    url: http://smart-frame.lan:8080/api/display/now-playing
    method: POST
    content_type: "application/json; charset=utf-8"
    timeout: 30
    headers:
      X-API-Key: !secret smart_frame_api_key   # when APP_API_KEY or ADMIN_PASSWORD is set
    payload: >-
      {% set p = 'media_player.living_room' %}
      {% set pic = state_attr(p, 'entity_picture') %}
      {{ {
        "title": state_attr(p, 'media_title'),
        "artist": state_attr(p, 'media_artist') or 'Unknown artist',
        "album": state_attr(p, 'media_album_name'),
        "artwork_url": ('http://homeassistant.lan:8123' ~ pic) if pic else none,
        "duration_seconds": state_attr(p, 'media_duration'),
        "position_seconds": state_attr(p, 'media_position')
      } | to_json }}
  frame_tv_poster:
    url: http://smart-frame.lan:8080/api/display/tmdb
    method: POST
    content_type: "application/json; charset=utf-8"
    timeout: 30
    headers:
      X-API-Key: !secret smart_frame_api_key
    payload: >-
      {% set p = 'media_player.living_room' %}
      {% set pic = state_attr(p, 'entity_picture') %}
      {% set series = state_attr(p, 'media_series_title') %}
      {{ {
        "query": series or state_attr(p, 'media_title'),
        "media_type": 'tv' if series else 'movie',
        "season": state_attr(p, 'media_season') if series else none,
        "fallback_url": ('http://homeassistant.lan:8123' ~ pic) if pic else none,
        "ttl_minutes": [((state_attr(p, 'media_duration') or 7200) / 60) | int + 15, 1440] | min
      } | to_json }}
  frame_cancel_ephemeral:
    url: http://smart-frame.lan:8080/api/queue/ephemeral
    method: DELETE
    headers:
      X-API-Key: !secret smart_frame_api_key

automation:
  - alias: Frame - now playing
    mode: queued
    trigger:
      - platform: state
        entity_id: media_player.living_room
        to: playing
      - platform: state
        entity_id: media_player.living_room
        attribute: media_title
    condition:
      - condition: state
        entity_id: media_player.living_room
        state: playing
    action:
      - choose:
          - conditions: "{{ state_attr('media_player.living_room', 'media_content_type') == 'music' }}"
            sequence:
              - service: rest_command.frame_now_playing
          - conditions: "{{ state_attr('media_player.living_room', 'media_content_type') in ['movie', 'tvshow', 'episode'] }}"
            sequence:
              - service: rest_command.frame_tv_poster
  - alias: Frame - playback stopped
    trigger:
      - platform: state
        entity_id: media_player.living_room
        from: playing
        for: "00:02:00"   # ignore short pauses
    action:
      - service: rest_command.frame_cancel_ephemeral

The now-playing call is deduplicated, so the media_title trigger only refreshes the frame when the album changes (every track with the title printed, if you enable show_track_title). A deep-sleeping frame wakes up to the right picture: covers whose song has ended are dropped from the queue, and the previous photo comes back.

Zeroconf / mDNS discovery

With ZEROCONF_ENABLED=true (default) the engine advertises _smartframe._tcp.local. with TXT records version, path (ROOT_PATH, / when empty) and auth (open, key or password). Any error is logged and ignored. Docker's default bridge network drops multicast, so run the container with network_mode: host to be discoverable (see Installation and Deployment).

The dedicated integration (planned)

A Home Assistant custom integration, Smart-Frame-Engine-HA, is on the roadmap: it would discover the engine through the Zeroconf service above, expose the frame and engine state as entities and offer the actions as services, installable through HACS. It does not exist yet: until then, add the engine by its URL with the REST commands on this page.


Home · Report an issue · Roadmap

Clone this wiki locally