628 lines
37 KiB
XML
628 lines
37 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<feed xmlns="http://www.w3.org/2005/Atom">
|
||
|
||
<title><![CDATA[Category: How-To | Home Assistant]]></title>
|
||
<link href="https://home-assistant.io/blog/categories/how-to/atom.xml" rel="self"/>
|
||
<link href="https://home-assistant.io/"/>
|
||
<updated>2016-07-17T08:54:18+00:00</updated>
|
||
<id>https://home-assistant.io/</id>
|
||
<author>
|
||
<name><![CDATA[Paulus Schoutsen]]></name>
|
||
|
||
</author>
|
||
<generator uri="http://octopress.org/">Octopress</generator>
|
||
|
||
|
||
<entry>
|
||
<title type="html"><![CDATA[PocketCHIP running Home Assistant]]></title>
|
||
<link href="https://home-assistant.io/blog/2016/07/06/pocketchip-running-home-assistant/"/>
|
||
<updated>2016-07-06T05:00:00+00:00</updated>
|
||
<id>https://home-assistant.io/blog/2016/07/06/pocketchip-running-home-assistant</id>
|
||
<content type="html"><![CDATA[<p><img src="https://home-assistant.io/images/blog/2016-07-pocketchip/pocketchip-logo.png" style="clear: right; border:none; box-shadow: none; float: right; margin-bottom: 12px;" width="200" /><br />
|
||
Over a year ago I participated in the <a href="https://www.kickstarter.com/projects/1598272670/chip-the-worlds-first-9-computer/description">kickstarter campaign</a> for “CHIP - The World’s First Nine Dollar Computer” by <a href="https://www.nextthing.co/">Next Thing Co.</a>. I went for the PocketCHIP because of the idea. Display, built-in storage (thus no need for SD cards), battery-powered, and a keyboard are pretty nice features. Last week a package arrives…</p>
|
||
|
||
<!--more-->
|
||
|
||
<p>Thanks to <a href="https://www.nextthing.co/">Next Thing Co.</a> and their CHIP which is actually 9 USD the space requirement for a single board computer has decreased. No Ethernet and HDMI output helped with that. But I guess that the next development cycle will allow us to put those boards in a matchbox including wired networking and a SATA interface.</p>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-07-pocketchip/size.png" />
|
||
Size comparison of a Cubieboard, OrangePi One, and CHIP.
|
||
</p>
|
||
|
||
<p>If you start using a PocketCHIP you will definitely look like a Blackberry or a GameBoy user. Typing is done with your thumbs :-)</p>
|
||
|
||
<p>First a couple of tweaks like setting up <code>sudo</code>, upgrading the existing installation, change passwords, enabling ssh, and removal of the annoying stuff then installation of Home Assistant. There is not much to tell…it’s straight-forward. For the sake of completeness below the notes about what I did.</p>
|
||
|
||
<p>A Debian installation is available by default. This means that some dependencies for Home Assistant are missing. I haven’t checked if a new build for the PocketCHIP would include them. So, after a <code>$ sudo apt-get update</code> installing those dependencies take a minute or two.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ sudo apt-get install python3-dev python3-pip python3-venv
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>As usual I run Python applications in a <a href="https://docs.python.org/3/library/venv.html">venv</a>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ pvenv ha
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Let’s activate the created environment.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ cd ha
|
||
$ source bin/activate
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>If you haven’t seen the next two commands already then you should visit our <a href="https://home-assistant.io/">frontsite</a>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ pip3 install homeassistant
|
||
$ hass --open-ui
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>With <code>surf</code> the browsing experience on the low-resolution display is not that great. Most smartphones, even very cheap ones, have touchscreens with higher resolutions. Nevermind, <a href="https://twitter.com/fabaff/status/748852317047418880"><code>midori</code></a> is not better.</p>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-07-pocketchip/pocketchip.png" />
|
||
PocketCHIP with Home Assistant frontend
|
||
</p>
|
||
|
||
<p>Well, with PocketCHIP and Home Assistant you could run your home automation on a 49 USD device with a touchscreen, an integrated USP, and a keyboard. With the GPIO available on top of the display you could even connect your PocketCHIP directly to sensors and actuators.</p>
|
||
|
||
]]></content>
|
||
</entry>
|
||
|
||
<entry>
|
||
<title type="html"><![CDATA[Using USB webcams with Home Assistant]]></title>
|
||
<link href="https://home-assistant.io/blog/2016/06/23/usb-webcams-and-home-assistant/"/>
|
||
<updated>2016-06-23T06:00:00+00:00</updated>
|
||
<id>https://home-assistant.io/blog/2016/06/23/usb-webcams-and-home-assistant</id>
|
||
<content type="html"><![CDATA[<p><img src="https://home-assistant.io/images/blog/2016-06-cranberry/motion.png" style="clear: right; border:none; box-shadow: none; float: right; margin-bottom: 12px;" width="200" /><br />
|
||
In the past month I was thinking about ways to integrate USB webcams into Home Assistant again. The main reason was that this would give those devices a second life and enable one to benefit from low-cost video surveillance. There are a couple of options available like <a href="http://www.pygame.org/hifi.html">pygame</a> or <a href="http://www.simplecv.org/">SimpleCV</a> but I never finished something. With the <a href="https://home-assistant.io/components/camera.local_file/">Local File camera platform</a> by <a href="https://github.com/Landrash">Landrash</a> and <a href="http://lavrsen.dk/foswiki/bin/view/Motion/WebHome">motion</a> you could integrate a local USB webcam with a few very easy steps.</p>
|
||
|
||
<p>In this blog post I am using a Fedora 24 (will most likely work on other distributions too) installation with Home Assistant 0.22.1 on a Foxconn nT-330i with an old <a href="http://support.logitech.com/en_us/product/quickcam-sphere-af">Logitech QuickCam Orbit AF</a> and a <a href="http://support.logitech.com/en_us/product/hd-webcam-c270">Logitech HD Webcam C270</a>. As a start only the Quickcam is used. No multi-camera setup for now.</p>
|
||
|
||
<!--more-->
|
||
|
||
<p>Check first if the your operating system lists your cameras.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ lsusb
|
||
[...]
|
||
Bus 002 Device 016: ID 046d:08cc Logitech, Inc. Mic (PTZ)
|
||
[...]
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The camera we are going to use is available at <code>/dev/video1</code>. The C270 is the one on <code>/dev/video0</code>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ ls -al /dev/video*
|
||
crw-rw----+ 1 root video 81, 0 Jun 23 08:05 /dev/video0
|
||
crw-rw----+ 1 root video 81, 1 Jun 23 08:36 /dev/video1
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>We need an additional software part to handle the cameras. <a href="http://lavrsen.dk/foswiki/bin/view/Motion/WebHome">motion</a> is capable of monitoring the video signal from USB and network cameras, do motion detection, and other nifty stuff like saving images, add text, or basic image manipulations. Make sure that you have the <a href="http://rpmfusion.org/">RPM Fusion respository</a> enabled.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ sudo dnf -y install motion
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>For our setup we need to modify the file <code>/etc/motion/motion.conf</code>. For now the most important parameters are <code>videodevice</code>, <code>snapshot_interval</code>, and <code>target_dir</code>. The other settings can be left to their defaults. We are going to use the device <code>/dev/video1</code>, use a 30 seconds interval, and set the path to <code>/tmp</code>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>[...]
|
||
###########################################################
|
||
# Capture device options
|
||
############################################################
|
||
|
||
# Videodevice to be used for capturing (default /dev/video0)
|
||
# for FreeBSD default is /dev/bktr0
|
||
videodevice /dev/video1
|
||
|
||
[..]
|
||
############################################################
|
||
# Snapshots (Traditional Periodic Webcam File Output)
|
||
############################################################
|
||
|
||
# Make automated snapshot every N seconds (default: 0 = disabled)
|
||
snapshot_interval 30
|
||
|
||
[...]
|
||
############################################################
|
||
# Target Directories and filenames For Images And Films
|
||
# For the options snapshot_, picture_, movie_ and timelapse_filename
|
||
# you can use conversion specifiers
|
||
# %Y = year, %m = month, %d = date,
|
||
# %H = hour, %M = minute, %S = second,
|
||
# %v = event, %q = frame number, %t = thread (camera) number,
|
||
# %D = changed pixels, %N = noise level,
|
||
# %i and %J = width and height of motion area,
|
||
# %K and %L = X and Y coordinates of motion center
|
||
# %C = value defined by text_event
|
||
# Quotation marks round string are allowed.
|
||
############################################################
|
||
|
||
# Target base directory for pictures and films
|
||
# Recommended to use absolute path. (Default: current working directory)
|
||
target_dir /tmp
|
||
|
||
[...]
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>It’s suggested that you adjust at least <code>width</code> and <code>height</code> to get a bigger image from your camera. If you are done, fire up <code>motion</code>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ sudo motion
|
||
[0] [NTC] [ALL] conf_load: Processing thread 0 - config file /etc/motion/motion.conf
|
||
[0] [ALR] [ALL] conf_cmdparse: Unknown config option "sdl_threadnr"
|
||
[0] [NTC] [ALL] motion_startup: Motion 3.3.0 Started
|
||
[0] [NTC] [ALL] motion_startup: Logging to file (/var/log/motion.log)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Your <code>target_dir</code> will start filling up with images from your camera. <code>motion</code> will create a symlink called <code>lastsnap.jpg</code> which always point to the latest snapshot. We will setup the <a href="https://home-assistant.io/components/camera.local_file/">Local File camera platform</a> to use this file.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">camera</span>:
|
||
- <span class="string"><span class="content">platform: local_file</span></span>
|
||
<span class="key">name</span>: <span class="string"><span class="content">Cranberry cam</span></span>
|
||
<span class="key">file_path</span>: <span class="string"><span class="content">/tmp/lastsnap.jpg</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-06-cranberry/cam.png" />
|
||
The “Cranberry cam” in action
|
||
</p>
|
||
|
||
<p>The machine with the attached USB camera will become a webcam server as well because <code>motion</code>’s built-in HTTP server is enabled by default. This means that you could connect your USB webcams to a different machine in your network, run <code>motion</code> there, adjust your firewall rules, and use Home Assistant to display the videos. Just check http://[IP of your webcam host]:8081/ to see the stream. This required more powerful hardware than using snapshots, of course.</p>
|
||
|
||
<p>In a scenario like this needs a <a href="https://home-assistant.io/components/camera.mjpeg/">Generic MJPEG IP Camera </a> in your <code>configuration.yaml</code> file.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">camera</span>:
|
||
- <span class="string"><span class="content">platform: mjpeg</span></span>
|
||
<span class="key">mjpeg_url</span>: <span class="string"><span class="content">http://[IP of your webcam host]:8081</span></span>
|
||
<span class="key">name</span>: <span class="string"><span class="content">Cranberry Live cam</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p><a href="http://lavrsen.dk/foswiki/bin/view/Motion/WebHome">motion</a> is a powerful tool and this blog post only showed two very simple use cases. Take a look at the <a href="http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionGuide">documentation</a> of <code>motion</code> to unleash its potential.</p>
|
||
|
||
]]></content>
|
||
</entry>
|
||
|
||
<entry>
|
||
<title type="html"><![CDATA[Static website]]></title>
|
||
<link href="https://home-assistant.io/blog/2016/04/07/static-website/"/>
|
||
<updated>2016-04-07T06:28:00+00:00</updated>
|
||
<id>https://home-assistant.io/blog/2016/04/07/static-website</id>
|
||
<content type="html"><![CDATA[<p>The frontend of Home Assistant is served with the help of a local web server. If you have <a href="/getting-started/devices/#customizing-devices-and-services">customized</a> your installation you already use this functionality. The content of your folder <code>www</code> in your Home Assistant configuration directory (<code>.homeassistant</code>) is available under <code>/local</code> (eg. <a href="https://localhost:8123/local">https://localhost:8123/local</a>).</p>
|
||
|
||
<p>But there is more you can do! You can not only host images for customization there but HTML files or even web applications including CSS and Javascript.</p>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-04-display/ha-display.png" />
|
||
</p>
|
||
|
||
<!--more-->
|
||
|
||
<p>In the past the buzz word “Smart mirror” was used a couple of times in our <a href="https://gitter.im/balloob/home-assistant">chatroom</a> and even made it into the <a href="https://github.com/home-assistant/home-assistant/issues/1392">issue tracker</a>. The existing solutions (<a href="http://docs.smart-mirror.io/">Smart mirror</a>, <a href="http://michaelteeuw.nl/tagged/magicmirror">MagicMirror</a>, and <a href="https://github.com/HannahMitt/HomeMirror">HomeMirror</a>) seems to be overkill if you already have Home Assistant running somewhere in your house or apartment. Why not simple display a web page served by Home Assistant on the tablet? No app and no Raspberry Pi running in the background.</p>
|
||
|
||
<p>There are plenty of ways to achieve this…<a href="/developers/rest_api/">RESTful API</a>, <a href="/developers/python_api/">Python API</a>, or one of the <a href="/components/#history">history components</a>. If it is to be a web page I’m using the <a href="/components/mqtt_eventstream/">MQTT Eventstream component</a> and <a href="http://git.eclipse.org/c/paho/org.eclipse.paho.mqtt.javascript.git/tree/src">mqttws31.js</a>.</p>
|
||
|
||
<p>The <a href="https://pypi.python.org/pypi/hbmqtt">HBMQTT</a> broker provides websockets support for MQTT and mqttws31.js included in web page gives you access to the MQTT messages. It’s a matter of minutes. OK, it took a little longer because I’m not a Javascript guy to create the software part that will show details about your environment. The source is available at <a href="https://github.com/fabaff/home-assistant-display">https://github.com/fabaff/home-assistant-display</a> and the screenshot above shows the result. I guess that every person who is familiar with Javascript would be able to reduce the amount of code and to make it more flexible. Well, it’s a only prototype and showcase to include an image in this blog post.</p>
|
||
|
||
<p>I hope that this little article could give you an idea of extending Home Assistant in an unconventional way.</p>
|
||
|
||
]]></content>
|
||
</entry>
|
||
|
||
<entry>
|
||
<title type="html"><![CDATA[Multi-room audio with Snapcast, Mopidy, and Home Assistant]]></title>
|
||
<link href="https://home-assistant.io/blog/2016/02/18/multi-room-audio-with-snapcast/"/>
|
||
<updated>2016-02-18T05:10:56+00:00</updated>
|
||
<id>https://home-assistant.io/blog/2016/02/18/multi-room-audio-with-snapcast</id>
|
||
<content type="html"><![CDATA[<p>Would you like to listen to music in every room in your home, controlled from one source? Then multi-room audio is for you.</p>
|
||
|
||
<p>Multi-room audio can be achieved by having a computer attached to speakers in every room. On each computer, services run to play and/or control the audio. With this DIY approach, the kind of computer and speakers is very much up to you. It could be your desktop computer with attached powered speakers, your HTPC hooked up to your TV and receiver, a Raspberry Pi with Amp or DAC, or even an Android device.</p>
|
||
|
||
<p>You’ll need two key software packages, besides Home Assistant. The first is <a href="https://www.mopidy.com/">Mopidy</a>, a music server that can play local files, or connect to streaming music services like Spotify. The second is <a href="https://github.com/badaix/snapcast/">Snapcast</a>, which enables synchronized audio streaming across your network. Both can be integrated into Home Assistant. Each room audio device will run an instance of the Snapcast client, and optionally a Mopidy instance. Your server will run a special instance of Mopidy and the Snapcast server.</p>
|
||
|
||
<p>Finally, you also need a player to control Mopidy. Any MPD-compatible player will work, and there are several <a href="https://docs.mopidy.com/en/latest/ext/web/#ext-web">Mopidy-only web-based options</a> available. On Android, <a href="https://play.google.com/store/apps/details?id=se.anil.remotedy">Remotedy</a> is particularly nice since you can access multiple Mopidy instances in one place.</p>
|
||
|
||
<p>Home Assistant will provide device status, and volume control for each room. If you want to play music in all your rooms (on all your clients), access the server instance of Mopidy. If you want to play music only in a specific room, access that specific Mopidy instance. If you’re using a web UI for Mopidy, you can add links to each instance in Home Assistant with the <a href="/components/weblink/">weblink</a> component.</p>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-02-snapcast/diagram.png" />
|
||
</p>
|
||
|
||
<!--more-->
|
||
|
||
<h2>Staging</h2>
|
||
|
||
<ul>
|
||
<li><a href="https://www.mopidy.com/">Install</a> Mopidy (2.0.0 or greater)</li>
|
||
<li><a href="https://github.com/badaix/snapcast/releases/">Download</a> and <a href="https://github.com/badaix/snapcast/tree/v0.5.0-beta-1#installation">Install</a> Snapcast (0.5.0 or greater)</li>
|
||
</ul>
|
||
|
||
<h2>Configure Mopidy</h2>
|
||
|
||
<p>Mopidy can be run with multiple configuration files, each extending the previous file. This is helpful when we’re running multiple instances with varying functionality.</p>
|
||
|
||
<h3>core.conf</h3>
|
||
<p>The core configuration is shared between all instances:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>[mpd]
|
||
hostname = ::
|
||
|
||
[http]
|
||
hostname = ::
|
||
|
||
[audio]
|
||
output = alsasink
|
||
|
||
[spotify]
|
||
username = <redacted>
|
||
password = <redacted>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3>local.conf</h3>
|
||
<p>Add the local configuration on computers that have local media files:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>[local]
|
||
media_dir = <your/music/here>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3>snapcast.conf</h3>
|
||
<p>Finally, the Mopidy instance that connects with Snapcast needs special configuration. Run on a different port to avoid conflicts if you have a second Mopidy instance running on your computer. The audio output is sent to a named pipe - Snapcast will read from there. Note that you may have to adjust the audio output attribute depending on your system and audio sources.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>[mpd]
|
||
hostname = ::
|
||
port = 6601
|
||
|
||
[http]
|
||
hostname = ::
|
||
port = 6681
|
||
|
||
[audio]
|
||
output = audioresample ! audio/x-raw,rate=48000,channels=2,format=S16LE ! audioconvert ! wavenc ! filesink location=/tmp/snapfifo
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Run Mopidy</h2>
|
||
|
||
<p>To run a room-specific instance:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ mopidy --config $CONF_DIR/core.conf
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>To run a room-specific instance with local media:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ mopidy --config $CONF_DIR/core.conf:$CONF_DIR/local.conf
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>To run the special Snapcast-connected instance (with local media):</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ mopidy --config $CONF_DIR/core.conf:$CONF_DIR/local.conf:$CONF_DIR/snapcast.conf
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Run Snapcast</h2>
|
||
|
||
<p>Start the <code>snapserver</code> on the same server running Mopidy with the snapcast configuration.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ snapserver # or use systemd
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Start the <code>snapclient</code> on computers that will be playing audio.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ snapclient # or use systemd, add -h <server host> if necessary
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Configure Snapcast</h2>
|
||
|
||
<p>There are a number of snapcast configuration options, but the one relevant to Home Assistant is the client names. You can set them in the snapserver configuration file, by default located at <code>~/.config/Snapcast/settings.json</code>. Only edit this file while the <code>snapserver</code> is not running. Modify the <code>name</code> JSON value to your liking - this is how the client will be named in Home Assistant.</p>
|
||
|
||
<h2>Configure Home Assistant</h2>
|
||
|
||
<p>Use the <a href="/components/media_player.mpd/">mpd</a> and <a href="/components/media_player.snapcast/">snapcast</a> components. Optionally, use <a href="/components/weblink/">weblink</a> to provide easy access to a Mopidy web UI.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">media_player</span>:
|
||
- <span class="string"><span class="content">platform: snapcast</span></span>
|
||
<span class="key">host</span>: <span class="string"><span class="content">xxxxx</span></span>
|
||
- <span class="string"><span class="content">platform: mpd</span></span>
|
||
<span class="key">server</span>: <span class="string"><span class="content">xxxx</span></span>
|
||
<span class="key">location</span>: <span class="string"><span class="content">Multi-Room Controller</span></span>
|
||
- <span class="string"><span class="content">platform: mpd</span></span>
|
||
<span class="key">server</span>: <span class="string"><span class="content">xxx</span></span>
|
||
<span class="key">location</span>: <span class="string"><span class="content">Room 1</span></span>
|
||
|
||
<span class="key">weblink</span>:
|
||
<span class="key">entities</span>:
|
||
- <span class="string"><span class="content">name: Multi-Room Player</span></span>
|
||
<span class="key">url</span>: <span class="string"><span class="content">xxxx</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
]]></content>
|
||
</entry>
|
||
|
||
<entry>
|
||
<title type="html"><![CDATA[Smarter SmartThings with MQTT and Home Assistant]]></title>
|
||
<link href="https://home-assistant.io/blog/2016/02/09/smarter-smart-things-with-mqtt-and-home-assistant/"/>
|
||
<updated>2016-02-09T07:44:00+00:00</updated>
|
||
<id>https://home-assistant.io/blog/2016/02/09/Smarter-Smart-Things-with-MQTT-and-Home-Assistant</id>
|
||
<content type="html"><![CDATA[<p><em>This is a guest post by Home Assistant users <a href="https://github.com/jer">Jeremiah Wuenschel</a> and <a href="https://github.com/stjohnjohnson">St. John Johnson</a>.</em></p>
|
||
|
||
<p>So you own a <a href="http://smartthings.com">SmartThings</a> 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 <strong>anything.</strong> 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 <a href="https://www.reddit.com/r/homeautomation">reddit</a> and discovered the amazingness that is Home Assistant! A solution that offered dashboards, graphs, working support for Nest, and REAL EASY automation!</p>
|
||
|
||
<p>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?</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p class="img">
|
||
<img src="https://home-assistant.io/images/blog/2016-02-smartthings/splash.png" />
|
||
</p>
|
||
|
||
<!--more-->
|
||
|
||
<h2>Glossary</h2>
|
||
|
||
<p>This is going to be a pretty detailed tutorial on setting up our SmartThings bridge. However, there are a couple key terms that <em>might</em> be new to you:</p>
|
||
|
||
<ul>
|
||
<li><a href="https://en.wikipedia.org/wiki/MQTT">MQTT</a>: A lightweight message protocol for listening and publishing events that happen. Many home automation platforms have built in support for this <a href="/components/mqtt/">(especially Home Assistant)</a>.</li>
|
||
<li><a href="https://www.docker.com/">Docker</a>: 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.</li>
|
||
</ul>
|
||
|
||
<h2>Setting up the Bridge</h2>
|
||
|
||
<h3>MQTT</h3>
|
||
|
||
<p>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 <a href="http://mosquitto.org/">MQTT</a> <a href="https://github.com/emqtt/emqttd">brokers</a> available in Open Source land. We chose <a href="http://www.mosca.io/">Mosca</a> for its simplicity.</p>
|
||
|
||
<p>There is very little you need to do to get Mosca running. The easiest approach is to use <a href="https://www.docker.com/">Docker</a>, and run a command like the following:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ docker run \
|
||
-d \
|
||
--name="mqtt" \
|
||
-v /opt/mosca:/db \
|
||
-p 1883:1883 \
|
||
matteocollina/mosca
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>This will start Mosca up inside of a docker container, while keeping persistent storage for Mosca in <code>/opt/mosca</code>. The default configuration is the only thing we need to get things up and running.</p>
|
||
|
||
<p>If you don’t want to mess with Docker and can get node.js installed without trouble, the <a href="https://github.com/mcollina/mosca#standalone">standalone</a> instructions are all you need.</p>
|
||
|
||
<h3>MQTT Bridge</h3>
|
||
|
||
<p>This is the small piece of magic that bridges the gap between MQTT and SmartThings. It is a node.js app, and like Mosca it is probably easiest to install with Docker:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ docker run \
|
||
-d \
|
||
--name="mqtt-bridge" \
|
||
-v /opt/mqtt-bridge:/config \
|
||
-p 8080:8080 \
|
||
stjohnjohnson/smartthings-mqtt-bridge
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The code for this bridge is <a href="https://github.com/stjohnjohnson/smartthings-mqtt-bridge">on Github</a> if you want to start it up independently.</p>
|
||
|
||
<p>The MQTT Bridge only needs to know where your MQTT broker lives. If you are using these docker commands as-is, edit <code>/opt/mqtt-bridge/config.yml</code> to look like this:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="head"><span class="head">---</span></span>
|
||
<span class="key">mqtt</span>:
|
||
<span class="key">host</span>: <span class="string"><span class="content"><IP of the host></span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Restart the bridge, and you are ready to go:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ docker restart mqtt-bridge
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3>SmartThings Device</h3>
|
||
|
||
<p>The next step (and possibly the most confusing) is the device type. Go to the <a href="https://graph.api.smartthings.com/ide/devices">Smart Things Device IDE</a> and <code>Create New Device Handler</code>. Choose <code>From Code</code> and paste in the <a href="https://github.com/stjohnjohnson/smartthings-mqtt-bridge/blob/master/devicetypes/stj/mqtt-bridge.src/mqtt-bridge.groovy">MQTT Bridge Device Code</a>. Click <code>Save</code>, <code>Publish</code>, and then <code>For Me</code>.</p>
|
||
|
||
<p>Now to install your new Device Handler. Go back to <code>My Devices</code> in the IDE, and click <code>New Device</code>. 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 <code>MQTT Bridge</code>. Fill in the other boxes however you like.</p>
|
||
|
||
<p>Go back to <code>My Devices</code>, and click on your new device in the list. This will bring up a page that allows you to edit your device’s Preferences. Click <code>edit</code> and fill in the 3 pieces of information it asks for.</p>
|
||
|
||
<ul>
|
||
<li>MQTT Bridge IP Address: <IP address of the MQTT Bridge from the previous step></li>
|
||
<li>MQTT Bridge Port: <8080 if you have changed nothing in the previous commands></li>
|
||
<li>MQTT Bridge MAC Address: <Mac address of machine running the Bridge code></li>
|
||
</ul>
|
||
|
||
<p>This will create the link between SmartThings and the MQTT Bridge.</p>
|
||
|
||
<h3>SmartThings App</h3>
|
||
|
||
<p>The last step is to setup the SmartApp. After this, any registered devices will start sending their events to MQTT.</p>
|
||
|
||
<p>Go to the <a href="https://graph.api.smartthings.com/ide/apps">Smart App IDE</a>. Click <code>New SmartApp</code>, followed by <code>From Code</code>. Paste in the <a href="https://github.com/stjohnjohnson/smartthings-mqtt-bridge/blob/master/smartapps/stj/mqtt-bridge.src/mqtt-bridge.groovy">MQTT Bridge SmartApp code</a> and click <code>Save</code>. Click <code>Publish</code> and then <code>For Me</code>. In the SmartThings mobile app, add the new SmartApp and configure it with your devices and MQTT Bridge device. Clicking <code>done</code> will subscribe SmartThings to your MQTT broker and begin 2-way propagation of events.</p>
|
||
|
||
<h3>Configure Home Assistant</h3>
|
||
|
||
<p>To add SmartThings devices to Home Assistant over MQTT, first enable MQTT in Home Assistant:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">mqtt</span>:
|
||
<span class="key">broker</span>: <span class="string"><span class="content">localhost</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Replace <code>localhost</code> with the location of the running MQTT Broker. Devices from the MQTT Bridge are published to the path <code>smartthings/<Device Name>/<Atribute></code></p>
|
||
|
||
<p>For example, my Dimmer Z-Wave Lamp is called “Fireplace Lights” in SmartThings. The following topics are published:</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Topic</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>smartthings/Fireplace Lights/level</td>
|
||
<td>Brightness (0-99)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>smartthings/Fireplace Lights/switch</td>
|
||
<td>Switch State (on/off)</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Here is an example Home Assistant config:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">switch</span>:
|
||
<span class="key">platform</span>: <span class="string"><span class="content">mqtt</span></span>
|
||
<span class="key">name</span>: <span class="string"><span class="delimiter">"</span><span class="content">Fireplace Lights</span><span class="delimiter">"</span></span>
|
||
<span class="key">state_topic</span>: <span class="string"><span class="delimiter">"</span><span class="content">smartthings/Fireplace Lights/switch</span><span class="delimiter">"</span></span>
|
||
<span class="key">command_topic</span>: <span class="string"><span class="delimiter">"</span><span class="content">smartthings/Fireplace Lights/switch</span><span class="delimiter">"</span></span>
|
||
<span class="key">brightness_state_topic</span>: <span class="string"><span class="delimiter">"</span><span class="content">smartthings/Fireplace Lights/level</span><span class="delimiter">"</span></span>
|
||
<span class="key">brightness_command_topic</span>: <span class="string"><span class="delimiter">"</span><span class="content">smartthings/Fireplace Lights/level</span><span class="delimiter">"</span></span>
|
||
<span class="key">payload_on</span>: <span class="string"><span class="delimiter">"</span><span class="content">on</span><span class="delimiter">"</span></span>
|
||
<span class="key">payload_off</span>: <span class="string"><span class="delimiter">"</span><span class="content">off</span><span class="delimiter">"</span></span>
|
||
<span class="key">retain</span>: <span class="string"><span class="content">true</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>We recommend <code>retain: true</code> for every MQTT device in order to keep states in sync when things become disconnected.</p>
|
||
|
||
<p>Start digging through the <a href="/components/mqtt/">MQTT Components</a> in Home Assistant to find which components map to the new events being published to MQTT.</p>
|
||
|
||
<h3>Configuring with Docker-Compose</h3>
|
||
|
||
<p>Our personal preference for starting the whole suite of software is to use a single Docker-Compose file. Just create a file called <code>docker-compose.yml</code> like this:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">mqtt</span>:
|
||
<span class="key">image</span>: <span class="string"><span class="content">matteocollina/mosca</span></span>
|
||
<span class="key">ports</span>:
|
||
- <span class="string"><span class="content">1883:1883</span></span>
|
||
|
||
<span class="key">mqttbridge</span>:
|
||
<span class="key">image</span>: <span class="string"><span class="content">stjohnjohnson/smartthings-mqtt-bridge</span></span>
|
||
<span class="key">volumes</span>:
|
||
- <span class="string"><span class="content">./mqtt-bridge:/config</span></span>
|
||
<span class="key">ports</span>:
|
||
- <span class="string"><span class="content">8080:8080</span></span>
|
||
<span class="key">links</span>:
|
||
- <span class="string"><span class="content">mqtt</span></span>
|
||
|
||
<span class="key">homeassistant</span>:
|
||
<span class="key">image</span>: <span class="string"><span class="content">homeassistant/home-assistant:latest</span></span>
|
||
<span class="key">ports</span>:
|
||
- <span class="string"><span class="content">80:80</span></span>
|
||
<span class="key">volumes</span>:
|
||
- <span class="string"><span class="content">./home-assistant:/config</span></span>
|
||
- <span class="string"><span class="content">/etc/localtime:/etc/localtime:ro</span></span>
|
||
<span class="key">links</span>:
|
||
- <span class="string"><span class="content">mqtt</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>This will start home-assistant, MQTT, and the Bridge, in dependency order. All config can reference the name of the docker container instead of using IP addresses (e.g. mqtt for the broker host in Home Assistant).</p>
|
||
|
||
<h3>How it works</h3>
|
||
|
||
<p><strong>HTTP Endpoint</strong>: 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.</p>
|
||
|
||
<p><strong>Custom Device Type:</strong> 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:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>Z-Wave Switch |
|
||
Zigbee motion sensor |<---> Bridge App <---> Bridge Device Type <---> <Local network>
|
||
Z-Wave light bulb |
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>Here is the final sequence of events:</p>
|
||
|
||
<p class="img">
|
||
<a href="https://home-assistant.io/images/blog/2016-02-smartthings/SmartThings-HomeAssistant.png">
|
||
<img src="https://home-assistant.io/images/blog/2016-02-smartthings/SmartThings-HomeAssistant.png" alt="SmartThings Bridge Sequence" />
|
||
</a>
|
||
SmartThings Bridge Sequence
|
||
</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3>Future Improvements</h3>
|
||
<ul>
|
||
<li><strong>Raspberry pi</strong>: 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.</li>
|
||
<li><strong>Authentication for MQTT</strong>: 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.</li>
|
||
<li><strong>Authentication for MQTT Bridge</strong>: Right now the bridge expects that anyone subscribing is the SmartThings hub. This could use proper authentication.</li>
|
||
</ul>
|
||
|
||
]]></content>
|
||
</entry>
|
||
|
||
</feed>
|