Skip to content

Home Assistant

The Frameleaf integration for Home Assistant puts your library on your smart-home dashboards. It adds:

  • Sensors for how many photos and videos you have, when a phone last backed up, storage, Cloud Backup and things that need attention.
  • A picture for dashboards and photo frames: today’s memory, or one of your favourites.
  • A button that looks for new files in your library folders.
  • Frameleaf events that start automations, such as a notification when Cloud Backup fails or a Studio export finishes.

It reads from your own server over your home network. Nothing goes through Frameleaf Cloud.

Looking for Claude or ChatGPT instead? See Connect AI assistants.

  • Home Assistant 2025.1 or newer.
  • Home Assistant has to reach your Frameleaf server, normally on the same home network.
  • For sensors beyond your own photo and video counts, an API key. For storage, Cloud Backup, things to look at, the scan button and Frameleaf events, the key has to belong to an administrator.
  1. In Home Assistant, open HACS.
  2. Open the menu and choose Custom repositories.
  3. Add https://github.com/Frameleaf/frameleaf-app with the type Integration.
  4. Find Frameleaf in HACS and choose Download.
  5. Restart Home Assistant.
  1. Download the Frameleaf app source and open integrations/home-assistant/custom_components.
  2. Copy the frameleaf folder into the custom_components folder of your Home Assistant configuration. Make custom_components if it isn’t there.
  3. Restart Home Assistant.
  1. In Home Assistant, open Settings → Devices & services.
  2. A Frameleaf server on your network is found by itself and shows under Discovered. Choose Add. If it isn’t there, choose Add integration, search for Frameleaf, and type the address you use to open Frameleaf, such as http://frameleaf.local:2283.
  3. Under How to sign in, choose one of the two ways below.

Home Assistant asks to see your library and nothing more. It can’t change, share or delete anything.

  1. Choose Sign in through Frameleaf.
  2. Frameleaf’s Allow an app page opens. Sign in if you’re asked to, then choose Allow.
  3. Home Assistant says Frameleaf is connected.

Home Assistant then shows under Settings → Your sign-in & privacy → Connected apps in Frameleaf, where you can remove it at any time. After that, Home Assistant asks you to sign in again.

This way gives you the Photos and Videos sensors and the Picture.

Choose this for the rest of the sensors, the scan button and Frameleaf events.

  1. In Frameleaf, open Settings → Your sign-in & privacy → API keys and make a key. See API and CLI.
  2. In Home Assistant, choose Use an API key and paste the key.
  3. To start automations from Frameleaf, turn on Send Frameleaf events to Home Assistant. This needs an administrator’s key.

A key belongs to one account. Home Assistant shows that account’s library.

In Home Assistant Shows Which sign-in
Photos How many photos are in your library Either
Videos How many videos are in your library Either
Picture Today’s memory, or one of your favourites Either
Last phone backup When a phone last finished backing up API key
Storage used Space used on the server Administrator’s API key
Storage used (percent) How full the server’s storage is Administrator’s API key
Cloud Backup Backed up, Backing up, Waiting, Failed, Stopped or Not set up Administrator’s API key
Things to look at How many items Frameleaf says need attention Administrator’s API key
Look for new files A button that starts a scan of the library folders Administrator’s API key

Sensors refresh every five minutes.

The Picture shows a photo from today’s memory. When there’s no memory today, it shows one of your favourites. It changes about every ten minutes.

It only ever shows photos from your timeline. Locked, hidden, archived and trashed photos are never shown, and neither are videos.

To put it on a dashboard, add a Picture entity card and choose the Frameleaf Picture:

type: picture-entity
entity: image.frameleaf_picture
show_name: false
show_state: false

Your entity’s name may differ. Find it under Settings → Devices & services → Frameleaf.

With an administrator’s key and Send Frameleaf events to Home Assistant on, Frameleaf tells Home Assistant when one of these happens:

Event When
studio.export.completed A Studio export finished
cloud.backup.completed Cloud Backup finished
cloud.backup.failed Cloud Backup failed
clients.gallery.approved A client approved a gallery in Clients
cloud.job.completed A Frameleaf Cloud job finished

Home Assistant fires each one as frameleaf_event. Use it as a trigger:

automation:
- alias: Tell me when Cloud Backup fails
trigger:
- platform: event
event_type: frameleaf_event
event_data:
event: cloud.backup.failed
action:
- service: notify.notify
data:
title: Frameleaf
message: Cloud Backup failed. Open Frameleaf to see why.

Each event carries event, occurred_at, subject, detail and delivery_id. Leave out event_data to trigger on every Frameleaf event.

More ideas:

  • Flash a light when a long Studio export finishes.
  • Send a message when a client approves their gallery.
  • Show a warning card when Things to look at is above zero, or when Storage used (percent) passes 90.
  • Press Look for new files on a schedule after a camera card is copied to the server.

To send events, the integration adds one workflow in Frameleaf for each event, named Home Assistant: and the event. You can see them in Workflows. Removing the integration from Home Assistant removes them again.

Each message is signed with a secret that only your Frameleaf server and your Home Assistant know. Home Assistant ignores a message that isn’t signed, is more than five minutes old or was already received.

Home Assistant remembers the last 500 messages to catch repeats, and forgets them when it restarts. Write automations that are safe to run twice.

Frameleaf only sends events to secure (https) addresses unless you allow home addresses. If your Home Assistant is at an address such as http://homeassistant.local:8123, an administrator has to turn on Allow automations to call devices on my network in Frameleaf under Settings → Server name & welcome. Then reload the Frameleaf integration in Home Assistant so it can add its workflows.

In Home Assistant, open Settings → Devices & services → Frameleaf and delete it. Its workflows are removed from Frameleaf.

To stop Home Assistant from the Frameleaf side, remove it under Connected apps, or delete the API key it uses.

What you see What to do
Frameleaf could not be reached at this address Type the address you use to open Frameleaf in a browser, with http:// or https:// and the port. Check that Home Assistant is on the same network as the server.
Frameleaf did not accept this API key Copy the whole key, and check that it hasn’t been deleted under API keys.
This Frameleaf server does not let new apps connect themselves An administrator turned off Let new apps register themselves. Ask them to turn it on in Registered apps, or sign in with an API key.
That is a different Frameleaf account When signing in again, use the account you added the first time.
Sign in to Frameleaf again Home Assistant was removed under Connected apps, or its API key was deleted. Sign in again or paste a new key.
Storage, Cloud Backup or Things to look at are missing Those need an administrator’s API key. Sign in through Frameleaf only gives the photo and video counts and the picture.
No events arrive Check that you used an administrator’s key and turned on Send Frameleaf events to Home Assistant. If Home Assistant is on a home address, turn on Allow automations to call devices on my network, then reload the integration.
The picture never changes It changes about every ten minutes, and only when today’s memory or your favourites hold more than one photo that can be shown.
Frameleaf isn’t found by itself Choose Add integration and type the address. Discovery only works when both are on the same network.