search

myhouse-project / myHouse

Home monitoring and automation suite with interactive Slack bot
GNU General Public License v3.0
2 stars 0 forks source link
home-automation iot mysensors raspberry-pi rtl-433 slack slackbot

readme

[MyHouse]

Features

How it works

Think of myHouse as a framework for automating your house. The first step is to configure the sensors you want to collect data from. Included in the package, there are already a number of plugins (e.g. to collect weather statistics, information from the linux box when it runs, retrieving images from the Internet, your GPS position from icloud, data collected by Wirelessthings/Ciseco sensors, interacting with the GPIO, leveraging rtl_433, etc.) and you can easily add your own plugins. Once your sensors are configured and data has been collecting, the suite automatically calculates for every hour and for every day minimum/maximum/average values so to present only summarized information without overloading with unnecessary data.

What will be presented in the web interface is completely up to you. You can define your own modules, chose your icons and configure all the widgets that will be presented in the order you like the most. The statistics elaborated by the tool can be presented in a number of ways: timeline charts for different group of sensors with recent or historical data, current measures and minimum/maximum values for today and yesterday are just some of the examples. From the interface your actuators can be controlled as well: thanks to input fields, switches and a fully-featured scheduler, you can meet easily whatever requirements you might have.

Collecting and presenting statistics is nice but you may want to be automatically alerted whenever a specific situation is taking place. This is why you can easily create rules which will trigger when the set of conditions you have defined will be all true. Actions can be configured as well to e.g. send a message to an actuator or just set the value of a sensor. An alert does not necessarily represent a critical situation but can be just a simple messages (e.g. the minimum and maximum temperature we had yesterday indoor) to share with the users. Notificationscan be presented within the web interface, sent by e-mail or sms, sent to a speacker or posted on a Slack channel of your choice.

If you don't know what Slack is, have a look at it. This collaborative, real-time messaging tool can become your family's virtual place when enhanced by myHouse. Not only myHouse's Slack bot will notify the members when something is happening but allows direct interaction in your natural language. Depending on your questions and what the bot knows (e.g. the attached sensors and configured widgets), it can reply by sharing with you its statistics and charts or send commands to an actuator on your behalf. The same mechanism applies if you connect a speaker and a microphone to the station: the bot will be able to understand your requests and respond accordingly.

How I configured myHouse at home

Since myHouse is a framework, everything is defined in the configuration file so my instance may look completely different than yours. This is nice because allows great flexibility but requires a starting point if you don't want to get lost in the configuration. For this reason, I'm making my own configuration part of the distribution package under the name config-advanced.json: most of the modules and rules are disabled since do not necessarily work in your environment but at least you have a fully working example to take inspiration from. In my own myHouse, I have configured the following sensors:

I have configured then the following modules and widgets:

I have finally configured the following rules:

I have eventually configured a number of rules without conditions (that are used by the bot for its basic knowledge) reporting upon current weather conditions, temperature, boiler status, etc.

Installing

Installation logs will be made available under logs/install.log

Uninstalling

The dependencies, the database and all the other files belonging to myHouse will NOT be deleted.

Upgrading

Configuring

