Use the REST Component to Add A Shelly Switch To Home Assistant
August 29, 2018Today on the hookup we’re going to learn how to use the REST api component to add a sensor or switch like the shelly2 to home assistant without the need for a device specific home assistant component.
In my last video about the Shelly 1 I mentioned that the shelly products have a well documented REST API that allows them to be controlled via HTTP commands instead of their app. I sort of mentioned it in passing since the focus of the shelly 1 is that it is so easy to install custom firmware using it’s external gpio headers.
But what if you’re happy with the firmware that it comes with, or what if you want to use some of the other devices from the shelly family? Or maybe you’ve got some other totally unique device in your home that happens to have a REST API? The great news is that home assistant has a very powerful RestAPI component already built in.
In this video I’m going to be setting up the Shelly2, which is a 2 channel relay with power monitoring that is designed to be installed behind a switch plate. It has similar properties to the shelly1, although it doesn’t have a 16A relay, instead it has two 10 amp relays. The other key difference between the shelly1 and the shelly2 is that the shelly2 doesn’t have GPIO pins pre-soldered to be able to easily change the firmware.
But as I mentioned in my last video, the included firmware on the shelly2 has an option to turn off the shelly cloud that in my testing seemed to effectively prevent the shelly from phoning home, and in my tests the shelly sent out only local multicast requests and the occasional request to a time sync server.
So how do you add a shelly device with the factory firmware into home assistant?
Lets start by setting up the shelly2 as a rest switch. According to the shelly rest api documentation the shelly will accept properly formatted http requests to turn the relays on and off. These http requests go to the ip address of the shelly, front slash, relay, front slash, and then the relay number, which would be 0 for relay 1 and 1 for relay 2. These requests need to be formatted as content-type: application/x-www-form-urlencoded. Basically that means that you could just put the whole url in your browser and turn the relay on and off, but we need to figure out how to format it as a POST request to work with the home assistant REST component.
When I’m testing out my commands for a REST api I like to use the chrome addon “advanced rest client” or ARC. You can select the type of request and the format of the request from dropdown boxes and it just makes the whole process much simpler. After a bit of fumbling around I was able to figure out the commands I needed to send I was ready to add them to my configuration.yaml file.
Since the shelly2 has two relays I set them up as two different switches, the only difference being the number in the resource URL that corresponds to the specific relay to turn on or off. I’ve posted this yaml in the description and the only thing you’ll need to update to get it working with your shelly is the ip address of the device. If you’re using the shelly1 the only relay that will be available is relay zero.
One major difference between MQTT switches and REST switches is that there is about 10 to 15 seconds of lag time from the time the switch is manually toggled to when the state updates in home assistant. This is due to the fact that it needs to send an HTTP GET request to the url to figure out if the switch is on or off, and doing so every second would cause an unnecessarily large amount of extra traffic on your network. There is never any lag in actually turning the switch on and off, only in showing the current state of the switch on the dashboard. However, if this update lag is unacceptable to you you can always add the parameter “scan interval” to your configuration file to tell it how often to issue a GET request to that switch. I wouldn’t recommend going crazy with it, but setting it to a value of 5 seconds or so shouldn’t be a problem since this device is on your local network.
The other cool feature of the shelly2 is that it offers relatively accurate power monitoring. This power monitoring will eventually be available in the custom Tasmota firmware as well, but as of publishing this video that integration is not finished yet. Thankfully, if that’s a feature that you are interested in, it’s not too tough to get it set up in home assistant using the REST sensor component and the factory shelly firmware.
To find out how the data from the shelly is formatted I’m going to use the ARC addon again and send a GET request to my shelly’s IP front slash status. You can see that sending this request results in a significant amount of data returned, but I’m only interested in the power meter which is down here under “meters”.
When formatting a REST component any JSON response that is returned will be saved by home assistant as the variable value_json. Since I want to know about the power meter I’d format my value template as value_json.meters. If I left it like that it would return all the information inside these curly brackets, but I don’t want all that. I specifically just want to return the value for power, which is the number of watts being consumed by the devices attached to the shelly2. In order to pull out that single value I need put each nested attribute into my value template. Specifically, you can see that the power attribute is first nested within the meters attribute, and then within the zero attribute. The correctly formatted yaml for the power meter sensor is in the description, and again, the only thing you need to change is the IP address of your device and you’ll be up and running.
Now that I’ve got my two switches and my sensor added to my configuration.yaml file I can restart home assistant and test them out. I haven’t wired this shelly2 into a wall switch yet because I’m still actively writing code for it, but I’ve temporarily got it hooked up to an extension cord for testing the power monitoring. Lets first check out switching via home assistant. You can see that switching the shelly2 on and off via the REST component is instant and using a switch an external switch also work and updates in home assistant as expected.
You can also see that this card shows the power consumption. In this lamp I’ve got two 60W incandescent bulbs hooked up to relay1, the power monitoring is pretty accurate, not perfect, but still pretty good. Who knows if those bulbs actually consume the amount of power marked on the packaging.
Because I set up this device with the factory firmware through the app I’ll need to use the app to set up any additional options like setting the switchmode. Thankfully the app is well designed and responsive. There’s also a web interface available by simply navigating to the IP address of the device.
Overall, I’m pleased with how well the shelly integrates with home assistant without making any changes. I’ll probably end up flashing Tasmota on all of my shelly devices anyways, but I really wanted to make this video for people who don’t feel the need to put custom firmware on every device in their house. The bin file I posted last week includes profile for the shelly2 that works without issue but doesn’t have power monitoring enabled, it’s a work in progress.
I will make a separate video on flashing the shelly2 with tasmota once the power monitoring gets worked out, but that may be a while. For the time being I’ve included a few pictures in the video description for the pinout on the shelly2 if you’re feeling brave. I was able to get my shelly2 flashed without any issue, but it was FAR from my first soldering project. You’ll need a thin tip on your iron and a steady hand to ensure you don’t mess up any of the surrounding components on the board.
The interest in last weeks video was crazy, and I know the guys at Shelly have been working hard to get the supply chain back up to get the Shelly1 to everyone who was interested. I’ve been told that since the shelly2 has been around longer that the supply is much greater. If you’re interested, you can order the shelly2 from amazon US for $19.90 with prime shipping, and remember that buying through the link in the description helps support my channel without costing you a penny. For my international viewers, I’d recommend ordering directly through the shelly website.
I’m also going to take a quick second thank my patrons for their support, it is honestly super motivating to know that you are enjoying my videos and I hope I can continue to put out content that you enjoy. If you’ve got any questions about anything from this video please leave a comment and I’ll get back to you ASAP. If you’re new to the channel and you enjoyed this video, please consider subscribing, and as always, thanks for watching the hookup.
US Links:
Shelly 1 Amazon US: https://amzn.to/2BzVDYs
Shelly 2 Amazon US: https://amzn.to/2PqtE0i
FTDI Adapter Amazon US: https://amzn.to/2PpcoZv
Jumper Wires Amazon US: https://amzn.to/2o0Moa1
UK Links:
Shelly Website: https://shelly.cloud/
Files
Home Assistant Shelly YAML: https://github.com/thehookup/shelly1tasmota/blob/master/Shelly2YAML.yaml
Shelly1Tasmota Bin File: https://github.com/thehookup/shelly1tasmota/blob/master/shelly1tasmota.bin
Shelly2 GPIO Pinout: https://github.com/thehookup/shelly1tasmota/blob/master/shelly%202%20gpio.jpg