Allow integrations to provide built-in blueprints

Feature Requests
1

I initially posted this at Allow integrations to provide blueprints · home-assistant/architecture · Discussion #1246 · GitHub but I have moved it here as I don’t have the skills to implement

Idea

Integrations and helpers should be able to provide blueprints to their users. If the user’s installation satisfies the pre-requisite inputs and ouputs for the blueprint to function, the blueprint should appear in the list of available blueprints similar to the built-in blueprints motion_light.yaml and notify_leaving_zone.yaml.

Rationale

It is the stated aim of Home Assistant to be more accessible, and one of the currently perceived barriers is the complexity of writing one’s own automations and scripts. Upon adding an auto-discovered integration, it can be daunting or confusing to a user as to how the entities and services provided by the integration might be put to us. If implemented, a growing library of ‘official’ blueprints would gradually be made available to the user as they expand their configuration.

Implementation

This already seems to be partly implemented in the case of core/homeassistant/components/automation/blueprints at dev · home-assistant/core · GitHub, where the defined blueprints auto-populate /config
However I would add the following programmatic criteria to decide if the blueprint should be displayed in the UI at /config/blueprint/dashboard. Some of the logic for this already exists in #43321

  1. The integration is configured (this could be the prompt to run the process)
  2. At least one option is available for all input selectors
    • Unless the input is marked as optional in some way (not currently possible)
  3. All actions performed by the blueprint are available and have at least 1 valid target

Blueprints which satisfy 1 but not 2 and 3, could be shown in a collapsed ‘hidden’ pane within the blueprints page.

Foreseen issues

  1. There would have to be a robust policy about introducing breaking changes to blueprints
    • Ideally there would be a repairs infrastructure
    • This is already true of blueprints, and wouldn’t be specific to this use case
  2. Some blueprints might not have an obvious integration to which they belong and there is a risk of duplication of similar blueprints
    • For example a a blueprint which charges your Tesla when your Solar Edge inverter is generating excess could reasonably be provided by the Tesla or the Solar Edge integration.
    • Solution: Allow some degree of first mover advantage, otherwise the blueprint should belong to whichever integration has the most specific requirement. I.e a entity selector with a domain: filter or an action provided by an integration
  3. Clutter - some contributors or code owners may be tempted to produce a raft of useless or similar blueprints which clutter the UI
    • Solution: Apply a guideline for the number of blueprints expected per integration. Blueprints should only be approved if the use case is obvious and likely to be useful to a significant portion of integration users or there is already a proven demand for the blueprint on the forums.
  4. Testing: Ideally we should apply similar code coverage principles to blueprints with a test_blueprint.py that mocks entity states in order to test that blueprints function as desired.
  5. Blueprints without a home; browsing through the blueprint exchange reveals that many of the most popular blueprints would not have an obvious integration that they would belong to and so would not have a way to become an ‘official’ blueprint.

Related:

  1. WTH can't integrations ship a set of blueprints? 58 upvotes (Includes a vote of support from frenck)
  2. Blueprint Store with Official Blueprints

Examples

Integrations which are providing semi-offical blueprints through other channels:

  1. GitHub - music-assistant/voice-support: Music Assistant blueprints
2

Sounds like a lot of work. Who is going to do it? :grin:

1 Like
3

I don’t actually think its a huge amount of work. The infrastructure to import blueprints from integration folders into /config already exists in /components/automations/, I don’t know how complex it would be to perform the filtering logic.

Then the blueprints and their tests would be slowly added by contributors over time and released in the usual release cycle.

4

Hello HarvsG,

So, a bit confused…
First, everything in the

section applies to all blueprints anyway, so really not related.

Second, Example any integration that would supply a blueprint, that blueprint would likely only do one or 2 of the things that the integration can do, so what is the point exactly? There will be constant, and I mean constant request to add this tweak ot adjust that so it turns on the thing only what this other condition. Trust me, as a person that has over 20 blueprints available in the exchange, this is daunting. Core will not put up with that many updates, Implementation is up to the user, not the core function. The docs and the examples are for that.
And the couple of example blueprints that are in core as, examples, are even vulnerable to this. I have had to update those to fix problems when other core functions changed.

Third, if you are talking about Custom Integrations, they can already do this. Nothing stopping them other than the problems I already mentioned. Only a couple do, such as MA that did this as part of their Custom Integration that is currently still active I think next to the core version.

Finally, the current path is to make the Automation and Script GUI Editors as accessible as possible, so the user can build anything they want. Again I remind you that implementation is a user function because there are literally millions of ways to do things and are not core functions of the software, so this is not the path. Look to others to provide the tricky implementations for the new users via the current blueprint system… It seems to be working fine,and I don’t see it changing.

Eventually if you want that special tweak, you are going to have to put a little effort in and learn how to make your way around no matter what.

1 Like