Master Reusable Automation Patterns: A Home Assistant Blueprint Guide

Home Assistant is renowned for its flexibility and powerful automation engine. However, as your smart home grows, managing numerous similar automations can become repetitive and time-consuming. This is where Blueprints come in.

What Are Home Assistant Blueprints?

Blueprints are pre-defined automation or script templates that you can easily configure and reuse without writing complex YAML code from scratch each time. Think of them as recipes for common smart home tasks. They abstract away the underlying logic, allowing you to quickly create instances tailored to specific devices or situations.

For example, instead of writing the YAML for a motion-activated light automation for every single motion sensor and light combination in your house, you can create or use a single Blueprint. Then, for each instance (e.g., Bathroom Light with Bathroom Motion Sensor, Hallway Light with Hallway Motion Sensor), you simply select the specific devices and perhaps configure a few parameters like the off delay.

Why Use Blueprints?

• Reusability: Define a pattern once and apply it multiple times.
• Simplicity: Create complex automations with a user-friendly configuration form.
• Shareability: Easily share your useful automation patterns with others or use Blueprints created by the community.
• Maintainability: Updates to the core logic of a Blueprint can potentially benefit all instances created from it (though be cautious with breaking changes).

Anatomy of a Blueprint

A Blueprint is essentially a YAML file with a specific structure. Let's break down the key components:

blueprint:
  name: My Awesome Blueprint
  description: This blueprint does something cool.
  domain: automation # or script

  # Input variables that the user configures when creating an instance
  input:
    my_device:
      name: Select a Device
      selector:
        device: # Use selectors to guide user input
    my_time:
      name: Delay Time (minutes)
      default: 5
      selector:
        number:
          min: 1
          max: 60
          unit_of_measurement: minutes
          mode: slider # or box

# The core logic of the automation/script, referencing the input variables
trigger:
  # Define triggers using the input variables (e.g., trigger when device state changes)
  - platform: state
    entity_id: !input my_device
    to: 'on' # Example trigger

condition:
  # Optional: Define conditions using input variables
  - condition: time
    after: 'sunset'

action:
  # Define actions using input variables and potentially other entities
  - service: light.turn_on
    target:
      entity_id: !input another_entity # Example using a different input type
  - delay: '{{ !input my_time | multiply(60) | int }}' # Example using an input in a template
  - service: light.turn_off
    target:
      entity_id: !input another_entity

• blueprint: Contains metadata about the blueprint (name, description, domain).
• input: Defines the variables (parameters) that the user needs to provide when setting up an automation/script from this blueprint. You define a name, description, default value (optional), and a selector which dictates the type of input control (e.g., device picker, entity picker, number slider, text field). Using selectors is crucial for a user-friendly experience.
• trigger, condition, action: These are the standard components of Home Assistant automations/scripts. Within these sections, you reference the defined input variables using the !input <variable_name> syntax. You can also use Jinja2 templates to process input values, as shown in the delay example.

Using Existing Blueprints

Home Assistant provides a Blueprints Exchange on its community forum, and many integrations and add-ons also provide their own blueprints. You can add them in a couple of ways:

Adding from a URL

1. Go to Settings > Automations & Scenes.
2. Select the 'Blueprints' tab.
3. Click the 'Import Blueprint' button (bottom right).
4. Paste the URL of the blueprint (usually a raw YAML file link, often found in community posts or GitHub repositories).
5. Click 'Preview Blueprint' and then 'Import Blueprint'.

Using the Community Store (if available via HACS or other means)

Some community add-ons like HACS (Home Assistant Community Store) offer a browsing interface for blueprints. Check their documentation for details if you use such tools.

Creating an Automation from a Blueprint

1. Once a blueprint is imported, go back to the 'Blueprints' tab.
2. Click on the blueprint you want to use.
3. Click the 'Create Automation' button.
4. A configuration form will appear, showing the inputs defined in the blueprint. Fill in the required fields (e.g., select your specific device, set the delay time).
5. Give your new automation a name.
6. Click 'Save'.

You now have a new automation instance based on the blueprint, configured for your specific needs!

Creating Your Own Blueprint

Writing your own blueprint requires a bit more YAML knowledge, but it's a powerful way to encapsulate your custom logic for reuse.

Steps to Create a Blueprint:

