How do I YAML? Ways to make the website documentation more accessible for n00bs

Configuration
1

Hello Home Assistant Community,

I’ve looked over the website in detail, read through everything suggested on YAML, and I think I’m lacking some kind of base level of understanding. I’m looking for some additional guidance on what I’m missing, but failing that, I’ve got a bunch of suggestions on how to improve the home-assistant website documentation to be more friendly to noobs like myself. I really like Home Assistant and it looks like it’ll be really flexible and powerful, but only after I clear the first hurdle of understanding its syntax.

What I’ve already tried

After some digging on the website (troubleshooting pages should probably be a link in the top), I stumbled on the Home Assistant troubleshooting configuration page here. It’s a good overview of what YAML is, but doesn’t really tell how to use it within Home Assistant. Here’s what I mean:

  • The first example of a collection is nice, but not really useful. Why does it say - hello - how - are - you"? What does that mean in the context of home-assistant? It’d be more helpful if you showed a list of actual items that might be used within Home Assistant, like Living_Room_Light, Hallway_Light, etc.

  • The second example also doesn’t mean anything within the context of Home Assistant. I’m also not 100% sure what it’s trying to get across. There’s a comment saying the first beer: will be ignored because it’s specified twice, but again, why use beer? Also, why ice cold and not just cold in that situation, like it lists water: below? What does this teach me about Home Assistant? It’d be far more useful to show an example using the Light function, and specifying Brightness: twice, adding in a comment that Home Assistant will ignore the first Brightness:

  • The third example, showing nesting mappings, is a lot clearer in some ways but more difficult in others. It shows how to indent, but it doesn’t tell me why you would indent, and what situations you’d indent in. The text above the sample says that indentation is important in specifying relationships… which feels a lot like saying “don’t mess this up” and never specifying what “this” is or how it can be messed up.

  • The fourth example gives a bit more of an overview, but it’s meaningless to someone unfamiliar with MQTT. Even to people who know it’s a messaging protocol, it’s still not really clear what the relationship is between state_topic and sensor, or why one would be part of the other. This is made more confusing by the hyphens in the list, which push the eye into believing the platform: mqtt statement is on the same level as state_topic:

I’ve also looked at the links suggested for additional reading below this, and they make even less sense to me. YAML Idiosyncrasies seems like it could be really useful to someone with more experience, but assumes a base level of understanding and vocabulary I don’t have. The two YAML parsers are the same way - this looks like it’d be useful if I knew more about python, but I installed python specifically for Home Assistant, and then spent 2 hours figuring out what the heck pip was, so I’m not the target audience here. (side note: the HA website is much, much better at explaining this now than it was when I installed python originally)

This brings me around to my biggest question: In the context of Home Assistant, and YAML, what are platforms and components? When do you use one over the other? Why would you call one using platform: in some cases, but other cases just list it directly? There’s a list of components on the website, but sometimes a component (like Lights or Switch) contains another component (like Phillips Hue or Belkin) and sometimes a component is referred to as a profile in the documentation and called as a platform: in YAML. This relationship between these things doesn’t seem consistent, and it is really hard to just wrap my head around.

Thanks for reading the wall of text, hope some of this was useful, and want to say thank you again to everyone who has contributed to Home Assistant! :slight_smile:

6 Likes
2

Hi @faloun and welcome.
I’m fairly new here as well (only a few weeks) and I’ve had some of the same issues as you getting started, but am probably more experienced with learning syntax for new things.
What I’ve been doing is editing the documentation and committing my suggestions to GitHub - including for the page you’re mostly referring to: https://github.com/balloob/home-assistant.io/commit/69ca7107b76c84b4f51dbe1c2cdf618c7dc6098b?short_path=daec241#diff-daec2410099f4754ccbff233c6d0d973

It’s certainly hard to learn multiple things at once, and that’s the main issue here I think.
You say that the trivial examples (like beer) don’t help, but then say that the MQTT example is meaningless if you don’t know MQTT. That’s an example of the problem… we need people to know the context (things like MQTT, lights, platforms, etc.) AND the YAML syntax. Which should come first?
This page is mostly focused on the syntax; the context comes in other places on the site.

