Blueprints for template entities

[tetele]

PR here home-assistant/core#126971

Context

Template entities (especially sensors and binary_sensors, but not only them) would greatly benefit from being either instantiated multiple times and/or from being shared among users. Here are a few use cases:

• having a room occupancy template binary sensor which has the same logic behind it, but relies on different room-specific sensors (e.g. motion, door) for each room that it would need to be instantiated into
• having a "recipe" to create a template gate entity from 2/3 buttons/switches for opening, closing and, optionally, stopping . If those buttons or switches are available for a user, the gate definition is pretty much the same, except for (maybe) a time it takes to open/close the gate
• turning a computer into a template switch for turning it on and off using wakeup-on-lan and a hibernate/shutdown command sent through a certain integration could benefit the developer of the integration, who could provide this functionality out of the box to their users

Proposal

Allow blueprints for template entities, which can be shared using the same mechanism as blueprints for automations and scripts. These blueprints could then be instantiated by populating input fields, each instance creating an entity.

Blueprints could be shared among users just as automation or script blueprints and they could be instantiated multiple times in a HA server. More over, the re-import blueprint functionality should work out of the box for these blueprints, with the same caveats as for other types of blueprints (i.e. potential breaking changes could be fetched upon re-import).

Example config

#/config/blueprints/template/simple_invert.yaml
blueprint:
  name: Invert a binary sensor
  description: Creates a binary_sensor which holds the inverted value of a reference binary_sensor
  domain: template
  source_url: http://example.com # used for updates
  input:
    original_entity:
      name: Binary sensor to be inverted
      description: The binary_sensor which needs to have its value inverted
      selector:
        entity:
          domain: binary_sensor
variables:
  original_entity: !input original_entity
binary_sensor:
  state: >
    {% if states(original_entity) == 'on' %}
      off
    {% elif states(original_entity) == 'off' %}
      on
    {% else %}
      {{ states(original_entity) }}
    {% endif %}
  # delay_on: not_used in this example
  # delay_off: not_used in this example
  # auto_off: not_used in this example
  availability: "{{ states(original_entity) not in ('unknown', 'unavailable') }}"

#/config/configuration.yaml
...
template:
  - use_blueprint:
      path: simple_invert.yaml
      input:
        original_entity: binary_sensor.foo
    name: Inverted foo
    unique_id: inverted_binary_sensor_foo
  - use_blueprint:
      path: simple_invert.yaml
      input:
        original_entity: binary_sensor.bar
    name: Inverted bar
    unique_id: inverted_binary_sensor_bar

[Jc2k]

I certainly have a bunch of template sensors that would benefit from something like this. I guess they'd fall under occupancy logic.

I need to create one timer and 2 sensors per instance of this logic, and a couple of automations on top.

[Petro31]

I have about 80 that would fall under this. Just thinking about the logictech harmony switch deprecation. The blue print would make the transition to template switches a breeze. The only issue I see is that it would need to support the legacy template platforms as well as the template integration.

[SirGoodenough]

I like the idea a lot. Templates are quite intense and scary for the gui people we are attracting now, and I would love to be able to help people with this in a meaningful way.
To allow them to import a template blueprint and then just call it easier than they can with custom template macros now would lower the bar and make a lot of complex functions (that many seem to want/need now) accessible.

[SirGoodenough]

People are afraid of Templates. They can be daunting for sure. I would love to be able to provide canned examples for people to just use or as happens now with blueprints, to copy and tweak to their own uses.
Please make this happen.

[dinki]

This would be ideal for the project I am working on. I am creating a template sensor per visual satellite device. I can see this being intimidating for new users so I've started to look at creating an extension just to create these devices. This proposed blueprint would make creating these really easy.

[MartinHjelmare]

We've discussed this proposal in the Core team, and decided to approve it. @tetele I'll review the PR when it's up. 👍

[tetele]

Thanks, Martin! I'll try to find the time to work on it.

[tetele]

First draft here home-assistant/core#126971

[tetele]

Does anyone want to help out with the frontend for this? Should that be a separate architectural discussion?

I'm thinking including the template blueprints in https://my.home-assistant.io/redirect/blueprints/ (and possibly moving that section separately, since it would no longer pertain only to automations and scripts), adding the "filter by blueprint" functionality in the helpers dashboard and whatever else I couldn't think of atm.

Not sure if the config flow for setting up new blueprint-based template entities in the UI needs any frontend work, but that would need to be tackled as well, if it is indeed needed.

[tetele]

My PR currently doesn't have a config flow 😅

I was hoping to get some feedback on the implementation as a whole and then, if it's passable, to add the config flow.

[MartinHjelmare]

Right. It's good to keep the PR scope small. We can tackle the config flow in the next PR. I'll review the open PR once more. I think it was good, the first time I read it.

[tetele]

I've tried creating a new PR with a config_flow for creating template entities based on blueprints, but too many pieces of the puzzle are missing:

• there is no blueprint selector
• all labels in config flows rely on translation keys, so i can't use blueprint input names and descriptions in the form

I guess it's YAML-only for now 🥺

[heinemannj]

A couple of questions to this approach:

Will template trigger and their action variables also work?

template:
  - trigger:
      - platform: time_pattern
        minutes: "/1"
    action:
      - variables:
          var: >-
            {% from '032-emhass.jinja' import globalVariables %}
            {{ globalVariables()|from_json }}
          data_update: "{{ states(var.epexspot_data_update) }}"
          last_update: "{{ state_attr(var.epexspot_data_update, 'last_update') }}"
          next_poll_time: "{{ state_attr(var.epexspot_data_update, 'next_poll_time') }}"
          data: "{{ state_attr(var.epexspot_net_price, 'data') }}"
          APIUpdate: >-
            {% from '032-epexspot.jinja' import APIUpdate %}
            {{ APIUpdate(data_update, last_update, next_poll_time, data)|from_json }}
    binary_sensor:
      - name: "epex_spot_data_update"
        unique_id: epex_spot_data_update
        icon: mdi:clock
        state: >-
          {{ APIUpdate.tomorrow_data_available }}
        attributes:
          last_data: "{{ APIUpdate.last_data }}"
          last_api_update: "{{ APIUpdate.last_update }}"
          next_poll_time: "{{ APIUpdate.next_poll_time }}"
          last_updated: "{{ now().isoformat() }}"

{%- macro globalVariables() %}
    {{- {
            'epexspot_net_price': 'sensor.epex_spot_data_net_price',
            'epexspot_data_update': 'binary_sensor.epex_spot_data_update'
        }|to_json -}}
{%- endmacro %}

[HarvsG]

• all labels in config flows rely on translation keys, so i can't use blueprint input names and descriptions in the form

strings.json supports placeholders which can then be populated via the description_placeholders argument in async_show_form() This might help?

[rvalitov]

It's a great work! I'm waiting when this feature will go from RC to release. Meanwhile I try to understand how to make the sample blueprint work in case when my configuration is split into multiple files. I see that in the sample blueprint yaml the blueprint and the binary_sensor sections are on the same level. It's not a mistake? It means I should split them into multiple files?

[tetele]

I see that in the sample blueprint yaml the blueprint and the binary_sensor sections are on the same level. It's not a mistake?

Why do you think it's a mistake? If you look at blueprints for automations and scripts, you'll see they follow the same pattern.

Each blueprint can contain a single entity (e.g. one template binary sensor), so that you can instantiate each blueprint as many times as you want without creating unwanted entities.

[rainwoodman]

Looks like switch is still using the 'platform: template' syntax, and thus not supported by this PR?

[tetele]

This is an architectural discussion, not a PR. You may want to watch this PR for what you're interested in