I know experienced users will laugh at this, but I’m just getting started with HA, and I wanted to mention a few points about the automation editor that gave me problems with my first attempt at creating an automation.
I just created my very first automation, a simple motion detect -> turn on light. The principles are easy to understand, and I was pleased to see a convenient UI automation editor, although unfortunately most of the examples of automation refer directly to the automation configuration file rather than showing the automation editor. That led to some silly initial problems because there are so few examples of the automation editor.
The first was that the syntax of the “Service Data” field was not clear. The only example given in the HA documentation (https://www.home-assistant.io/docs/automation/editor/) showed creating a text message, where the text was naturally quoted. It took me quite a while to find another example that made it clear that the syntax is actually “key name”:“key value” with the quotes required for everything. It would help if the description page for the editor made this clearer, or offered an extra example.
Second problem was that my automation would not save, and I eventually noticed by scrolling up to the top of the page that it displayed the cryptic error message: “Message malformed: Entity ID is an invalid entity id for dictionary value @ data[‘trigger’][1][‘entity_id’]”. It took me ages to figure out that it was complaining about a blank 2nd trigger entry. Maybe I hit the Add Trigger button during entry without realizing that it created a blank 2nd trigger. Anyway, the automation editor should really ignore blank entries, and it would sure help if the error message was more understandable or this problem was mentioned in the documentation.
Third problem was that my automation would not work, and I was reduced to trying things at random until I finally hit on changing the capitalization of the binary sensor states, from “On” and “Off” to “on” and “off”. The information shown on this page is therefore wrong: https://www.home-assistant.io/components/binary_sensor/ . I did not find any way to check what the actual available states are. Presumably it’s buried in a configuration file somewhere?
I just set up a Z-Wave motion sensor controlling a light.
I checked the z-wave log when my automaton did not work and realized the states output by the device were not capitalized.
You do not state what type of sensor you have. That platform may have a separate log to check.
Yes, a lot of the documentation is written by very experienced users, for very experienced users. And a lot of details are left out, or (as you found) some minor details can be flat out wrong. I think that’s just the nature of a project that’s running headlong toward “version 1” with a lot of developers and frequent changes.
My big “ah-ha” moment was that each entry has to start with a unique "id: line, but there’s no magic format the editor uses; just random numbers. I could use (lower case) letters and the “_” character to make mine human-readable.
Actually, the syntax shown in the example (see below) is quite clear and the form is: "key": "value"
{
"message": "Sensor value greater than 10"
}
I don’t know why you were led to conclude text was naturally quoted.
Referring to the documentation, the third line in the first paragraph states:
These sensors only have two states: 0/off/low/closed/false and 1/on/high/open/true .
I see no mention of On or Off.
I believe what you may be referring to is in the Device Class section. It use the form On and Off to explain how the different device classes interpret the two states. Let’s take a walk down memory lane to see how this documentation page evolved:
The first use of ‘On’ and ‘Off’ was in February 2016. The capitalization had more to do with the spelling conventions of written text as opposed to the literal representation of a binary_sensor’s two states.
Then in July 2017 all ‘On’ and ‘Off’ became On and Off. This visual flourish served to highlight the words but, it would appear, had the unfortunate side-effect of leading some readers to believe it represented the valid literal states for a binary_sensor (which they are definitely not).
You should know that Home Assistant is not a commercial software product. It’s an open-source software project. That means it is built by volunteer contributors. That means you.
If you find the documentation is in error or is unclear, then you’ll be pleased to know you can take action to correct it.
Get a GitHub account then, on the doc page needing revision, click the ‘Edit this page on GitHub’ link. Submit a Pull Request with the modifications (i.e. changing the states to on and off). Someone will review it and, if acceptable, will merge it into the documentation. If not acceptable, they’ll suggest what you ought to change. That’s how you can improve the documentation and the community will appreciate your contribution.
The answers always seem obvious when you already know them, but surprisingly they don’t seem quite so obvious when you don’t. For example it seems obvious to you that a parameter needs to appear in quotes when the example shows that. But what I saw was a quoted text string parameter. Text string parameters are almost always quoted, but that doesn’t imply that other non-text-string parameters are quoted. Hence my suggestion that it would be nice to actually state that ALL parameters should be quoted, or show an additional non-text-string example.
Thanks for the instructions on how to contribute to documentation. I like what I’m seeing in HA, and when I’ve had a bit more experience I will certainly submit some suggested doc improvements.
Thank you so much for taking the time to write here!
My plate is pretty full right now with other projects, and I’m trying to sneak HA in on the side. Once I have more time to devote to it, I think my first foray into contributing will be figuring out how GitHub works so I can help with the documentation. It’s always easier for a fresh set of eyes to spot improvements and corrections.
You’re making an incorrect assumption about me. JSON notation was not ‘obvious’ to me, I learned it.
I agree with you that it ought to show at least one or two more examples, or direct the reader to pertinent reference material. In fact, for a key:value pair, only the key is always quoted whereas the value’s type determines if it should be quoted or not. For example, if a numeric or boolean value is not quoted then it is interpreted, not as a string, but as numeric or boolean. Similarly, arrays (called lists in python) aren’t quoted.
What you’re actually doing with these key:value pairs is creating a data structure called a dictionary (dict) and following the dictionary’s rules for how to define the pairs. I found a fairly straightforward explanation here. It includes several examples of dictionaries whose values are of multiple types.