jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 09:17:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Just some start to changes

Browse Source
This commit is contained in:
St. John Johnson 2016-02-08 08:29:28 -08:00
parent d012717b83
commit f4d3666d7a
1 changed files with 37 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
source/_posts/2016-02-09-Smarter-Smart-Things-with-MQTT-and-Home-Assistant.markdown
View File

@ -13,36 +13,28 @@ og_image: /images/blog/2016-02-09-Smarter-Smart-Things-with-MQTT-and-Home-Assist
_This is a guest post by Home Assistant users [Jeremiah Wuenschel](https://github.com/jer) and [St. John Johnson](https://github.com/stjohnjohnson)._
# SmartThings
### Why combine SmartThings and Home Assistant?
So you own a [SmartThings][smartthings] Hub. You probably bought it when you were looking to get into the whole Home Automation hobby because it worked with pretty much everything and offered you the ability to automate __anything.__ After a week of ownership, you realized that building dashboards and automating required writing way more Groovy then you expected. Then one day you were browsing [reddit][r/homeautomation] and discovered the amazingness that is Home Assistant! A solution that offered dashboards, graphs, working support for Nest, and REAL EASY automation!
You spent your weekend getting everything set up, showing it off to your significant other, but in the end you got stumped when it came to integrating with all your existing SmartThings toys. What do I do now? Should I buy another hub? Should I just buy a z-wave stick?
### Bridge Design
**HTTP Endpoint**: There are really only 2 ways to communicate with the SmartThings hub that we could find. The easiest approach is to create a RESTful SmartApp authenticated with OAuth that provides state changes via HTTP directly. This approach is pretty straightforward to implement, but it requires communication with the SmartThings cloud service, and can't be done entirely on your LAN. We hoped to keep all communication internal, and came up with a second approach.
That's where we came in. We wanted a solution that can bridge the awesomeness of Home Assistant with the SmartThings hub that works with almost everything.
**Custom Device Type:** SmartThings custom device types allow developers to define handlers for HTTP events received directly over the local network by the SmartThings hub. Messages received are authenticated by MAC address, and can contain arbitrary strings in their payload. Since a Device Type is only ever tied to a single device, we need to add a SmartApp to the mix in order to translate events between individual devices and our special Home Assistant Bridge device. Here is what we have so far:
```
Z-Wave Switch |
Zigbee motion sensor |<---> Bridge App <---> Bridge Device Type <---> <Local network>
Z-Wave light bulb |
```
## Glossary
On the Home Assistant side, there is a powerful platform available based on the MQTT lightweight message bus protocol. Everything from lights to switches to temperature sensors can be defined in Home Assistant as an MQTT component, so it makes for a convenient integration point. This requires an MQTT broker for handling the message bus, and one last piece to translate between the HTTP that SmartThings supports and MQTT.
This is going to be a pretty detailed tutorial on setting up our SmartThings bridge. However, there are a couple key terms that __might__ be new to you:
Here is the final sequence of events:
- [MQTT][mqtt]: A lightweight message protocol for listening and publishing events that happen. Many home automation platforms have built in support for this [(especially Home Assistant)][mqtt-ha].
- [Docker][docker]: A tool for running applications that are self-contained. No need for installing any dependencies or worrying about conflicts. Installs easily on Linux and OSX.
![SmartThings Bridge Sequence]("/images/blog/2016-02-smartthings/SmartThings-HomeAssistant.png" "SmartThings Bridge Sequence")
There are a lot of stops along the way for these events, but each piece is a simple translation layer to shuttle the events between systems.
## Setting up the MQTT bridge
## Setting up the Bridge
### MQTT
Assuming that you already have Home Assistant and Smart Things running, you wil first want to get an MQTT broker running. There are a handful of [MQTT][mosquitto] [brokers][emqttd] available in Open Source land. We chose [Mosca][mosca] for its simplicity.
Assuming that you already have Home Assistant and Smart Things running, you will first want to get an MQTT broker running. There are a handful of [MQTT][mosquitto] [brokers][emqttd] available in Open Source land. We chose [Mosca][mosca] for its simplicity.
There is very little you need to do to get Mosca running. The easiest approach is to install [Docker][docker], and run a command like the following:
There is very little you need to do to get Mosca running. The easiest approach is to use [Docker][docker], and run a command like the following:
$ docker run \
-d \
@ -51,7 +43,6 @@ There is very little you need to do to get Mosca running. The easiest approach i
-p 1883:1883 \
matteocollina/mosca
This will start Mosca up inside of a docker container, while keeping persistent storage for Mosca in `/opt/mosca`. The default configuration is the only thing we need to get things up and running.
If you don't want to mess with Docker and can get node.js installed without trouble, the [Standalone][mosca-standalone] instructions are all you need.
@ -81,9 +72,9 @@ Restart the bridge, and you are ready to go:
$ docker restart mqtt-bridge
### SmartThing
### SmartThings Device
The next step is the device type. Go to the [Smart Things Device IDE][ide-dt] and `Create New Device Handler`. Choose `From Code` and paste in the [MQTT Bridge Device Code][devicetype]. Click Save.
The next step (and possibly the most confusing) is the device type. Go to the [Smart Things Device IDE][ide-dt] and `Create New Device Handler`. Choose `From Code` and paste in the [MQTT Bridge Device Code][devicetype]. Click `Save`, `Publish`, and then `For Me`.
Now to install your new Device Handler. Go back to `My Devices` in the IDE, and click `New Device`. Enter a name, and pick any random set of characters for the Device Network Id (this will automatically update later). For Type, scroll to the bottom of the list and find your newly created `MQTT Bridge`. Fill in the other boxes however you like.
@ -95,11 +86,11 @@ Go back to `My Devices`, and click on your new device in the list. This will bri
This will create the link between SmartThings and the MQTT Bridge.
### SmartApp
### SmartThings App
The last step is to setup the SmartApp. After this, any registered devices will start sending their events to MQTT.
Go to the [Smart App IDE][ide-app]. Click `New SmartApp`, followed by `From Code`. Paste in the [MQTT Bridge SmartApp code][smartapp] and click `save`. In the SmartThings mobile app, add the new SmartApp and configure it with your devices and MQTT Bridge device. Clicking `done` will subscribe SmartThings to your MQTT broker and begin 2-way propagation of events.
Go to the [Smart App IDE][ide-app]. Click `New SmartApp`, followed by `From Code`. Paste in the [MQTT Bridge SmartApp code][smartapp] and click `Save`. Click `Publish` and then `For Me`. In the SmartThings mobile app, add the new SmartApp and configure it with your devices and MQTT Bridge device. Clicking `done` will subscribe SmartThings to your MQTT broker and begin 2-way propagation of events.
### Configure Home Assistant
@ -172,6 +163,25 @@ homeassistant:
This will start home-assistant, MQTT, and the Bridge, in dependency order. All config can reference the name of the docker container instead of localhost (e.g. mqtt for the broker host in Home Assistant).
### How it works
**HTTP Endpoint**: There are really only 2 ways to communicate with the SmartThings hub that we could find. The easiest approach is to create a RESTful SmartApp authenticated with OAuth that provides state changes via HTTP directly. This approach is pretty straightforward to implement, but it requires communication with the SmartThings cloud service, and can't be done entirely on your LAN. We hoped to keep all communication internal, and came up with a second approach.
**Custom Device Type:** SmartThings custom device types allow developers to define handlers for HTTP events received directly over the local network by the SmartThings hub. Messages received are authenticated by MAC address, and can contain arbitrary strings in their payload. Since a Device Type is only ever tied to a single device, we need to add a SmartApp to the mix in order to translate events between individual devices and our special Home Assistant Bridge device. Here is what we have so far:
```
Z-Wave Switch |
Zigbee motion sensor |<---> Bridge App <---> Bridge Device Type <---> <Local network>
Z-Wave light bulb |
```
On the Home Assistant side, there is a powerful platform available based on the MQTT lightweight message bus protocol. Everything from lights to switches to temperature sensors can be defined in Home Assistant as an MQTT component, so it makes for a convenient integration point. This requires an MQTT broker for handling the message bus, and one last piece to translate between the HTTP that SmartThings supports and MQTT.
Here is the final sequence of events:
![SmartThings Bridge Sequence]("/images/blog/2016-02-smartthings/SmartThings-HomeAssistant.png" "SmartThings Bridge Sequence")
There are a lot of stops along the way for these events, but each piece is a simple translation layer to shuttle the events between systems.
### Future Improvements
- **Raspberry pi**: There is a lot of interest in getting this running on the Raspberry Pi. It only requires binaries compiled for ARM, so we plan to get ARM-compatible versions of the containers going at some point.
- **Authentication for MQTT**: At the moment, the MQTT bridge doesn't understand how to authenticate to MQTT, so only unauthenticated MQTT is supported. This is mitigated to some degree if you use our Docker Compose config, because MQTT's port is not actually shared publicly.
@ -189,3 +199,6 @@ This will start home-assistant, MQTT, and the Bridge, in dependency order. All c
[ide-app]: https://graph.api.smartthings.com/ide/apps
[smartapp]: https://github.com/stjohnjohnson/smartthings-mqtt-bridge/blob/master/smartapps/stj/mqtt-bridge.src/mqtt-bridge.groovy
[mqtt-ha]: https://home-assistant.io/components/mqtt/
[smartthings]: http://smartthings.com
[r/homeautomation]: https://www.reddit.com/r/homeautomation
[mqtt]: https://en.wikipedia.org/wiki/MQTT