This week I got a Wio Link prototype from a friend at Seeed Studio. It is an ESP8266-based little Internet of Things board with 6 Grove connectors for easy device connectivity, wifi networking, and controlled over an app & the Internet. For a quick project I wanted to hook it up with Home Assistant, an open source home automation platform that I read a lot about lately. The main focus was to have a first impression of both parts, and build up some experience for future, more serious projects.
The target solution: light up an LED if a particular person is at home location. Sort of a basic alarm system, though notice that the location of the LED was not mentioned – it can actually be anywhere in the world, as long as there’s Internet connectivity.
I’ve used the Wio Link, a Grove LED light, an Olimex OLinuXino Lime2 board running ArchLinux for the server, and a Buffalo router with DD-WRT system installed.
Wio Link
Wio Link was introduced in Seeed’s Kickstarter campaign, where they have raised more than 8x of their original target. It looks like a neat little board, and was happy to try out when I got my hands on one.
Their wiki page has quite a bit of information, so it was easy to get started. Connect to power, hold down the configure button till the LED lights up in a “breathing” pattern, connect through their Wio Link app, set up the wireless network settings and so on. Once connected, can define what kind of devices are attached to the board, and it looks like most of Grove devices are represented there. I only had a Grove LED at hand, so added it (“Generic Digital Output”), updated it, which created a new firmware and pushed onto the device.
The first update took a couple of minutes, but it’s pretty straightforward. The device then also has an API link, which brings up a web page with all the options to query, control, and reset the attached accessories (in my case that’s the one digital output).
The API is pretty simple and usable, though definitely not perfect (will come back to this).
Since manual switching the light on and off worked like the charm, the next step was to enable automatic switching by the presence detection within the home automation system.
Home Assistant
Home Assistant is an open source home automation system written in Python. There’s a lot to like about it, and a lot of people are checking it out since a number of other, closed system providers are shutting down their services. On the other hand, figuring out the configuration to implement the automation steps I came up with is far from trivial…
Setting up Home Assistant is pretty simple. Create a new directory, add a new virtualenv environment, and install home assistant (I’ve added some bonus modules that the logs recommended):
$ virtualenv env Using base prefix '/usr' New python executable in /tmp/env/bin/python3 Also creating executable in /tmp/env/bin/python Installing setuptools, pip, wheel...done. $ source env/bin/activate (env) $ pip install homeassistant ... (env) $ pip install python-Levenshtein (env) $ pip install colorlog (env) $ hass --open-ui
Next step is adding the actual components (the pieces of the home automation). I’ve implemented the Wio Link light as a Command Line Switch. It has two commands for “on” and “off”, plus an extra for checking the on/off status (this latter is a very nice touch, and works well checking whether the switch took effect). In the configuration.yaml file in the ~/.homeassistant directory:
switch:
platform: command_line
switches:
presence_light:
name: Home Presence Light
oncmd: "/usr/bin/curl -s -X POST https://iot.seeed.cc/v1/node/GenericDOutD0/onoff/1?access_token=<token>"
offcmd: "/usr/bin/curl -s -X POST https://iot.seeed.cc/v1/node/GenericDOutD0/onoff/0?access_token=<token>"
statecmd: "/usr/bin/curl -s https://iot.seeed.cc/v1/node/GenericDOutD0/onoff_status?access_token=<token>"
value_template: '{{ value_json.onoff == 1 }}'
group:
remote:
- switch.home_presence_lightHere the URLs are coming straight from Wio Link API page, and you have to add your token value and the correct channels instead of GenericDOutD0 if you plugged your light into a different connector than me. I’ve also removed their -k command line parameter (allow insecure SSL connection), and added -s (silent mode). The last section starting with “group” is not really necessary, but could group devices to be controlled together.
Adding the presence detection through DD-WRT is just the same as in their example configuration, obviously add your own parameters.
device_tracker: platform: ddwrt host: 192.168.x.y username: <user> password: <password> interval: 10
I don’t like that username/password is in clear text, so better protect your Home Assistant device and this configuration file!
By the default configuration, after restarting Home Assistant this presence detection module will create a known_devices.yaml file in the ~/.homeassistant/ directory and add all new devices (see the device tracker component page for some more info). Here I had my smartphone, after connecting it to the home network.
xxxxxxxxxxxx: name: HTC One M9 mac: xx:xx:xx:xx:xx:xx picture: http://www.gravatar.com/avatar/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx track: yes hide_if_away: no
That file then can be edited, for example adding device name, disabling tracking for some discovered devices (eg. the small server running the Home Assistant server itself), and adding an image. I’ve added an image using a Gravatar link, where the xxxx section is just the md5 hash of your email, get it by.
echo -n "my@email.com" | md5sum -
Alternatively, this week’s update added local file support too, as it was discussed in the Home Assistant blog, so files in the ~/.homeassistant/www/ can be linked through the http://127.0.0.1/local/ path, so no online link is necessary (but I think Gravatar is a good unified approach).
After all this, the control interface will look something like this (the Sun is added as I had my home’s longitude/latitude information in the configuration). My icon will show Home/Away status, and clicking the switch on the presence light will trigger the light on the Wio Link.
The final step is the automation. This was the hardest step, as the Home Assistant automation documentation and their cookbook is pretty shallow, and often feel confusing. In the end, one working result is this pair of rules, which turn the light on when status change to home , and turn it off when changes to not_home for that particular device.
automation 1:
trigger:
platform: state
entity_id: device_tracker.xxxxxxxxxxxx
to: 'home'
action:
service: homeassistant.turn_on
entity_id: group.remote
automation 2:
trigger:
platform: state
entity_id: device_tracker.xxxxxxxxxxxx
to: 'not_home'
action:
service: homeassistant.turn_off
entity_id: group.remote
I’m sure it can be done differently, but I’m also just glad it works, as it took quite a few hours of checking documentation, trying things, and reading the Home Assistant source code to come up with a working solution.
It functions pretty well, though presence (arriving) is detected quicker than absence (going away), I guess that’s part of detection method and certain timeouts within DD-WRT.
Lessons
I quite like how it all turned out, and I’ve learned a lot along the way, in the about 5-6 hours it took to pull everything together for the first time.
There will always be bugs. When trying to read the Wio Link LED’s status, first I was trying to implement it as a RESTful Binary Sensor. Took a while to find that that component had a breaking bug. I’ve made a patch, but haven’t sent it upstream yet, because Home Assistant makes me fill out so much information before a pull request can be even considered. To make it worthwhile, I’ll review things and send the fix later.
Not all the Wio Link API design is great. In particular, turning the light on/off are empty POST request to two different API endpoints! That’s not really REST at all. I think the way it should have been is using the same API endpoint (one single URL), and the setting sent over the POST data. Because of peculiarity, I couldn’t implement the Wio Link control over the RESTful Switch component, which requires a single endpoint.
Since the Wio Link can be placed anywhere where there’s internet connection, this home automation system can incorporate data from anywhere, sending or receiving. Can have an LCD screen miles away that displays metrics from your home. Can incorporate external sensors, actuators, the whole shebang. This makes more of a “local area” or even “wide area” automation network, not just “home”. Let your imagination run amok!
The Home Assistant documentation is really lacking for me, and I say that while every component has code samples and there are a lot of cookbook samples around. The problem is that there’s very little consistency, there’s no overview, and the options are not documented extensively. There’s no list of “these are all the options and possible values”, and there are no “these are all the ways you can do this thing”. In the end, one needs a lot of trial and error and monumental amount of head scratching! (Use the Source, Luke!) All this basically means that Home Assistant is the “worst documented project that I’m the most excited about“. :) Fortunately the Home Assistant website’s source is also on Github and can submit updates if I figure out how to explain things better.
Creating automation through triggers, conditions, and actions is probably pretty straightforward at first. I guess it works very well for simple systems, though I wonder how it could be made to scale better. In this configuration based system, even just a couple of automation scripts can balloon to pages and pages of code, and possible very little operator understanding how rules possible cross-interact with each other. I don’t know what model would be better (some kind of state machine definition maybe?), but it would worth thinking about it for the long term of home automation.
There are more components defined than I could reasonably ever try in my life, just check the component’s page!
This abundance also means that the number of possible combinations are astronomical. I would wager, though, that the value of those combinations follow a power-low: most of the combinations are not interesting at all, while a relatively small number of combinations are the most useful in general! I guess the Cookbook would be a good place to highlight some more “common use cases”, not just covering the bases and filling in for the lack of documentation. There are some obviously more useful components, IFTTT component on its own can add a ton of functionality, or the RESTful components.
Future
I hope, that more device manufacturers will create components and generously add it to this lineup. I can’t see any downside and there’s just so much upside working with an open source system! Any system integrator that figures out Home Assistant will also have a big competitive advantage in some niches for sure.
I hope, that the documentation can be improved in the future and things will be easier to figure out (e.g. how would I update this project above to light up the LED if any one of the tracked devices is present and turn the LED off when all of them are absent?).
The huge number of possible component combinations to mix-and-match is also pretty paralyzing too (see the classic Paradox of Choice), I have no good “production-level” project in mind yet, even though I’m super excited about many components I’ve found so far! This particular project worked, because it’s already something I was thinking about, and could possibly replace an existing system in the Taipei Hackerspace!
Have you built something interesting? Would love to hear about it! :)