Repository navigation
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).
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/healthneeds no credentials. Compareapi_versionandmin_api_versionwith the contract your client implements, and readcapabilitiesto enable optional features (for exampleambient_context,family_mode,title_card). -
Identity.
/api/healthalso returnsinstance_id, a stable random UUID kept in the data volume: use it as the unique key of an engine, not its address.instance_nameis the readable name (INSTANCE_NAMEto set it). -
Discovery. The engine advertises
_smartframe._tcp.local.(needs host networking in Docker). The service name is the engine's uniqueinstance_name(so several engines can share a network) and the TXT record carriesversion,api_version,min_api_version,instance_id,pathandauth, so an incompatible engine can be rejected before connecting. The capability list comes from/api/health.
-
Camera (optional). Settings → Devices & services → Add integration → Generic Camera:
still image URL
http://<engine>:8080/api/current.jpg. It works without a key whilePUBLIC_IMAGE_ENDPOINTS=true. -
API key. If
ADMIN_PASSWORDorAPP_API_KEYis set, store the key insecrets.yaml(smart_frame_api_key) and send it asX-API-Key. -
Context from presence and weather.
POST /api/contexttells the engine who is home, the weather, the season or that guests are over, each with a lifetime (see the API Reference examples). - TV posters and now-playing covers. See the automations below.
The engine must be able to reach Home Assistant to download entity_picture images.
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_ephemeralThe 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.
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).
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.