Home Assistant Blueprints: Supercharging Reusable Automations

Home Assistant is renowned for its powerful and flexible automation engine. However, creating complex automations from scratch, especially for similar tasks across multiple devices, can be time-consuming and repetitive. This is where Blueprints come in. Blueprints are a feature designed to simplify the creation and sharing of automations, scripts, and even integrations, allowing you to define reusable patterns that can be easily configured for different devices or entities.

What are Home Assistant Blueprints?

Think of a blueprint as a template for an automation or script. It defines the basic structure, including triggers, conditions, and actions, but leaves certain elements parameterized. These parameters, called 'inputs', can be configured by the user when they create an automation based on the blueprint. This means you can define a common pattern, like "turn on a light when motion is detected in a room", and then use that blueprint multiple times, simply selecting the specific motion sensor and light entity for each room.

Blueprints are defined in YAML format. They can be shared easily as files or links, making it simple to import useful patterns developed by the Home Assistant community.

Why Use Blueprints?

• Reusability: Create an automation pattern once and apply it across numerous devices or scenarios without rewriting the core logic.
• Simplification: Complex automation logic can be encapsulated within a blueprint, providing a user-friendly configuration interface when creating automations from it. No need to dive deep into YAML every time.
• Sharing: Easily share your useful automation patterns with others, and benefit from patterns shared by the vast Home Assistant community.
• Standardization: Ensure consistency in how certain types of automations are implemented across your home.

Finding and Importing Blueprints

Home Assistant comes with a few built-in blueprints, and the community provides many more. You can find shared blueprints on forums like the Home Assistant Community Forums or GitHub repositories.

Steps to Import a Blueprint:

1. Find a Blueprint URL: Locate a blueprint shared online. It will typically be a GitHub Gist or a direct link to a raw YAML file. Copy the URL.
2. Navigate to Blueprints in Home Assistant: In your Home Assistant UI, go to Settings > Automations & Scenes.
3. Open Blueprints: Click on the "Blueprints" tab at the top.
4. Import Blueprint: Click the "Import Blueprint" button in the bottom right corner.
5. Paste URL: Paste the URL you copied into the "URL of the blueprint" field.
6. Preview and Download: Home Assistant will fetch the blueprint and show a preview. Review the details to ensure it's what you expect.
7. Download: Click the "Download blueprint" button.
8. Confirmation: The blueprint will be downloaded and added to your list of available blueprints.

Once imported, the blueprint is available for you to use when creating new automations.

Using an Imported Blueprint

Using a blueprint to create an automation is straightforward:

1. Navigate to Automations: Go to Settings > Automations & Scenes > Automations.
2. Create Automation: Click the "Create Automation" button in the bottom right.
3. Choose from Blueprint: Select "Create a new automation using a blueprint".
4. Select Blueprint: Choose the blueprint you want to use from the list.
5. Configure Inputs: The UI will present you with fields corresponding to the blueprint's inputs. These might be entity pickers (for devices, lights, sensors), number inputs, text fields, etc. Configure these inputs according to your specific needs.
6. Add Description (Optional): Provide a description for this specific automation instance.
7. Save: Click "Save".

Home Assistant automatically generates the YAML for the automation based on the blueprint and your provided inputs. You now have a new automation instance based on the reusable pattern defined in the blueprint.

Creating Your Own Blueprint

If you have a recurring automation pattern or want to share a useful configuration, creating your own blueprint is the next step. This requires writing YAML code.

Blueprint Structure (YAML):

!$0$!

Key Sections:

• !$1$!: Metadata about the blueprint (name, description, domain).
• !$2$!: Defines the parameters the user needs to provide. Each input has a name, an optional description, and a !$3$! which determines how the input is presented in the UI (entity picker, device picker, number field, text field, etc.). You can set optional default values.
• !$4$!, !$5$!, !$6$!: These follow the standard Home Assistant automation/script syntax. Crucially, you use !$7$! or Jinja2 templates like !$8$! to reference the values provided by the user for the defined inputs.

Steps to Create and Test:

1. Write YAML: Use a text editor or the built-in File Editor add-on to write your blueprint YAML code.
2. Save File: Save the file with a !$9$! extension in the !$10$! folder (replace !$11$! with !$12$! if creating a script blueprint). For example, !$13$!. If these folders don't exist, create them.
3. Reload Blueprints: In Home Assistant, go to Developer Tools > YAML, and click "Reload Automations & Scripts". This will also reload blueprints.
4. Test: Go to Settings > Automations & Scenes > Automations, click "Create Automation", and choose "Create a new automation using a blueprint". Your new blueprint should appear in the list. Select it and configure an automation instance to test its functionality.
5. Refine: Edit the YAML file, reload, and re-test as needed until the blueprint works as intended.

Tips for Effective Blueprints

• Use Selectors: Always use appropriate selectors in the !$14$! section (!$15$!, !$16$!, !$17$!, !$18$!, !$19$!, etc.). This makes the blueprint configuration user-friendly in the UI.
• Clear Names and Descriptions: Give your blueprint and its inputs clear, descriptive names and descriptions so users understand what they do and how to configure them.
• Provide Defaults: Where possible, provide reasonable default values for inputs.
• Be Specific (but not too specific): Filter selectors (e.g., by domain or device type) if the blueprint only makes sense for certain types of entities/devices. Avoid being overly restrictive unless necessary.
• Add Notes/Comments: Use YAML comments (!$20$!) to explain complex parts of the blueprint logic, especially if sharing.
• Include Metadata: Add !$21$! if you plan to share on GitHub or elsewhere.

Best Practices for Managing Blueprints

• Version Control: If you create your own blueprints and plan to evolve them, consider storing them in a Git repository (like GitHub or GitLab). This helps track changes and makes sharing easier via raw file links.
• Backup: Blueprints stored in your !$22$! folder are part of your Home Assistant configuration backup. Ensure you have a reliable backup strategy in place.
• Keep it Simple: While blueprints can handle complexity, the most successful shared blueprints often address common, well-defined problems. For highly unique or specific logic, a standard automation might be more appropriate.
• Regularly Check for Updates: If you import blueprints from the community, periodically check their source locations for updates or improvements. Some blueprint creators announce updates on the community forums.

Blueprints are a powerful addition to the Home Assistant ecosystem, transforming how we create, manage, and share automation logic. By leveraging reusable patterns, you can build a more robust, easier-to-maintain, and scalable smart home configuration.