Inkanva × Home Assistant

Your frame, part of your smart home.

Bring Inkanva into Home Assistant. Choose artwork, set your slideshow, and make your frame part of your everyday automations.

Set up the integration View on GitHub

Home Assistant 2026.9+ Device API key Cloud connection

01 / Get ready

A few things before you begin.

An Inkanva frame, already set up and connected to Wi-Fi.
Home Assistant 2026.9 or later.
Your frame’s device API key, available in the frame settings.
Internet access for both Home Assistant and your frame. The integration connects through the Inkanva cloud.

Keep your API key private. It gives access to your frame. Enter it in Home Assistant during setup.

02 / Install

Choose your installation method.

With HACS

If you already use HACS, add Inkanva as a custom repository.

Open HACS, open its menu, and choose Custom repositories.
Enter the repository URL below and select Integration as the type.
Find inkanva in HACS and download it.
Restart Home Assistant, then connect your frame.

Custom repository URL

https://github.com/galaxyguide/home-assistant-inkanva

Manual installation

Download inkanva-<version>.zip from the latest release.
Extract it into your Home Assistant configuration folder, alongside configuration.yaml.
Check that the folder contains custom_components/inkanva/manifest.json.
Restart Home Assistant, then continue below.

03 / Connect

Add your Inkanva frame.

In Home Assistant, go to Settings → Devices & services → Add integration.
Search for inkanva.
Enter your frame’s device API key and submit.
Open the newly added device to see its controls and status.

Have more than one frame? Repeat these steps for each one, using that frame’s own API key. Each frame has its own controls.

04 / Everyday use

Artwork and status, in one place.

Open your frame under Settings → Devices & services → inkanva. Add its controls and status to your Home Assistant dashboard for quick access.

Selected image: Choose a saved picture by its ID and filename.
Playback mode: Play pictures sequentially or in random order.
Slideshow interval: Set the time between pictures from 1 to 1,440 minutes. Set it to 0 to turn off automatic playback.
Refresh complete: Turns on when the frame confirms its screen has finished refreshing.
Battery & Charging: See the most recently reported battery level and charging status.
Last communication: Check when the frame last contacted the cloud.
Sleep interval: The frame’s reported sleep interval. Read-only and separate from the slideshow interval.
Reported online: The frame’s most recently reported connection status.

When will my picture appear?

Your frame may sleep between updates. A picture request is queued in the cloud and processed when the frame next connects, even if Reported online is off.

Selected image is the picture you requested. Refresh complete turns off after a new request and turns on once the screen has refreshed. Home Assistant checks status about once a minute, so confirmation may follow shortly after the screen changes.

05 / Automations

Make artwork part of your routine.

Use these actions in an automation or in Developer tools → Actions. For each Inkanva action, target your frame’s Selected image entity. Replace the example entity ID with the one shown for your frame.

Display a saved picture

Use the ID before the filename in Selected image. For example, 123: holiday.jpg has image ID 123.

YAML · Display image

action: inkanva.display_image
target:
  entity_id: select.living_room_selected_image
data:
  image_id: 123

Refresh the picture list

The list updates about every five minutes. Run this action to update it sooner after adding pictures elsewhere. It updates Home Assistant’s list and status without waking the frame or refreshing its screen.

YAML · Refresh image list

action: inkanva.refresh_images
target:
  entity_id: select.living_room_selected_image

Upload and display a new picture

The file must be available on the computer or container running Home Assistant. A file on the computer running your browser alone will not work.

Allow Home Assistant to read the image folder. Merge this into any existing homeassistant: and allowlist_external_dirs: settings in configuration.yaml, then restart Home Assistant.

homeassistant:
  allowlist_external_dirs:
    - /config/frame_images

Place your image in that folder, then run:

action: inkanva.upload_image
target:
  entity_id: select.living_room_selected_image
data:
  file_path: /config/frame_images/today.png
  name: today.png

Each upload adds a new picture and selects it for display. The maximum file size is 20 MiB. You can use raw base64 instead of file_path; supply exactly one and omit the data:image/...;base64, prefix. The decoded image must also fit within 20 MiB.

If an upload times out, refresh the picture list before retrying to avoid adding the same picture twice.

More examples in the automation guide

06 / Need a hand?

A few quick checks.

I can’t connect my frame.

Check that you copied the device API key correctly and that Home Assistant can access the internet. Confirm you are running Home Assistant 2026.9 or later and restarted it after installing the integration.

My API key has changed.

Open the Inkanva integration menu and choose Reconfigure to enter the replacement key for the same frame. Home Assistant will also prompt you if the saved key stops working.

My new picture hasn’t appeared.

Allow time for the frame to wake and connect. Check Last communication and Refresh complete to follow its progress. An accepted action means the request was received; the screen may update later.

A picture is missing from the list.

The picture list updates about every five minutes. Use the Refresh image list action to update it sooner. This changes the list in Home Assistant without changing the frame’s screen.

Still need help? Open an issue on GitHub with your Home Assistant version, integration version, and what happened. Remove API keys and other private information before sharing logs.