Home Assistant Coding Tutorial APIs - Integrate any Device

on the road to becoming a home assistant pro you'll need to start to learn about apis by the end this video you'll be able to look at an api documentation or a youtube tutorial and use information from the api to create a sensor in home assistant now let's throw the intro what is an api in a nutshell an api is simply a messenger imagine you're at a restaurant and you have a waiter and you have the kitchen the api is the waiter basically it's taking your order and then delivers the food the api documentation is going to be able to tell us which type of messages can we send so basically what's on the menu and what type of response or what can we expect back from the api and it will also tell us about errors the command line interface really is a simple way to send instructions to a computer exactly as what you do normally on day to day when you're using a mouse and a keyboard let's jump into the switchbot api and let's see how that works to actually talk to the api so to make your order this is the host this address over here api switch bob is what we will be using to communicate there are different ways that we can communicate we can communicate in four ways with a get a put a post and a delete to keep your account safe and secure you're going to need to be authorized to do this in this example we're using a token to actually get the token if you're doing the switchboard integration you can follow these stats with quite simple you can get it for the app tap on the app version 10 times don't worry if you lose a token just regenerate it and you'll be good so once you've got your token put it maybe on the notepad like i've got over here token and this is how the token should look it's not going to be exactly the same because each user is going to have their own token now we're going to need to do our first request but first we need to find out of how are we going to make this request so how are we going to build the command that we're going to use in the command line so let's jump back into the documentation let's find out note there's a request limit per account of 10 000 calls a day look at the parameter and you can see the exact name authorization and you can see the location of the organization which is the header on the devices you're going to see a get so get v dot 1.0 devices what does this mean this means that we are going to ask the messenger so we're going to ask our api for a list of all of the devices so i am just reading information i am not controlling the devices at this stage underneath here there's more information about which devices can actually appear obviously this will depend on the devices that you have in your home connected to the switchbot api first thing is using cal now we need to specify the header so minus h authorization we can open up with the double quotes and go back to the documentation and you can see the past possible parameters in the request and we have the authorization over here and we know it's a string and it goes in the header hence we put the minus h over here so we put authorization then we put a colon so we specify the value and the value of the authorization will be your token so get your token and put it in so far we've specified the authorization but we have not specified the api itself so in the documentation you should see the host domain copy this and this will be exactly the same for everyone so this is going to be the server in the cloud that switchbot have to manage all these requests now we need a specific path based on that request because we're getting the device list let's just get this v.1 devices so copy this in and let's add that at the end so complete command will be curl minus h authorization and this is the actual what is the authorization so you can see this is wrapped up in the double quotes and after that you've got the api with the devices at the end so let's get all of this and depending on what operating system you're using either windows and mac you should have a terminal so this is what i'm using don't be scared by this this is quite straightforward what we're going to do is we're just going to be pasting in our command which is the curl command and we're just going to press enter if we've been successful we should have a message returned now this looks all gibberish so let me show you a better way of actually understanding this so from devices you should see an empty line copy this curly bracket and go right down until the curly bracket closes and we can copy that out now you can simply google a json format validator that's what i normally use and i will just put the information inside and click process you should see a valid green over here and this is going to beautifully format the message so i'm going to take the message out over here by using this button with a copy and i'm going to go back to my notepad i'm going to paste it in if you're not familiar with json messages don't worry we're going to explore it right now so scrolling down in the documentation we got the response we sent a message to the messenger and we've got a message back which is the response we've copied and formatted the response we've put in here this response here has a few keys the keys are status code message and body if you look at this carefully you'll see that status code body and message are all higher level information in fact if you have a text editor like my one you can actually collapse the message down so this is the basic format of the message the message has a status code a body and a message itself and these curly brackets define the style and the end of the message if you're wondering what is in body the following information you'll find that down below so if i expand body and i look at the first thing and you can see there's the famous two spaces it's a recurring theme if you've been watching my other videos and we have device list the device list provides a list of devices because i have more than one device in fact i can collapse on the device list and i can see i have the device list and the infrared remote list so we have two different lists in the device list we have device ids you can see over here the device name and the device type and the hub device id if you're getting value at this video remember to smash that like button and subscribe to the channel for many more home assistant and smart on gadgets tutorial i actually went back and you can see the switchbot humidifier and i paired it with the app and i've rerun the command and i should have the new device id so you can see the humidifier appeared and now have full devices linked which reflects what's in the app which is fantastic if you actually want to know what this actually means the enable cloud service in this example is boolean so boolean is a true or false value and in terms if the cloud service is enabled or not so if i were to disable the cloud service this would be false you can see there's a lot of values here in the device list that don't appear in my own response if you pay closely attention the documentation actually tells you that some of these for example are only available for curtin devices so if one day i get one of those curtain devices and add it in i'll actually be able to see that in the device list response now this table down below is telling us what could be in the infrared remote list i don't have any devices to show you hence i've got an empty array and at the end it shows us the status code and the message so we have the status code 100 that actually means success so these two actually link together now if we scroll down and we look at the device status we can actually pick a specific device id and we can actually find out the status of that device in our scratch pad notes we have the device id and the token so the token hasn't changed unless you've reset it and the device id we can basically use any device that we've got over here so i can pick the humidifier the room meter the hub or the bot so let me pick the meter to give you an example i'll pick this up i've got the device id over here okay so let's start building up this again we know we're going to need this at the end so i'm just going to copy and paste it in and i'm going to replace the device id with my own device id so remember to remove the curly brackets so you should have something like this now if you still have from the previous part the main curl we can copy and paste them we have this http part so we can get rid of the part at the end and ensure that we only have one slash so we have this over here complete so i'm going to get this whole long string paste it in and enter and we have a response back so i'm going to format that nicely for you cool so we've got the status code 100 remember that success we have message message success which is pretty much the same and over here in the body we have more information we have the device id the device type and the hub device id we also have the humidity value and the temperature value now with this information over here you can create template sensors in home assistant to extract the temperature and the humidity my fellow youtuber bt verde tinkerer actually made a complete guide on his channel for the switchboard devices he also shared the code in a github pull request which i'm going to link in the description down below now these instructions are pretty clear for me that i'm a homeless system pro if you're struggling a little bit i'm going to try and take some parts out of that code and try to explain it to you so this is the part of the code that i wanted to go into some detail because this is linked to the tutorial and what we were doing previously so you can see that in home assistant we can use the command line interface and we can create our own switchbot humidifier to control the switchbot and we can use things like command on and command off to turn it on and turn it off but how do we actually do that and how does that actually link up with the api worker we were doing previously if you look at the command on and the command off and if we just take this and put that in our scratch pad first bit over here is we're telling home assistant to go to the user folder bin folder and look for the curl library that allow us those commands that we do previously with the command line minus x gives us basically the whole command string the post is what we're going to be doing so if you remember from the documentation we can do posts and posts basically means we're taking an action we're not just reading we want to actually want the device to actually do something so we give it an actual command and the post uses this application json json as the content type and you can see that reflected over here content type application json so the json is the way that we're going to be communicating with the authorization is our api key so that will be this long key that we've got over here minus d is the command that we're going to be telling the device to take which is turn on so if you scroll right down you should be able to see command set for physical devices so depending on what device you have there'll be different commands but bot for example has turn off and turn on humidifier has turned off and turn on so the actual command is turned off and you can notice the off is a capital o so you're going to need to follow the same caps so we've got turn on in this example and over here at the end we have the same api switchbot but the device id would be the device that you have only here instead of using the slash status we're going to be using slash commands and you can see it right here the example is device device id slash commands and this is a post if you've got any questions drop a comment in the description down below i hope this helped you a lot if you want to learn more about home assistant i've got 12 more common system pro videos right here this is geoffron's model makers i'll see you next one ciao

Channel: Smart Home Makers

Views: 6,204

Keywords: home assistant, smart home, smart home makers, automation, home automation

Id: 34yD15jmeEA

Length: 12min 48sec (768 seconds)

Published: Tue Dec 07 2021