1. Identify the pattern: Think of an automation or script structure you use frequently or plan to use with different entities/devices. A common example is 'motion turns on light, turns off after delay'.
2. Write the core automation/script YAML: Draft the automation or script as you normally would, using placeholder entity/device IDs for the parts you want to make configurable.
3. Convert to Blueprint structure: Wrap your YAML in the blueprint structure described above. Replace the placeholder entity/device IDs with !input <variable_name>.
4. Define the input variables: For each !input you used, define an entry in the input section. Give it a descriptive name, optional default value, and a suitable selector (device:, entity:, area:, number:, text:, boolean:, select:, etc.). Selectors are key to making your blueprint easy to use. For devices, the selector: device: is often the most flexible as it allows picking a device, and the blueprint instance can then target entities within that device using target: { device_id: !input my_device } or reference specific entity types within the device.
5. Save the Blueprint: Save your YAML file in the <config_directory>/blueprints/<domain>/<your_blueprint_name>.yaml directory. For automations, the domain is automation. For scripts, it's script. Example path: /config/blueprints/automation/my_motion_light.yaml. You might need to create the blueprints and automation/script subdirectories.
6. Reload Blueprints: Go to Settings > System > Reload > Automations & Blueprints. Your new blueprint should now appear in the Blueprints tab.
7. Test Thoroughly: Create an automation instance from your blueprint and test it with different configurations and devices to ensure it works as expected.

Example: Simple Motion-Activated Light Blueprint

Let's create a blueprint that turns on a light when motion is detected and turns it off after a configurable delay.

blueprint:
  name: Simple Motion Light
  description: Turns on a light when motion is detected and turns it off after a delay.
  domain: automation

  input:
    motion_sensor:
      name: Motion Sensor
      description: The motion sensor entity to use.
      selector:
        entity:
          domain: binary_sensor
          device_class: motion # Filter to motion sensors
    target_light:
      name: Target Light
      description: The light entity to turn on.
      selector:
        entity:
          domain: light # Filter to light entities
    delay_minutes:
      name: Off Delay (minutes)
      description: Time in minutes before turning the light off after motion stops.
      default: 5
      selector:
        number:
          min: 1
          max: 120
          unit_of_measurement: minutes
          mode: slider

trigger:
  - platform: state
    entity_id: !input motion_sensor
    from: 'off'
    to: 'on'

action:
  - alias: "Turn on the light"
    service: light.turn_on
    target:
      entity_id: !input target_light
  - alias: "Wait for motion to stop plus delay"
    wait_for_trigger:
      - platform: state
        entity_id: !input motion_sensor
        from: 'on'
        to: 'off'
  - alias: "Apply the delay"
    delay: '{{ !input delay_minutes | multiply(60) | int }}'
  - alias: "Turn off the light"
    service: light.turn_off
    target:
      entity_id: !input target_light
mode: restart # Ensures that detecting motion again resets the timer

Save this as /config/blueprints/automation/simple_motion_light.yaml, reload automations/blueprints, and you can now create motion-activated light automations by simply picking the sensor, the light, and setting the delay from a form!

Device Integration Tips with Blueprints (Using Selectors)

Making your blueprints flexible across different devices and entities is crucial for reusability. Selectors in the input section are your primary tool for this.

• selector: entity:: Allows the user to pick a specific entity. You can filter by domain or even device_class.
• selector: device:: Allows the user to pick a device. This is often more powerful than picking just an entity, as you can then reference entities within that device in your automation logic. You can filter devices by integration or model. When using a device input, you typically use target: { device_id: !input my_device } in actions, or use template logic to find a specific entity type within the device.
• selector: area:: Allows the user to pick an area. Useful for blueprints that control devices in a specific room.
• Other selectors: number:, text:, boolean:, select: (dropdown), time:, datetime:, addon:, blueprint:, action:, condition:, trigger: etc., allow you to expose various configuration options.

Using the appropriate selector makes your blueprint intuitive and guides the user to provide the correct type of input.

Best Practices for Managing a Reliable Smart Home Ecosystem with Blueprints

• Organize Custom Blueprints: Keep your custom blueprints in meaningful subdirectories within the blueprints folder (e.g., by function, or by which integration they relate to).
• Use Clear Naming and Descriptions: Both for the blueprint itself and for the input variables. This makes your blueprints easy to understand and use.
• Document Complex Blueprints: If your blueprint is complex, add comments in the YAML or provide external documentation (especially if sharing).
• Test Thoroughly: Before relying on a blueprint, create instances and test them in various scenarios.
• Be Cautious with Community Blueprints: While the community exchange is great, always review the YAML code of a blueprint before importing it to understand exactly what it does and ensure it doesn't contain anything malicious (though this is rare in the official channels). Understand that community blueprints are not officially supported.
• Version Control (Advanced): If you're creating many complex blueprints, consider managing them in a Git repository.
• Backup Your Configuration: Blueprints are part of your configuration. Ensure you have a reliable backup strategy in place.

Conclusion

Home Assistant Blueprints are a game-changer for managing smart home automations and scripts. They empower you to encapsulate complex logic into reusable templates, making your configuration cleaner, more maintainable, and easier to share. Whether you're using existing community blueprints or crafting your own, embracing this feature will significantly streamline your Home Assistant experience and help you build a more robust and reliable smart home ecosystem.