Right now most of the integration documentation is a technical reference indicating the available options, and other than a few examples not a “how-to” guide.
1 Like
On top of it, The doc is not that bad, and tend to improve !
The tricky part is sometime that contrarily to interfaces and integration, there is no translation of the doc, and thus sometime for non-english speakers, the native langage available tuto becomes the doc. And this one is rarely updated…
But to limit a little bit, most of the time, the doc stays unread and many help request are RTFM related…
I just spent 7 hours trying to learn blueprints.
I have a simple automation that I turned into a blueprint
alias: Desk Lamps
description: Turn desk lamps on or off depending on the state of the ISY scene Desk Lamps
triggers:
- trigger: state
entity_id: switch.bulbs
conditions: []
actions:
- delay:
milliseconds: 25
- if:
- condition: state
entity_id: switch.bulbs
state: "off"
then:
- action: switch.turn_off
target:
entity_id: switch.desklamps
data: {}
else:
- action: switch.turn_on
target:
entity_id: switch.desklamps
data: {}
mode: single
This would not work without the delay.
From the main page https://www.home-assistant.io
click on Documentation
click on Blueprints
Under related topics, click on Tutoirial: create an automation blueprint
Using :Studio Code Server and after a lot of trial-and-error, I was able to create my blueprint. I had to convert my if-then-else into a template and I never did figure out how to get the delay in there. I created the sub-directory blueprints/automation/laboratory and put the blueprint there. I came up with:
blueprint:
name: Switch Follower
description: Turn ONoff switch from state of another switch
domain: automation
input:
leading_switch:
name: Leading Switch
description: master switch
selector:
entity:
filter:
- domain: switch
following_switch:
name: Following switch
description: Slave Switch
selector:
target:
entity:
- domain: switch
triggers:
- trigger: state
entity_id: !input leading_switch
actions:
- action: >
{% if trigger.to_state.state == "on" %}
switch.turn_on
{% else %}
switch.turn_off
{% endif %}
target: !input following_switch
Which is nearly the same as the example. And this works. There are two “buts” I enable my orginal automation, trigger it externally, it works as expect. Then I disable the orginal and enable the the automation that runs the templated version, and again trigger it externally. It does not work until I click on the three dots on the right and then run the templated automation.
The second “but” is, “Why did it take me 7 hours to create this simple blueprint?” I have lots of experience. My reasons are that the documentation is not adequte. Basically, where is the documentation for the structure (when to indent, etc.), icons, colors, fonts, etc.? Where does one put comments? (edit in yaml, put in comments, save, test, re-edit … comments gone.)
-osd
1 Like
It’s linked on the page you described navigating too…
https://www.home-assistant.io/docs/blueprint/schema/
That was unnecessary, If/Then actions work in Blueprints.
There is no difference in the YAML used for a Delay action in an automation and one used in an automation blueprint.
One doesn’t if they are using the UI editors… https://community.home-assistant.io/t/wth-comments-disappear-from-yaml-editor/802437/6
One can add aliases to actions and conditions to act like comments.
I edited your post to format the YAML so that other people can actually read it 
3 Likes
icons, colors, fonts are not a thing in HA. So there won’t be documentation about it outside the theme section and blueprints have nothing to do with that area.
As for indentation, the documentation is covered on the schema page, which is the following bullet.
You’re largly struggling with the indentation because you don’t understand data structures and yaml. These are things that are covered in the yaml topic, they won’t be covered in the blueprint documentation because the principles are applied to all yaml.
If you look at the blueprint documentation:
All those keys are 1 indent.
If you look at input, you’ll notice that it says map (optioinal) and it says that it accepts input fields. If you scroll down to it’s configuration values…
Those are all indented under the input field and it provides an example:
blueprint:
name: Example blueprint
description: Example showing an input
input:
my_input:
name: Example input
map is a data structure that requires a key and a value. In the case of input the key is anything you want it to be named, and the value is the configuration values above. I.e. the data structure is
{"key": ...value...}
In the example above, my_input is the key and name: Example input and any other field indented at the same level is the value.
So, this goes on even further with selectors and every other field. If you know yaml and data structures, you can build the entire blueprint without even needing examples just by reading and understanding the current documentation.
This is largely why many people do not have issues with the documentation.
Lastly, you should not expect to learn these things over night. So 7 hours is nothing crazy. You may not like it, but it is all documented.
2 Likes
if-then-else in blueprints:
I copied the actions: section from my original automation and used it to replace the actions: section in the working blueprint. Then I changed the name: to “Switch Follower X”, changed switch.bulbs to !input leading_switch (two instances) and switch.desklamps to !input following_switch . “Switch Follower X” appeared in blueprints.
When I attempted to create my automation I got the error: Message malformed: not a valid value for dictionary value @ data[‘actions’][1][‘then’][0][‘target’][‘entity_id’]
In-code comments
Even if one is writing code for oneself, comments are vital to the next person using the code. The expression, “I stand on the shoulders of giants” comes to mind. Though we may not be giants, let us be those shoulders. Today, everyone here are the shoulders on which I stand. Someday, I would like to be as strong.
@petro Thank you for noting how better to present code. Is there a link to where this is documented? There may be other mark ups that I would find useful.
-OSD
There are buttons for various things on the editor toolbar of the forum too, e.g. it’s the </> button to format as code.
1 Like
@petro This topic is about documentation, though I greatly appreciate the guidance given. To that end, the documentation has a theme which I had conflated with the HA code. The theme helps the reader in understanding the documentation. When modifying the documentation, it is important to stay with the theme.
If I were to add my two-cents to the blue print page, I would put comments in the example. These would help the people that are new to blueprints:
eg:
blueprint:
name: Motion-activated Light
# name that will appear on the blueprint page. Avoid duplicate names to prevent unintended using, editing, deleting of blueprint`
description: Turn on a light when motion is detected.
# description shown when the blueprint is selected as a hint as to what the blueprint does
domain: automation
# automation, script, template see also: https://www.home-assistant.io/docs/configuration/entities_domains/
input:
# the "variables" of the blueprint
motion_entity:
name: Motion Sensor
# the varable name (Caps made lower case and underscore _ replaces the space)
selector:
entity:
filter:
device_class: motion
# device citation needed here
domain: binary_sensor
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
# automation follows, note variables are preceeded by !input
.
.
.
Thanks for your help and consideration!
OSD
The point of my post was to show you that the information you’re looking for is there, but you’re missing the fundamental understandings of YAML to understand the docs. Unfortunately, knowing YAML goes hand in hand with knowing blueprints. After all, they are an advanced portion of HA.
If there was an architecture (or task focus or UX focus) for the documentation, it would contain sections like prerequisites and where to go for more information. Understanding YAML and Jinja2 are key to becoming and intermediate or advanced user.
There should be some structure around basic, intermediate, and advanced topics and tasks. Ideally the documentation would be organized to deal with user “types”. Some users will be “appliance operators” that hope to be able to do everything from the UI.
Creating blueprints is at least an intermediate level task.
Another related thing that would help is roadmap style learning paths—These are topics you might want to read as a beginner, To become an intermediate level user these are the things you should learn.
First, Thanks for another good example of the structural problems, how is “Basic Information” part of Advanced Configuration? Advanced topics seems like a place to put anything that doesn’t fit in one of the other categories.
That YAML page is a pretty good collection of some of the YAML related issues. However, it isn’t a good tutorial, nor does it point to anything that would be. Having the first section be about YAML style guide serves developers not new end users.
The templating page is also a somewhat unorganized collection of stuff to the point that it is neither a good tutorial or a good reference manual, particularly if you haven’t been using Home Assistant for a long time.
It is an improvement that those YAML and Templating pages exist and maybe there are some efforts to add structure.
Since you respond to so many things, what would cut down on the number of responses you have to generate? What would help people ask less questions?
These aren’t meant to be tutorials, they are meant to be pages that document functionality. If you want to add a tutorial, you’re more than welcome to add one, it will likely be another page (like the blueprint one).
YAML and JINJA are both languages that are outside HA. You can look up any tutorial on yaml or jinja an it will transfer to HA. You then check out those advanced pages for the home assistant atlerations to yaml and jinja.
As a person who contributes quite a bit to this project, it seems like this thread is full of people that have ideas to change documentation but are unwilling to assist in doing so. I seem to remember having these exact conversations with you the last WTH. Here we are again, but I don’t see any contributions to any of the ideas you have (or had from the last wth). It’s like you’re expecting us to say “Yes I agree”, and then do the work you laid out.
6 Likes