mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-05-11 05:28:57 +00:00
215 lines
6.3 KiB
Markdown
215 lines
6.3 KiB
Markdown
---
|
|
title: "Blueprint schema"
|
|
description: "The schema for a valid blueprint."
|
|
---
|
|
|
|
The configuration schema of a blueprint consists of 2 parts:
|
|
|
|
- The blueprint high-level metadata, like its name and a description and
|
|
the input the blueprint needs from the user.
|
|
- The schema of the thing the blueprint describes.
|
|
|
|
The first part is referred to as the blueprint schema and contains mainly the
|
|
blueprint's metadata. The second part depends on what the blueprint is for.
|
|
|
|
For example, in the case of creating a blueprint for an automation, the full
|
|
schema for an [automation](/docs/automation/yaml/) applies.
|
|
|
|
This page is mainly set up to describe the configuration schema of the
|
|
blueprint metadata. Try our [blueprint tutorial](/docs/blueprint/tutorial/)
|
|
in case you are interested in creating your first blueprint.
|
|
|
|
## The blueprint schema
|
|
|
|
The only requirement for a blueprint is a name. In its most basic form,
|
|
a blueprint would look like:
|
|
|
|
```yaml
|
|
blueprint:
|
|
name: Example blueprint
|
|
domain: automation
|
|
```
|
|
|
|
And this is already a valid blueprint. But typically, one would need
|
|
more. For example, user inputs or a description to describe the blueprint's
|
|
functionality.
|
|
|
|
This is the full blueprint schema:
|
|
|
|
{% configuration %}
|
|
name:
|
|
description: The name of the blueprint. Keep this short and descriptive.
|
|
type: string
|
|
required: true
|
|
description:
|
|
description: >
|
|
The description of the blueprint. While optional, this field is highly
|
|
recommended. For example, to describe what the blueprint does, or tell more
|
|
about the options inputs of the blueprint provide. The description can
|
|
include [Markdown](https://commonmark.org/help/).
|
|
type: string
|
|
required: false
|
|
domain:
|
|
description: >
|
|
The domain name this blueprint provides a blueprint for. Currently, only
|
|
`automation` and `script` are supported.
|
|
type: string
|
|
required: true
|
|
author:
|
|
description: The name of the blueprint author.
|
|
type: string
|
|
required: false
|
|
homeassistant:
|
|
description: >
|
|
Home Assistant requirements to be able to use the blueprint successfully.
|
|
type: map
|
|
required: false
|
|
keys:
|
|
min_version:
|
|
description: >
|
|
Minimum required version of Home Assistant to use the blueprint (e.g.
|
|
`2022.4.0`. It is important to set this if the blueprint uses any features
|
|
introduced in recent releases to head off issues.
|
|
type: string
|
|
required: false
|
|
input:
|
|
description: >
|
|
A dictionary of defined user inputs. These are the input fields that the
|
|
consumer of your blueprint can provide using YAML definition, or via
|
|
a configuration form in the UI.
|
|
type: map
|
|
required: false
|
|
keys:
|
|
name:
|
|
description: The name of the input field.
|
|
type: string
|
|
required: false
|
|
description:
|
|
description: >
|
|
A short description of the input field. Keep this short and descriptive.
|
|
The description can include [Markdown](https://commonmark.org/help/).
|
|
type: string
|
|
required: false
|
|
selector:
|
|
description: >
|
|
The [selector](/docs/blueprint/selectors/) to use for this input. A
|
|
selector defines how the input is displayed in the frontend UI.
|
|
type: selector
|
|
required: false
|
|
default:
|
|
description: >
|
|
The default value of this input, in case the input is not provided
|
|
by the user of this blueprint.
|
|
type: any
|
|
required: false
|
|
{% endconfiguration %}
|
|
|
|
## Blueprint inputs
|
|
|
|
As written in the above schema, a blueprint can accept one (or multiple)
|
|
inputs from the blueprint consumer.
|
|
|
|
These inputs can be of any type (string, boolean, list, dictionary), can have
|
|
a default value and also provide a [selector](/docs/blueprint/selectors/) that
|
|
ensures a matching input field in the user interface.
|
|
|
|
Each input field can be referred to, outside of the blueprint metadata, using
|
|
the `!input` custom YAML tag.
|
|
|
|
The following example shows a minimal blueprint with a single input:
|
|
|
|
```yaml
|
|
blueprint:
|
|
name: Example blueprint
|
|
description: Example showing an input
|
|
input:
|
|
my_input:
|
|
name: Example input
|
|
```
|
|
|
|
In the above example, `my_input` is the identifier of the input, that can be
|
|
referred to later on using the `!input my_input` custom tag.
|
|
|
|
In this example, no `selector` was provided. In this case, if this blueprint
|
|
was used in the user interface, a text input field would be shown to the user.
|
|
|
|
A blueprint can have as many inputs as you like.
|
|
|
|
### Blueprint inputs in templates
|
|
|
|
The inputs are available as custom YAML tags, but not as template variables.
|
|
To use a blueprint input in a template, it first needs to be exposed as either
|
|
a [script level variable](/integrations/script/#configuration-variables) or in
|
|
a [variable script step](/docs/scripts/#variables).
|
|
|
|
```yaml
|
|
variables:
|
|
# Make input my_input available as a script level variable
|
|
my_input: !input my_input
|
|
```
|
|
|
|
## Example blueprints
|
|
|
|
The [built-in blueprints][blueprint-built-in]
|
|
are great examples to get a bit of a feeling of how blueprints work.
|
|
|
|
Here is the built-in motion light automation blueprint:
|
|
|
|
```yaml
|
|
blueprint:
|
|
name: Motion-activated Light
|
|
description: Turn on a light when motion is detected.
|
|
domain: automation
|
|
input:
|
|
motion_entity:
|
|
name: Motion Sensor
|
|
selector:
|
|
entity:
|
|
domain: binary_sensor
|
|
device_class: motion
|
|
light_target:
|
|
name: Light
|
|
selector:
|
|
target:
|
|
entity:
|
|
domain: light
|
|
no_motion_wait:
|
|
name: Wait time
|
|
description: Time to leave the light on after last motion is detected.
|
|
default: 120
|
|
selector:
|
|
number:
|
|
min: 0
|
|
max: 3600
|
|
unit_of_measurement: seconds
|
|
|
|
# If motion is detected within the delay,
|
|
# we restart the script.
|
|
mode: restart
|
|
max_exceeded: silent
|
|
|
|
trigger:
|
|
- platform: state
|
|
entity_id: !input motion_entity
|
|
from: "off"
|
|
to: "on"
|
|
|
|
action:
|
|
- service: light.turn_on
|
|
target: !input light_target
|
|
- wait_for_trigger:
|
|
platform: state
|
|
entity_id: !input motion_entity
|
|
from: "on"
|
|
to: "off"
|
|
- delay: !input no_motion_wait
|
|
- service: light.turn_off
|
|
target: !input light_target
|
|
```
|
|
|
|
Additional examples, provided by the community, can be found on the
|
|
[community forum][blueprint-forums].
|
|
|
|
[blueprint-built-in]: https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints
|
|
[blueprint-forums]: /get-blueprints
|