# Home Assistant

Source: https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/using/connect-ai-agents/).

## Before you start

- 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](https://frameleaf.app/docs/admin/api-and-cli/). For storage, Cloud Backup, things to look at, the scan button and Frameleaf events, the key has to belong to an administrator.

## Install the integration

### With HACS

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.

### By hand

1. Download the [Frameleaf app source](https://github.com/Frameleaf/frameleaf-app) 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.

## Add Frameleaf

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.

### Sign in through Frameleaf (recommended)

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**.

### Use an API key

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](https://frameleaf.app/docs/admin/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.

## What you get

| 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.

## A picture for dashboards and photo frames

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**:

```yaml
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**.

## Frameleaf events

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:

```yaml
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.

### How events get there

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](https://frameleaf.app/docs/admin/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.

### If Home Assistant is on a home address

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.

## Remove Frameleaf from Home Assistant

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.

## If something isn't working

| 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](https://frameleaf.app/docs/admin/connected-apps/#for-administrators), 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. |
