Table of Contents generated with DocToc

• Heating
  • Dependencies
    • Node.js
      • Installation
        • Variant 1)
        • Variant 2)
    • Node.js modules
    • 1-Wire & OWFS
    • RRDtool
  • Initial Configuration
  • Running
    • Manual
    • Automatic
  • Debugging
  • Testing
  • License

A personal effort for improving living standard through home heating automation :)

Slides.com presentation introducing the project and (hopefully) explaining architecture and design decisions is available here.

Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.

Even though Node.js installation should be straight forward, on Raspberry Pi you need to have a distro with hard-float support (e.g. Raspbian). Another issue could be amount of hours needed to compile Node.js from source. So, here are a few "shortcuts":

wget http://node-arm.herokuapp.com/node_latest_armhf.deb # v0.10.35 as of January 2015
sudo dpkg -i node_latest_armhf.deb

Described here. Latest stable (0.10.x) Raspberry Pi binaries (as of January 2015) are these and experimental (0.11.x) are these.

The application uses some 3rd party modules, dependency on which is listed in package.json and resolved with the following command:

npm install

OWFS is an easy way to use the powerful 1-wire system of Dallas/Maxim. OWFS is a simple and flexible program to monitor and control the physical environment. You can write scripts to read temperature, flash lights, write to an LCD, log and graph...

Go through a tutorial for setting up measuring temperature with DS18B20 temperature sensor.

The Round Robin Database Tool (RRDtool) is a system to store and display time-series data (e.g. network bandwidth, machine-room temperature, server load average). It stores the data in Round Robin Databases (RRDs), a very compact way that will not expand over time. RRDtool processes the extracted data to enforce a certain data density, allowing for useful graphical representation of data values.

Installation:

sudo apt-get install rrdtool

Relay pins and temperature sensor 1-wire address are set up in /app/gpio-tools.js:

• gpioPinHeater & gpioPinPump variables are using header pin numbers. (You can refer to this mapping to distinguish between header, BCM and wiringPi pin numbering),
• tempLivingSensorId variable represents the (living room) temperature sensor directory name on 1-wire bus.

Outside temperature is gathered from a 3rd party weather service (forecast.io) which requires an API key that needs to be specified in /app/weather-tools.js variable options.APIKey. Frequency of accessing this API (config.collect_record_interval) is configured so that the number of free daily requests is not exceeded.

Application checks the origin of the (API) request and, based on config.allow_unauthenticated_lan switch, doesn't restrict write-access for locally originated requests, but if accessed remotely (i.e. from outside of LAN) then the authentication (username & password) is enforced for application (API) write-access. To create a user, simply run node createUser.js username password. Password is hashed and, for simplicity, stored as JSON in /app/.auth file.

Optionally, to enable online scrobbling of measurements (currently disabled) change the value of scrobble_data_online in /app/config-tools.js and set up a Sen.se account API key to be used in variable sense_url in /app/cloud-tools.js.

Running the application manually (with npm start) is possibly convenient when e.g. testing new functionality, but for real-life usage a convenience of having the application running continuously regardless of application crashes, system reboots, power outages, etc. is recommended (see next chapter).

Step 1 is ensuring application continues running after crashing. That is the work of Node.js module forever, which is installed globally (with npm install -g forever) and, once run, takes care of keeping the target Node.js application up. Basically, this will do the trick: forever start app/app.js (if run from the app root directory). But that, unfortunately, doesn't solve power outages and system reboots killing the application.

Step 2 is taking the automation to the system level by creating a service. The service script is already available (file heating in the app root directory) and these steps describe what needs to be done to enable it:

1. customize APP_HOME variable in heating script to point to your app root,

2. deploy the script with:

   sudo cp heating /etc/init.d/ sudo chmod 755 /etc/init.d/heating sudo update-rc.d heating defaults

3. after that, start the service with: sudo /etc/init.d/heating start.

When started with forever/service, the app defaults to process.env.NODE_ENV='production' which displays only "error"-level logs. For printing out more logs, it's necessary to run the app with NODE_ENV=development node app/app.js or to simply start it with npm start.

Tests are located under /test directory and are separated into modules they aim to test. Note: tests only cover "public" functions of modules.

Test execution depends on Mocha -- a feature-rich JavaScript test framework running on Node.js.

To install Mocha:

npm install -g mocha

To start the tests:

npm test

Copyright 2015 Robert Šarić

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.