I will take your suggestions on board and personally do some more editing. I think the docs could use a YAML intro earlier (not as troubleshooting), so I might try it that way.

I’ll let someone more experienced answer your platform vs component questions.

Thanks for your questions and suggestions :slight_smile:

2 Likes
3

Thank you! Yes, I’m sure there’s a lot of “I don’t know what I don’t know” issues here, where getting to one thing requires knowledge in another, and the circular nature of it all was… a little bit frustrating. I hope that didn’t come out too much. :grin:

I was talking to my wife (who loves python) and she had no problem understanding the documentation. My experience programming is limited to compiled languages like C++, and most of that was a decade ago. Home-Assistant is my first real experience using python, or any interpretive language, so I lack any context for what the YAML is doing on the back-end. That’s really frustrating, because it means I can read through a sample configuration file and have a pretty good idea of what’s going on… but have no idea how to re-create it.

Thanks for your help, and a special thanks for helping out with the documentation. It’s an important but mostly thankless job, and in spite of occasional frustrations I really appreciate it. :thumbsup:

4

Pull request submitted: https://github.com/balloob/home-assistant.io/pull/374
Hopefully this helps. I’d appreciate your feedback when it goes through.

By the way, you don’t need to know Python to edit the YAML config. I know Python but it hasn’t helped with YAML or understanding HA - they’re different beasts entirely. Python is only for when I start developing components and platforms.

5

This thread was marked as solved after I started with the replay. So, I will post it anyway.

To get Home Assistant working only minimal knowledge about YAML is needed. Almost every platform or component contains an sample for the configuration.yaml file and the Getting started docs guide users through the process of setting up Home Assistant.

Feel free to submit Pull Request and propose changes to the documentation. We depend on user contributions.

This is an example of how a collection in YAML looks like. There is no difference if we use light.living_room or monkey. A couple of platform uses this to add multiple values as configurations options.

Again example…

Because it doens’t matter. The key is important and not the value.

This part of the listings show a very common error if a multiple key-value pairs with the same key are used (see also Adding Devices to Home Assistant) and the comment is the hint. It shows the concept. Like an equation…some people prefer to use a, b and other x, y.

This is how YAMl works. The link to the project site of YAML at the very beginning of the section give you access to the detailed description of the language itself.

[quote=“faloun, post:1, topic:459”]
The fourth example gives a bit more of an overview, but it’s meaningless to someone unfamiliar with MQTT.[/quote]

Again, example and still key-value pairs. If it’s get context specific for Home Assistant you want more generic examples but before you complained that the example are out of context.

Doesn’t matter…sensor/topic is only a value. If we talk about a MQTT topic, the format of a topic should match the used format because otherwise it would be confusing for people who knows about MQTT.

Both are on the same level. As shown before in the listing.

Well, if you went through the YAML documentation one should be able to understand the details provided by YAML Idiosyncrasies.

As an user you don’t need to know about the parsing mechanism because Home Assistant is handling this for you in the background. Of course it helps if you have a basic understanding of how the configuration works. The links to the online parser are there to help find syntax errors in the configurations file. Home Assistant is getting a more advanced configuration checking mechanism as we speak.

The website of pip is at least in my preferred search engines the first hit :slight_smile:

Components are implementing the generic functionality of an entity, like lights, switches, or sensors. Platforms are handling the device specific stuff.

Architecture docs contains details about the

Depends on the use case. It’s smart to implement support for X as a component if there are multiple vendors/products available which are acting as X, sharing the same credentials, or using the TCP port. The platform is then only responsible for the communication with the device and the component. See the existing code.

The documentation is listing all entities as components. As mentioned before there needs to be an entry be a entry for the component configuration and for every platform that belongs to the component.

6

