Home Assistant Blueprints

Aivi provides a set of Home Assistant blueprints that help you connect Home Assistant devices and automations to Live Activities and persistent widgets. They handle the “plumbing” - watching entities for changes and calling the right rest_command with the right payload - so you can get a working Live Activity or widget in a few clicks.

Prerequisites

The Live Activity blueprints call rest_command.update_live_activity and the widget blueprints call rest_command.update_widget. Add both to your Home Assistant configuration:

1. Open your Home Assistant configuration.yaml.

2. Add the rest_command entries below:

   rest_command:
     update_live_activity:
       url: 'https://api.getaivi.app/activity/{{ slug }}'
       method: PATCH
       headers:
         content-type: application/json
         authorization: Token [token]
       payload: '{{ payload }}'
     update_widget:
       url: 'https://api.getaivi.app/widget/{{ slug }}'
       method: PATCH
       headers:
         content-type: application/json
         authorization: Token [token]
       payload: '{{ payload }}'

   Note

   Replace [token] with your Aivi API token.

3. Reload your Home Assistant configuration.

Versioning

Blueprints are versioned using a suffix like -v1 (for example, timer-v1).

• Stability: Updates within the same major version (e.g. v1) are intended to be backwards compatible.
• Breaking changes: If we need to change inputs or behavior in a breaking way, we’ll publish a new major version (e.g. -v2) alongside the old one so existing automations keep working.
• Upgrades: To move to a new major version, import the newer blueprint and reselect your entities/inputs in the automation editor (Home Assistant does not auto-migrate blueprint input mappings across breaking changes).

Live Activity blueprints

These blueprints drive Live Activities through rest_command.update_live_activity.

Progress: Simple (from sensors)

Version v1

Drives a simple progress bar from sensors. Use this when your device exposes:

• A binary “running” entity (on/off)
• A progress sensor (0–100)
• Optionally, an ETA sensor (timestamp or duration) and/or a human-readable state sensor (“Washing”, “Drying”, …)

Progress: Segmented (from sensors)

Version v1

Drives a segmented progress bar from sensors. Same inputs as the simple blueprint, but lets you define up to 4 labeled segments with individual colors, track patterns, and a display mode (split or layered).

Progress: Timer (from a timer helper)

Version v1

Drives a simple progress bar from a Home Assistant timer. Automatically synchronizes the Live Activity state with the timer’s progress, and supports pausing, resuming, and cancelling.

Monitor

Version v1

Use this when you want to drive the Monitor template from sensors or templates. It supports optional headers/footers, custom value colors, formatters, and per-column visibility conditions, with an optional set of custom triggers for templated fields.

Widget blueprints

One blueprint per widget template. Each one watches your sensors and calls rest_command.update_widget when they change, and they all share the same conveniences: an SF Symbols icon with full customization, an accent color, an optional tap URL, and an optional staleness threshold (stale_after). Updates are skipped while a required sensor is unavailable.

Note

The Battery, List, Budget, and Energy blueprints use row-based inputs and require Home Assistant 2025.7 or newer; the rest work on 2024.10+. Because automations cannot trigger on entities picked inside rows, these four also have a “Watched entities” input: add the entities your rows reference so the automation fires when they change.

Status widget

Version v1

Keeps a Status widget in sync with your sensors: a hero reading and a supporting state line.

Progress widget

Version v1

Drives a Progress widget: a live bar or self-advancing countdown with an optional state line.

Gauge widget

Version v1

Puts a numeric sensor on a Gauge widget’s dial.

Battery widget

Version v1

Tracks up to eight battery sensors on a Battery widget. Device names default to each sensor’s friendly name, with any trailing “battery” stripped.

Budget widget

Version v1

Keeps a Budget widget current with a top-level budget and up to six category breakdowns.

Trend widget

Version v1

Feeds a Trend widget with a current reading and its recent history sparkline.

Countdown widget

Version v1

Aims a Countdown widget at a timestamp from a sensor; the countdown then ticks on-device.

List widget

Version v1

Fills a List widget with up to eight labeled rows from arbitrary entities.

Prices widget

Version v1

Publishes a price series to a Prices widget, which keeps the current period highlighted on its own.

Energy widget

Version v1

Wires solar, grid, battery, and home power sensors into an Energy widget, with up to three named generation sources.

Legacy blueprints

These blueprints drive the legacy Generic template. They continue to work, but we recommend using the Progress blueprints above for new automations.

Generic: Progress + ETA (from sensors)

Version v1

Drives the legacy Generic template from sensors. See Progress: Simple for the recommended replacement.

Generic: Timer (from a timer helper)

Version v1

Drives the legacy Generic template from a timer helper. See Progress: Timer for the recommended replacement.

Source code

The source code for all blueprints is available on GitHub at getaivi/ha-blueprints.