The entire configuration of the suite is within the config.json file, of course in a JSON format (http://www.json.org/). If the file does not exist, at the first run, myHouse will automatically create one as a copy of config-example.json. This is a working example with basic functionalities.

For a more complex example, the one described in the section above, review the config-advanced.json and take inspiration from there to understand the most complex capabilities of myHouse.

The configuration itself is pretty articulated this is why it is highly recommended to review the config-schema.json file for a detailed explanation of the different options and combinations available. Alternatively, the configuration editor available from within the web interface allows to build your own configuration graphically (upon saving, a copy of the previous configuration is stored into the config.bak file). Either way, the resulting file is checked against the schema to ensure the configuration is correct upon startup. A service restart (e.g. sudo /etc/init.d/myHouse restart) is required to apply any change.

The logic behind the configuration file is pretty simple: there is a generic configuration first (where the database is, what is the mailserver, which recipient to send notifications to, how to connect to Slack, what and where to log, etc.) followed by a number of custom modules. Each module is an entry in the menu of the web interface and has three main sections:

Plugins

Each plugin can support input (retrieve data from a sensor), output (send data to an actuator) or both. For input, data can be retrived in two ways: pull (the sensor is pulled at regular time intervals) or push (the plugin is kept running and when a new measure is received, the main engine is notified). The following out of the box plugins are part of the software:

Plugin Name Input Output
wunderground Yes (pull) No
weatherchannel Yes (pull) No
messagebridge Yes (push) Yes
csv Yes (pull) No
image Yes (pull) No
icloud Yes (pull) No
command Yes (pull) Yes
system Yes (pull) No
rtl_433 Yes (push) No
gpio Yes (pull/push) Yes
earthquake Yes (pull) No
mqtt Yes (pull) Yes
ads1x15 Yes (pull) No
dht Yes (pull) No
ds18b20 Yes (pull) No
rss Yes (pull) No
mysensors Yes (pull) Yes
bluetooth Yes (pull) No

For input, "Push" plugins must implement a "run()" method (which will be called at startup to keep the plugin running in background) and a "register(sensor)" method (for registering suitable sensors against the plugin). When a new measure is available, it must call the "store" method of sensors.py to save the data. "Pull" plugins must instead implement a "poll(sensor)" method (to retrieve the raw data from the sensor), a "parse(sensor,data)" method (to parse the raw the data previously polled) and optionally a "cache_schema(sensor)" method to cache raw data so preventing different sensors to poll for the same data concurrently. The main engine will be responsible to periodically invoke poll and parse and hence storing the new measure. For input plugins, they must implement a "send(sensor,data)" that will be invoked to send a message to their supported actuators.

Notifications

The notification subsystem allows the user to communicate with myHouse and viceversa. Each module can support input (the user requests something to the system), output (the system sends the user a notification) or both. The following out of the box modules are part of the software:

Module Input Output
email No Yes
sms No Yes
slack Yes Yes
audio Yes Yes
buzzer No Yes
GSM sms No Yes
GSM call No Yes

For each output notification the following can be optionally set:

About myHouse

Why myHouse?

There are thousands of home automation suites around and dozens of new solutions made available every single day. So why yet another piece of software? I may have very peculiar requirements but none of the products around had a good fit for me.

First, I didn't want to use a cloud-based service both for privacy reasons and because my Internet connection is not necessarily always on so I had the need to both store and present data from within my network.

Secondarily, I need to review the statistics collected mostly when I am not at home: this is why I had to exclude all the solutions which are creating charts with all the raw data collected if I wanted to avoid high latency and mobile roaming charges. Much lighter and more resistant to spikes looked to me to calculate average/minimum/maximum values for each hour and for each day.

I also wanted a way to centralize in a single place both the sensors and the webcams, independently of the source. This is why this plugin-based architecture: if you are collecting the external temperature from an Internet service and you add a sensor at home to do the same later, you want to keep the history and use the same presentation format. For the same reason I wanted to be indipendent from the different standards and IoT vendors around.

I also wanted to create something adapting easily to the extreme flexibility needed by this kind of solutions. This is why everything is defined in the configuration, the sensors you want to collect data from, the widgets to present in the web interface, the way you want each chart to be drawn.

I also have the need to receive when I'm not at home a very detailed e-mail summary containing the same information as I was browsing the web interface.

For the same reason (and because I dont' not want to expose the web interface over the Internet so making the access via the VPN not very handy) I wrote the Slack bot. It allows me to immediate access any information I need in real-time, interact with the actuators (e.g. my boiler) quicker and remotely and, why not, having some fun by arguing with a real bot.

The last technical requirement I had was to make the solution as lighter as possible (hence Flask instead of Apache/PHP) and gentle with the SD card of my raspberry pi (hence Redis instead of other SQL databases).7

Need help?

Third-party software

myHouse makes use of the following third-party software components:

Changelog