@faloun, my edits are live now. Please let me know if this clears things up well (although I’m sure you’ve already learned more and are no longer a noob!).
If you have further suggestions, let us know.

1 Like
7

Hello @fabaff, and thanks for the reply. After looking at @lindsayward’s reply, I realized many of my suggestions were outside the scope of the troubleshooting page. For a little context, I’d spent a solid 2 hours trying to implement a very simple automation rule (turn off the lights when both myself and my wife leave) so my frustration came out a little. :slight_smile: I agree the values and examples aren’t important in the context of that page, I was just being nit-picky because I was frustrated.

The sample configuration.yaml files have been extraordinarily helpful. In fact, pretty much everything I’ve done with home assistant so far involves copying someone else’s config file and modifying it to match my own setup. YAML is quite easy to read, which contributed to my frustration when I couldn’t get it to do what I wanted.

That said, I think now that my problem isn’t with YAML, but my understanding of how Home Assistant interprets it. Everything I tried passed the YAML parser but didn’t behave the way I expected. My answer might be in the YAML idiosyncrasies link included on that page, but to be completely honest, I’m not sure. Much of that page touches on concepts and jargon I’m unfamiliar with, and I haven’t spent the time to go line by line and translate it into something I understand yet. I started, but 20 tabs later I wasn’t much closer and it was time for bed. :wink:

I think I finally understand the difference between components and platforms after reading through your explanation. Components are broad implementations that aren’t hardware specific (e.g., lights and switches), and Platforms represent particular kinds/brands of device (e.g., Phillips Hue and Belkin Wemo). I think a big part of my problem was how Platforms and Components are thrown together in one big list on the Components section of the website, when they actually have a parent/child relationship. Would it make more sense to list these separately? With specific brands listed under “Supported Platforms” instead of being lumped in with Components? It sounds like that’s what you’re hinting at, and I think that would be very helpful for people new to Home Assistant.

8

@lindsayward My understanding of github is limited to the wikipedia entry on it, so I’m still a little fuzzy on push/pull requests and what they mean, but I can infer that the website is updated and I’ll definitely re-read it later on today. :slight_smile:

9

@lindsayward This is wonderful! :thumbsup: :grin: I’m able to follow this documentation much more easily and it does a great job explaining some of the core concepts I really struggled with, especially component vs. platform and the basics of YAML syntax. I also really like how you explain each block of code and provide context for what it will actually do on the back end. It really makes a difference.

The only part I’m a little fuzzy on is here:

The other properties (like name) are specified using mappings. Note that the second line just has threat: with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.

Afterwards, you define a specific instance of the input_select component called threat: but you also define it as name: Threat Level. Is this the difference between using a system defined name vs. a more friendly one for humans? Like renaming light.phillips_hue_1 to Living Room Lamp or something along those lines? Would you refer to it in scripts and automations as input select.threat, just Threat Level, or some third option I’m not considering?

This actually made me realize I’m still not 100% sure how to refer to things, which is the likely cause of my issues. :slight_smile: I’ve just been relying on the auto-fill functionality in my text editor and old-fashioned trial and error.

1 Like
10

I have had the exact same issue @faloun, the initial implementation was completed by copying someone elses examples.

I found the documentation hard to put into an appropriate order. I think that a tutorial that allows you to go from start to finish is something that is lacking at the moment, that will give you the syntax help with yaml, how it fits into HA, and explain the rationale behind reasons.

One of the other things is that the components are independantly developed, which has lead to inconsistent terminology in defining keys for different sensor/switch platforms.

I really love how HA is coming together, how active the community is and that it is going to be able to do what i need it to do, even things i didn’t know i needed (the GTFS component for example!)

any way - keep up the hard work devs!

3 Likes
11

Getting started is done similar to a wizard which is guiding you through the all step needed to setup Home Assistant.

There is plenty of room for improvement in the documentation. Every kind of contributions are welcome.

1 Like
12

I am not talking about the documentation, but how some of the component built - an example that got me was teh commandline switch vs MQTT switch:

