A blueprint in Home Assistant is a reusable automation or script template. One grower builds a well-designed automation for, say, soil-moisture-triggered irrigation. They convert it to a blueprint. Another grower imports the blueprint, selects their own sensor and valve entities, and creates a working automation without reading a line of YAML. The pattern is built once and used many times, on many installations, by growers who may not know Home Assistant configuration well enough to write the automation from scratch. Blueprints are the primary mechanism by which Home Assistant users share automation patterns — "growers teach growers" in practice, expressed as configuration. This page covers how to import and configure existing blueprints, how to turn an automation into a blueprint, the input selectors that make blueprints flexible, the documentation practices that make blueprints maintainable, and the collective's approach to sharing agricultural blueprints so the patterns developed across member operations become available to everyone.
Before using blueprints.
Prerequisites from earlier pages:
Automation basics in hand. [Automation Fundamentals](/home-assistant/automations/fundamentals) covers the underlying model. Blueprints are templates of automations and scripts; understanding what the underlying logic does is what lets the grower pick the right blueprint for their need.
Areas and naming conventions set up. Per [Organizing Home Assistant for a Farm](/home-assistant/agriculture/organizing). Blueprints ask the grower to select entities by name — areas and consistent naming make those selections quick and correct.
A sense of what patterns are worth sharing. Not every automation deserves to be a blueprint. The good candidates are patterns that recur across many operations with only input variations — "high temperature alert," "moisture-triggered irrigation," "DLI-target supplemental lighting." One-off automations specific to a single grower's situation are not blueprint candidates; they stay as regular automations.
What a blueprint is.
A blueprint is a YAML file that defines the structure of an automation or script along with a set of inputs. When the blueprint is used, Home Assistant prompts the user to fill in the inputs, then creates a working automation or script with those inputs substituted in.
Blueprints are templates, not configurations. A blueprint by itself does nothing. It becomes functional only when a user creates an automation from it, selecting their own entities and setting their own values for the inputs. The same blueprint installed by ten growers produces ten distinct automations — each tailored to that grower's sensors and equipment.
Blueprints live in a specific directory. Home Assistant stores blueprints in the `blueprints/` subdirectory of the configuration folder, organized by domain (`automation/` or `script/`) and by source (the author's handle). Importing a blueprint puts it in the right location; creating automations from it is then a matter of selecting it in the UI.
Blueprints can be automations or scripts. The two kinds are functionally similar in structure but fit different use cases. An automation blueprint is for triggered patterns — "when X happens, do Y." A script blueprint is for callable logic — "a reusable cooling sequence any automation can invoke." Most shared patterns are automation blueprints; script blueprints are less common but useful for shared libraries of reusable logic.
Blueprints do not run; automations from blueprints run. Importing a blueprint is like receiving a recipe. It does not cook anything. Creating an automation from the blueprint is making the dish. The automation that results is a normal automation in every way — it appears in the UI, has its own trace viewer, can be enabled and disabled — except that its configuration is controlled by the blueprint definition and its inputs.
Using existing blueprints.
The most common use of blueprints is importing one someone else wrote.
Where to find blueprints. The Home Assistant community forum hosts a Blueprints Exchange category where users share blueprints. GitHub repositories from prolific Home Assistant contributors often contain blueprints. The collective maintains a set of agricultural-focused blueprints (see "The collective's blueprint library" below). Individual creators sometimes publish blueprints on their own sites.
Importing a blueprint. Home Assistant supports importing directly from a URL. Navigate to Settings → Automations & Scenes → Blueprints, click "Import Blueprint," paste the URL, and Home Assistant fetches the blueprint and installs it. The blueprint then appears in the list of available blueprints.
Creating an automation from a blueprint. From Settings → Automations & Scenes, click "Create Automation," and choose "Create new automation from blueprint." Select the blueprint, fill in the inputs (sensor entities, thresholds, target devices), give the automation a name, and save. The resulting automation is a normal automation entity.
Inspecting a blueprint. The blueprint's YAML file is readable. Opening it shows the underlying logic, which is useful when deciding whether to trust a blueprint from an unknown source. The blueprint's `description` field should explain what it does; the `input:` section lists each parameter; the body of the blueprint shows the actual triggers, conditions, and actions.
Updating a blueprint. If the blueprint author releases a new version, updating the blueprint file (by re-importing from the same URL) changes every automation that was created from it. This is powerful — one fix propagates to every user — but also requires trust in the author. Blueprints from unknown sources should be reviewed before updating, or pinned to a specific version through a local copy.
Creating blueprints.
Converting an automation into a blueprint is straightforward for simple automations and gets more involved for complex ones.
When to blueprint something. An automation is a blueprint candidate when:
- The same pattern would be useful in another zone, another operation, or another grower's installation. - The pattern's core logic is stable; the inputs vary per installation. - The pattern is valuable enough that packaging it is worth the effort. - Documentation can make the pattern self-explanatory to a grower who has not seen it before.
The blueprint structure. A blueprint YAML file has three main sections:
- `blueprint:` metadata — name, description, domain (automation or script), source URL (for updates), and the `input:` block defining parameters. - `trigger:` (for automation blueprints) — the automation's trigger, which may reference input values. - `action:` and optionally `condition:` — the actions and conditions, which reference input values through template substitution.
Converting an automation to a blueprint. The mechanical process: start with a working automation, identify which values should be inputs (entity IDs, thresholds, target devices, durations), replace those values with `!input` references, add an `input:` block at the top defining each input, and move the file into the `blueprints/automation/
Input selectors. Each input specifies a selector type that determines the UI control the user sees. An entity selector presents an entity picker scoped to a specific domain. A number selector presents a slider or number field. A time selector presents a time picker. A text selector presents a text field. A boolean selector presents a toggle. A target selector presents an area/entity/device picker for service-call targets. Matching the selector to the input type makes the blueprint easy to use and prevents common input errors.
Defaults. Inputs can have default values. A "high temperature alert" blueprint might default the threshold to 85°F and the duration to 5 minutes; users override when their needs differ. Good defaults make the blueprint usable with minimal configuration.
Descriptions. Every input should have a description explaining what it controls. The blueprint overall should have a description explaining what the automation does, when to use it, and any prerequisites. These descriptions appear in the UI when the user configures the automation; they are the only documentation most users ever see.
Input types and selectors.
The selectors available in blueprint inputs cover most agricultural needs.
Entity selector. Picks one or more entities, optionally filtered by domain, device class, or area. For a blueprint that needs a temperature sensor: `selector: entity: domain: sensor, device_class: temperature`. The user sees only temperature sensors in the picker, preventing accidental selection of the wrong kind of entity.
Number selector. Picks a numeric value, optionally with a min, max, step, and unit. For a temperature threshold: `selector: number: min: 0, max: 120, step: 1, unitofmeasurement: "°F"`. The user sees a slider or input field appropriate to the range.
Time selector. Picks a time of day. Useful for schedule-based blueprints — "start supplemental lighting at this time."
Boolean selector. A true/false toggle. For features that can be enabled or disabled in the blueprint — "enable light-leak detection during dark period."
Text selector. Free-form text. Useful for message templates, labels, or notes.
Target selector. A special selector for service-call targets that accepts areas, devices, or entities. Useful when the blueprint's action is "call service X on this target" and the user should choose the target without the blueprint constraining to a specific entity type.
Select selector. A picklist with predefined options. Useful when the blueprint has a discrete choice — mode selection ("heat," "cool," "auto"), severity level ("low," "normal," "critical"), growth stage, season.
Action selector. An advanced selector that lets the user specify a sequence of actions to be run as part of the blueprint's logic. Useful when the blueprint provides structure and the user customizes the specific actions — "when condition X occurs, run these actions the user specifies."
Descriptions, documentation, and versioning.
A blueprint that works but is poorly documented is hard to use. A well-documented blueprint is often easier to use than the original automation.
The blueprint description. A paragraph or two at the top of the blueprint YAML. Should answer: what does this do, when is it useful, what does the grower need before using it (sensors, helpers, other blueprints), and any known limitations. The description appears in the blueprint list and in the creation wizard.
Input descriptions. Every input deserves a short explanation, even if the name seems self-evident. "Threshold temperature" is clearer with "The temperature above which the alert triggers. In the unit of the selected temperature sensor." The grower reading the wizard in the field does not have time to guess.
Examples in the description. A real agricultural example makes blueprints easier to understand. "Example: select your greenhouse temperature sensor, set threshold to 85°F, choose your phone as the notification target, enable daylight-only to avoid nighttime alerts."
Versioning. The blueprint's `source_url:` supports updating from the origin. Adding a version number to the description — "v1.2, 2026-03-15" — lets users know what version they are running. Major behavior changes deserve a new blueprint rather than a surprising update to the existing one.
Changelog. The description can include a changelog. "v1.0 initial release. v1.1 added hysteresis. v1.2 added daylight-only condition." Users upgrading benefit from knowing what changed.
Compatibility notes. Features that depend on specific Home Assistant versions should say so. "Requires Home Assistant 2025.10 or later for the new wait-for-template behavior." Avoids confusion when older installations try the blueprint.
The collective's blueprint library.
The collective maintains a set of agricultural blueprints. The purpose is to make the patterns developed across member operations available to growers who want working solutions rather than build-it-yourself templates.
What belongs in the collective's library. Blueprints that match the site's agricultural focus — climate, irrigation, lighting, VPD, cold chain, fertigation, photoperiod, multi-zone operations. Patterns that have been tested in at least one real agricultural deployment. Patterns that include the safety considerations and failure handling that production deployments need.
What does not belong. Home-automation patterns (lighting for living rooms, presence detection for bedrooms). Patterns that depend on proprietary commercial integrations that most growers do not have. Untested patterns that have not run in a real operation.
Authorship. Blueprints in the collective's library are authored by collective members. The blueprint's metadata lists the author (by name if they have opted into attribution, or as "OpenAgTechnology Collective" by default). The pattern's provenance — which operation developed it — is part of the description where the contributor is comfortable being named.
Review process. New blueprints are reviewed by at least one other collective member before inclusion. The review looks at correctness, safety, portability across installations, and documentation quality. This process is lighter than formal software review but heavier than "commit and ship."
Contribution. A grower who has developed a useful pattern can propose it for the library. The proposal includes the blueprint, a description of the deployment it was developed for, and any caveats. Accepted contributions are integrated with attribution.
Updates. Blueprints in the library are updated as issues are found or improvements are made. The `source_url:` in each blueprint points to the canonical version; users who have imported the blueprint receive updates when they refresh.
Local copies. For operations that cannot rely on external updates (intermittent internet, security policies, critical production stability), local copies of blueprints work fine. The blueprint file stored in the local blueprints directory is functional even if the source URL is unreachable.
Agricultural blueprint patterns.
Categories of blueprints that come up repeatedly.
Environmental alert blueprints. "Alert when X crosses threshold" with hysteresis, time conditions, and notification target selection. One blueprint handles temperature, humidity, CO2, VPD, DLI, or any numeric sensor. The pattern is the same; the inputs vary.
Scheduled control blueprints. "Turn on X at time A, off at time B" with options for days of the week and exclusion windows. Basic scheduled lighting, scheduled pumps, scheduled ventilation changes.
Sensor-triggered control blueprints. "When X is below threshold A, turn on Y; turn off when X rises above threshold B." Moisture-triggered irrigation, temperature-triggered heating, humidity-triggered dehumidification.
Multi-zone blueprints. Apply the same logic to a list of zones. The blueprint accepts a list of zones (or a pattern that maps to multiple zones) and iterates. Reduces duplication when the same pattern applies to five greenhouses.
Escalation blueprints. "Try approach 1, if that does not work try approach 2, if that does not work alert the grower." Cooling escalation, heating escalation, irrigation retry. The escalation structure is the same pattern; specific actions vary.
Dead-man switch blueprints. "If sensor X has not updated in Y minutes, alert." Catches failed sensors, disconnected ESPHome devices, and communication failures. One blueprint applied to every critical sensor is more maintainable than per-sensor watchdogs.
Schedule-shift blueprints. Automatically adjust targets through a day or season. Ramping supplemental lighting up at sunrise and down at sunset. Shifting VPD targets between daytime and nighttime values. Seasonal automation adjustments.
Data-logging blueprints. Write current conditions to a log (a notification service, a file, a database) at scheduled intervals. Used for compliance records, trend analysis, and operational history.
Common failure modes.
Specific blueprint issues from real use.
The blueprint that referenced entities by specific names. A blueprint hardcoded `sensor.temp` instead of using an entity input. The blueprint "worked" only for users who happened to have an entity with that exact name. Fix: every value that varies per installation should be an input; never hardcode entity IDs in a blueprint.
The blueprint that did not validate selector types. An input was declared as a number without min and max; a user entered a value outside the sensible range; the automation behaved in ways the blueprint author did not anticipate. Fix: use appropriate selector constraints (min, max, step, required options) to prevent invalid inputs.
The blueprint that updated and broke every user's automations. A breaking change to a blueprint propagated to everyone who had imported it, silently changing the behavior of their working automations. Fix: breaking changes deserve a new blueprint (or a major version with explicit opt-in); preserve backward compatibility for existing users where possible.
The blueprint with undocumented prerequisites. The blueprint required a specific input helper to exist, but the description did not say so. Users who created automations from it got errors about missing entities. Fix: document every prerequisite in the description; check prerequisites at automation-creation time where possible.
The blueprint that worked on one Home Assistant version and failed on another. An advanced feature the blueprint used was deprecated or changed in a later Home Assistant release. Users upgrading found their blueprint-based automations no longer worked. Fix: state compatibility ranges; test against the current Home Assistant version; update blueprints when Home Assistant changes affect them.
The blueprint that could not be disabled for one zone but not others. The blueprint was applied in many zones; a temporary need to disable it in one zone required disabling the automation entirely, which affected all zones. Fix: blueprint design can include a per-instance enable/disable helper, or multiple automations each using the blueprint (one per zone) can be enabled and disabled independently.
The blueprint whose author disappeared. The source URL eventually 404'd; the blueprint no longer updated. Users who needed an improvement had no path forward. Fix: fork the blueprint to a location the user controls; keep local copies of critical blueprints; prefer collective-maintained blueprints where longevity matters.
The blueprint that assumed specific units. A "temperature alert" blueprint assumed Fahrenheit; a user with Celsius sensors got wrong behavior. Fix: either make the unit configurable, use the sensor's declared unit, or state the assumed unit clearly in the description.
What not to do.
Patterns to avoid when creating or using blueprints.
Don't blueprint automations that are too specific. An automation that is useful only in one specific operation with one specific configuration is not a blueprint candidate. Blueprints should be patterns, not snapshots.
Don't create blueprints without documentation. A blueprint with no description and undocumented inputs is almost unusable for anyone but the author. The time spent on the description pays back every time the blueprint is used.
Don't overload one blueprint with too many options. A blueprint with thirty inputs and ten conditional paths is hard to configure and harder to debug. Simpler blueprints with focused purposes are easier to use and compose.
Don't trust unknown-author blueprints in production without review. Blueprints from the community forum are often excellent but occasionally contain bugs or assumptions that do not fit your operation. A quick review of the YAML before using a blueprint in production catches issues.
Don't update blueprints in production without testing. A blueprint update changes every automation created from it. Testing the update on one non-critical automation before letting it propagate is cheap insurance.
Don't use blueprints where a script or a direct automation would be clearer. Blueprints are overhead. A one-off automation that you understand and can edit directly is sometimes easier to maintain than a blueprint-based one you have to re-configure whenever the underlying logic changes.
Don't ignore blueprint versioning. Treating every blueprint revision as a minor tweak loses the history of what changed. A visible version and a changelog help users decide when to update.
Don't fork blueprints casually. A blueprint that has been useful to many users has value as a common reference point. Small tweaks on private forks fragment the community. If a change belongs in everyone's version, contribute it upstream.