YAML Basics // Level Up Your Home Assistant Skills

hey everyone it's ryan with the smart house and on today's video we're going to be doing another in our series of getting started with home assistant so i've had a number of viewers in both the comments on these youtube videos and in my discord server asking questions on this specific subject now these users have encountered problems when adding new integrations to their home assistant instance that don't use the new ui function they stumble across something that all beginners dread code they look up a new integration that fits the device in their house and then they're presented with a block of code some files they don't recognize and then they give up never fear because in today's video we're going to take a look at the fundamental configuration building block of home assistant yaml now i wanted to title the video yaml basics or how i learned to stop worrying and love code but i figured a lot of people wouldn't get it and it won't fit in youtube's title length restrictions so in today's video i'm going to explain to you some of the syntax or how yaml code is formatted and how home assistant specifically uses it so by the end of this video you'll know the basics of yaml how it's formatted and how you can clean up your home assistant configuration files to make it both more secure and easier to read so let's take a look at what is yaml all right so let's start at the beginning so yaml stands for yet another markup language now this is a coding language um configuration language that's been around since 2001. it's actually very similar to xml if you've used it but it's a little lighter weight so it's primarily used to bring a custom configuration into an application when it starts up so this is used in oracle and other systems where you want to read a configuration out of a file and dump it in to a application that's going to start up now home assistant chose this one i believe because it's fairly lightweight and it doesn't require a lot of additional syntax except for the items i'm going to cover here in just a second so let's talk about the structure and syntax of yaml now please don't fall asleep i will make this section as quick as possible and i've got some examples that i've taken from the home assistant documentation but i'll take you through them in each step so you understand what they mean so most of you don't know but i really like to diagram and show people examples on a whiteboard the unfortunate thing is one i'm left-handed so it's really hard for me to write on a whiteboard two my handwriting is terrible and three i cannot draw worth a darn i'm going to be using some paper printed out versions of the code to show you the examples as we move through today so the main form of syntax or code format that there is in yaml is the indent and in yaml the indent is two spaces so what this means is if you look at a structure of code each hierarchy is designated by double spaces so each double space is moving one step down the hierarchy now one thing to note is yaml does not accept a tab character so if you were to say open up a yaml document in notepad on windows and insert your code and put a tab in instead of a double space if you save that and try to execute it you'll get an error message at home assistant this is because it doesn't accept that tab format if you use a modern code editor like vs code or even notepad plus plus it will disable tabs entirely and replace every tab with two spaces so keep that in mind as you're editing your file for the first time if you're using something basic like notepad make sure you're following the rules of using spaces not tabs but if you're using a different one it will call it out or replace it automatically so for this first example these are basically what you're going to see anytime you run across a documentation it'll be a small snippet of code with a specific platform called out so this is designed for a single giant configuration.yaml which is a fine thing to do but later on in the video we'll talk about why you might want to split this up into smaller chunks and i'll show you how to interpret these type of commands if you have a split configuration but for now we're just going to go through as if this is just a section in your configuration die so say you wanted to add the push bullet notifier and again this is now in the ui but this is still a good example so we've got the notifier platform so if i put a line down here this indicates this is the left side so there is no space here the the platform callout or integration coa is all the way to the left it's the first item in the line we want to define the platform so we'll bring in the platform but you'll notice this is an indent and this indent is two spaces to move it over in the hierarchy now you'll notice this does not have quotation marks on it and that is because it's defining a known platform in the system it's not a variable which we'll get to the quotes here a little bit later so again now we move on to the next value and it has two spaces in front of it of course these have a space in between so this is a value so how things are defined in yaml is you have a key and a value and those are separated by a colon this is typical in things like json or other platforms but just remember every time you define something you have to have a key and then a value and we'll go a little bit into some of the pitfalls you can have with quotes a little bit later in the video so then finally we do two more spaces and we define the name also push bullet so in this case this string doesn't have to but you can put quotes on here because it can be given a name so you could name this push bullet you can even whatever you want to do so as we see here anytime you define something the first line or the first section of a new integration is always going to be the integration or platform name then the next line down is every definition under that every key under that there's a basic introduction into yaml code we've looked at what our indents look like we've looked at what is a platform or integration and we've also defined the key and variable pairs that are required as you go through a yaml code so let's move to a slightly different code this will have multiple callouts under the same platform [Music] now we're going to introduce a new element into our yaml setup here and that's collections which is the hyphen you see here so again or integration is sensor so then we go down to the next step and since we're under sensor we've got two spaces here and then you'll notice we now have a hyphen in the mix this hyphen indicates a list or collection of items so if you have a large number of sensors each one of those sensor headers are gonna start with a hyphen platform so you could have hyphen platform mqtt template anything as you go down you have to have that hyphen indicating that there's a list of items that we're going down through so in this case we've got platform as mqtt under that this is the state topic example here of sensor topic so again here we've got to go four spaces in because now we are under the platform mqtt and one quick tip to notice if you're using a more modern editor it'll be using a type of font that has equal sized letters so you will always be able to tell the alignment by where it lines up so if you notice this hyphen is directly under the n and that's two letters in so that's your two white space your two spaces there hyphen platform mqtt then this one lines up directly under the p the s under the p because there's four spaces here because you've got one two three four because this is actually there's actually a space here too so now we'll define the next sensor which is also an mqtt platform under here so again we've got two spaces and then our hyphen showing our next element in the list as platform mqtt directly below that again we've got state topic with four spaces in front of it and then our next sensor value which is defined over here so again this is an example of having a set a collection in your list of items so again no matter what it is whether it's sensors notified binary sensors you're going to have a hyphen at the beginning of each of these platforms because you've got multiple entries heading down your yaml file in our last example we only had a single platform so we didn't need that because we didn't have a list so anytime you're going to have a list of items you're going to need to have a hyphen in front of it so now on to our last example we're going to introduce a few more elements and kind of combine everything together [Music] so for this example we're going to be defining an input select now again this has been transferred into the ui but you can still define it in the yaml code so it's just a good example that has all these elements pulled together into one so again we have our platform definition at the top no spaces to the left we come down to where it will define the actual name of the entity of the input select so we have to have two spaces in front of that this is an example if we had more than one entity here we'd have to use a hyphen but since we only have one we're not going to use the hyphen we move down inside the to the next level over and that's why we need four spaces here so we can find the friendly name of this input select now say i wanted to add a note here to myself that i could read later on while i'm coding if i want to stick this note here this would cause a syntax error because this is not a valid key here however if you wanted to add something all you got to do is throw a hashtag in front of it or as we always call it a pound sign and in this case it doesn't matter if there's spaces in front of it or not because it's a comment block as soon as the interpreter comes across this pound sign it's going to say this doesn't matter i don't need to read the rest of this line move on to the next one so you can include a comment at the end of a line on its own line either way as soon as it hits that hash sign it's going to stop interpreting the code and it's going to move on to the next line so in this case since it's under here we have four spaces in front of it but that's entirely optional because again it's not going to actually be interpreted by the interpreter it's going to skip that and continue on so next we have to define our options for this input select and since it is a parameter that's under the same entity called threat it's going to be in line with the line above it so again since this line's a comment it doesn't matter but because these are under the threat hierarchy then these two be the name and the options would be on the same line so again this requires four spaces in front of it and now we're going to find the options so then we're going to bring in another one of our collections so now we have another list here so because we have a list we have to use our hyphens and since this list is under the key of options we have to indent it to one more so in this case there are six spaces here and that's the case for each of these lines as you go down because again you're moving into the hierarchy you have to have six spaces there so again you want to make sure that the hyphen lines up with the third letter in the word and then that's how you know you're in that particular column so then finally we have another thing that we're defining this this is another requirement for the input select and since this is not part of the options subheader it moves back out again so in this case it's got four spaces in front of it so if we look at the actual code it's a little bit easier to see than it is here on the whiteboard that you've got the first elements which is the input select the second element which is threat everything is under that then you move to the third level of hierarchy and that's where the options are defined for this element you've got name options and initial and then the fourth hierarchy is showing under the options and then finally we've also introduced a comment so again you could place the comment anywhere you want in your line and it's good practice to add comments so when you go back to try to figure out what you meant you don't have issues understanding why you wrote it that way so before we move on to the next section there was a there's a couple of elements that i want to point out that are important to understand about yaml the first one being letter case now yaml interprets uppercase and lowercase as different characters so if you were to say have a sensor called sensor oven with a lowercase this does not equal sensor oven with an upper case so if you were to use define a sensor using all lowercase characters and then later on reference that sensor but you have an uppercase character it's not going to work it's going to error out because this is a different sensor than this over here so make sure you keep it consistent i like to use all lowercase when defining my characters in the yaml just so we don't run into that problem and that subject let's talk about our final tip in this case is how is making sure you use consistent quotations throughout your environment now you can nest quotations if you look at my first example here we have a single quotation on the front first and ending to put that whole section in quotations you'll notice that my on has double quotes around it now this is correct and this is completely acceptable so you can get away with this also you can get away with having double quotes on the outside and single quotes on the inside because they're matched correctly now if you look at our third example here we use a single quote and then we use a single quote again here on the on this is going to cause the interpreter to see this whole section here in quotes and then it's going to see the word on out of quotes and it's going to cause an error message so this was incorrect you shouldn't do it this way this is this last example is when i see a lot of people get tripped up on if you use the same quotes throughout the entire the entire thing whether it's single quotes or double quotes all the way through there so you put double quotes on the outside here to start and then you put double quotes around you're on and then double quotes at the end again the interpreter is going to see this is the beginning of your quotation area and this is the end then it's going to see these in quotations so it's going to find this on outside of quotations it's not going to know what to do with so again when you are having nested quotations make sure you start and stop them correctly you need to make sure you use it in the correct order because it won't know where it stops and where it starts so make sure you select one style so if you wanted to have your outside quotes always be single quotes and then your inside quotes be double quotes that's fine just pick a standard and stick with it all right so now that we've seen some of the ins and outs of the yaml language so now we've seen some examples of the yama language and how it's used let's hop back onto the computer and we'll take a look at how it applies specifically in home assistant and how home assistance hierarchy works with a split configuration all right so for this next section let's take a look at how home assistant specifically uses yaml and how to split up your configuration file now home assistant has a great article it may be a little outdated but on how to split up a configuration file and talking about the core structures of their yaml configurations i'll take you through the configuration file for my test environment we'll go ahead and split off a couple of sections into their own files and then we'll talk about the secrets.yaml section so if we hop over into my visual studio code for my configuration.yaml on my test environment so i actually created this one um a couple about probably a year ago the older version configuration.yaml file was a little bit different now i believe if you start today you already get a partially split configuration file things like your groups automation scripts scenes sensors switches input booleans and binary sensors all already come with a file with an old configuration.yaml or if you are splitting off one you found before this would be a good method to help you out so starting with our configuration.yaml we'll notice i've got a large section of cameras and i've also got a large section for the rest command here so if we look how it works is we have our integration up here so like in our examples notify things like that two spots and you'll see here this is why using a more modern editor like vs code helps because it shows you the spaces that are here make sure you're lined up so if i scroll all the way to the bottom here you'll notice that i've got a few of these with an include here so how this works is so when yaml sees this exclamation point it calls out a command it's telling it to include a groups.yaml file and if we look at my configuration here you'll see there's a whole series of files in the same folder as my configuration.yaml so in this case it's calling out for the group integration it wants to include the groups.yaml so it's going to call out this groups.yaml file and then parse it down and then move to the next line so if we look at my sensors over here so bring up the sensors.yaml now there's a whole series of files under here that would be in my normal configuration.yaml but that would just clutter things so if we notice on this one because we are already under the sensors integration the first line is the hyphen so we can see each to the far left is a hyphen and then two spaces and then it starts each one so so we use the same example we did on the white board we'll see this push bullet if we want to pull this in as a sensor you'll notice that it's called out the sensor and then it's going to give you something that's going to give you the rest of code now if you were to grab this copy it and paste it into your sensors.yaml you are actually not within syntax if you look it's going to give you an error message that's because it already included the indent so you can remove that and shift everything over two spaces and then you'll be set so that's how when you wanna grab code off of an example off of the documentation if you were to grab it with all the indents in there it's gonna fail because it's assuming you're pasting this into your configuration.yaml but when you paste it into a separate yaml file for say sensors you need to remove left two spaces off of everything shift it over one so it matches up with the items above and this is one of the issues a lot of new users run into is they'll grab that snippet of code paste it and then they'll run into errors and give up if you wanted to create a new one so let's i'm going to go ahead and create one called for camera and then i'm going to include camera.yaml now you'll notice in vs code it's going to give me this duplicate key error that's because i already have a camera section defined here now one thing to note is if you do have duplicates in here it's always going to take the last key the last integration it may even error out but it will always take the last one because it's going to read it and it's going to overwrite your existing cameras but it's always a good idea to get rid of the duplicate key so now i'm going to take all of my code from here remove it remove the camera integration and then we'll go over and we'll create a new file and call this one camera now when i paste my code in here everything is going to be two spaces to the right too far so obviously i could go through here and erase those two spaces but in most modern editors you can hold down shift and tab and it will bump everything over one indentation so there we go now everything is lined up correctly the hyphens are all the way to the left so this should when i save it and check it everything should be good so let's go back to the configuration.yaml and we're going to go ahead and do the same thing for the rest command so i'm going to grab everything under the rest command and you'll notice there's only one entity i'm defining so there's no hyphen here so let's grab all this cut and then i'm going to remove the white space here and we'll say include restcommand.yml again we'll go create a new file call us rest underscore command.yaml and we'll paste the code in and again our indent is in there so we'll go ahead and remove that shift everything over the left and then hit save so now we have a much simpler configuration and it's much easier to jump into the right section to make the edits you want to make and obviously to check this you go to configuration go down to server controls which looks different this is still running an old version and then you hit check configuration and this is going to make sure your configuration is valid if you get no errors when you restart it home assistant won't freak out so you know everything's good all right for this last piece let's talk about secrets.yaml so if i hop into my sensors you'll notice right here i've got a secret definition so very similar to how the include works where you use the exclamation point include when you use the tag exclamation secret it's going to look into a specific file and look for a key to bring in and replace this variable so in my case there's a secret and it's going to look for this key switchbot underscore api so if i open up my secrets.yaml you'll notice these again are all lined up to the far left hand side and you'll see these are the keys it's going to look for so what's going to happen when it hits that exclamation point secret it's going to then pop into the secrets.yaml file and search for that key so obviously these two need to be identical these keys need to be identical because it's got to search it out it's going to come down here find this and then it will insert everything to the right back in to the configuration as it loads now the biggest reason you want to do this is say you want to get help and you post either in the forum or on a discord server the first thing they're gonna ask you is to send us your configuration so we can read through your code to make sure everything looks good now obviously if you copy and paste that it's gonna contain things like passwords and api keys and that's not a good idea and you'll typically be asked to delete your file if you do that so if you use the secrets.yaml you can actually upload your entire configuration except for the secret file and then people can be able to help you with it or if you want to share this example with a friend you can do that without exposing all of your passwords so it's a good idea and it's now set up by default in home assistant to load that secrets.yaml in there say i wanted to keep this ip address safe so i'm going to go ahead and put it on my clipboard we'll type in exclusion point secret and then we'll give it a we'll call it a xiaomi ip now go into my secrets.yaml go down to the bottom here and we'll do xiaomi ip and then we'll paste in the ip address and again once we save that it will grab that when it loads the configuration into home assistant and replace it with the ip address therefore if i share this out i don't have to give out any information so there you go that's how in home assistant you can take an existing configuration and split it up now we've seen how the include works there are some more advanced features like include directory where instead of including an individual file you can actually tell to include an entire directory so if you wanted to split your configuration even further like you had automations you wanted to split them into separate automation files you can do that but that's a more advanced topic that we may cover in the future so we now see how to split a configuration file up we've talked about using the include tag we've talked about taking an existing file and then making a new yaml file to keep things clean and organized and i've shown you how to use the secrets.yaml so if you do run into any questions on these please make sure you join the discord server or leave a comment here below all right so there you go hopefully you found this basics video helpful even if you've never used yaml before i hope you learned something new now i plan to have more of these basics videos each month in 2022. so if there's a topic that you want to see please leave in the comments below now i know i have an mqtt basics video in the works but that's been a popular question that i've received now if you'd like to see more home assistant basics videos click on the playlist right here if you like to look the algorithms like the next video for you click up here now as always if you haven't already please make sure you subscribe to the channel by clicking our logo right here so thank you again for joining us on today's video and i hope to see you next week for another video have a great week

Channel: This Smart House

Views: 42,524

Keywords: yaml tutorial, yaml basics, yaml tutorial for beginners, home assistant, home automation, introduction to yaml, yaml introduction, yaml for beginners, what is yaml, yaml syntax, learn yaml, home automation system, yaml home asssistant, home assistant split config, split config

Id: nETF43QJebA

Length: 22min 58sec (1378 seconds)

Published: Mon Jan 31 2022