switch:
  platform: mqtt
  name: "Bedroom Switch"
  state_topic: "home/bedroom/switch1"

switch:
  platform: command_line
  switches:
    kitchen_light:
      oncmd: switch_command on kitchen
      offcmd: switch_command off kitchen
      statecmd: query_command kitchen
      value_template: '{{ value == "online" }}'

Notice how the different switches are built? CL has “switches”, and all the instances of the CL switches are nested below, MQTT is set up differently.

This is just a by-product of all the great contributions by everyone!

1 Like
13

Yes Yes Yes!!! A SIMPLE tutorial taking someone from start to finish would be fantastic!!! I’m having the same issues. Seems as I can’t see the forest for the trees. It seems to go from installing HA to Step 3 without touching on Step 1 or Step 2. It’s like going through a bag of keys trying to find the one that unlocks the one lock. Frustrating!!!

14

It has taken me a while, but i am getting it. I still tend to bugger around trying things until it compiles.

But i keep my automations short and simple, so that it is easier to debug.

15

I’d be thrilled if someone just put up a simple light showing the programming and where the programming goes. Say a simple light.family_room and have it turn on at sunset and turn off at 11:30PM. I have no idea where things go or what is the correct syntax.

16

sample-automation.yaml (544 Bytes)

Here you go… This switches the front door light on at sunset and off at sunrise.

2 Likes
17

Thanks! So if I’m using a Wink Hub and have the Wink access code this programming would go under that in the configuration.yaml or in a seperate automation.yaml where I direct the configuration.yaml to look?

18

And if I wanted to address a Cree Light I would change “switch” to “light” and add the extension that is in Home Assistant (example: Family_Room_East ) after light?

19

At the bottom of the left sidebar of HASS’ web interface, there’s a row of icons. The one that looks like < > will show you a list of every entity that’s available based on what you’ve configured. The “entity” column will show you the value that you’d use for an entity_id. The services tab (leftmost - like a remote control) will show you all of the services that are available. Things like switch.turn_on light.toggle. The service you’ll use depends on how your device (entity) is supported. homeassistant.turn_on and homeassistant.turn_off are utility services that generally understand what a device is based on its entity_id and will handle things properly.

You’ll only have one block of automations. If you split your configuration as you did, you’ll have all of your automations in automation.yaml. Within that file, you’ll list all of your automations. You’ll use a - (minus sign) at the beginning of each. So that file that @dap35 linked above - that could be the entire contents of automation.yaml if you only define 2 automations. You’ll add a new block for each new automation, starting with a - (minus), etc.

1 Like
20

I think I just about read through all the above and haven’t seen a proper answer to the question. Somewhere further down this topic I came across the typical problem I have encountered and which I think typifies the documentation problem. NO EXPLANATION.

Just like another member, I have only been able to blindly copy examples (IF I CAN FIND ONE) 'cos there is no explanation anywhere of what each line of the example does. The Components section reads like a syntax appendix to a language manual and usually doesn’t cover all the possible syntax.

I’ve been part of other developing projects and whilst you may love or hate Wikipedia there is no substitute for the collaborative effort, the talk pages that elaborate on changes and at one time the great feeling of having made a positive contribution. Submitting helpful document changes as if they were tried/tested code releases is not going to get this documentation issue fixed. You can’t do it with a Forum either because problems and solutions go stale very quickly in a development environment.

Like the OP I see no benefit in confusing examples with ‘cold beer’ (iced or otherwise). I’m here to switch things on and off and I wouldn’t be here if I wanted a beer or if I didn’t understand what I expect HA to do for me. So, ditch the beer and pizza and lets see some genuine examples with commented explanation of each and every configuration line. Lets see examples with a descriptive text explaining the problem and how HA solves it, alternatives (if there are any) and dare I say pictures or videos of things in action to make us cheerful?

Feel free to shoot the messenger as the only other feeling I get (which I will air) is that the driving forces are a little bit deaf to the back seat passengers.

2 Likes