Chains is a home automation system.
The main goals of the Chains project are:
- Support as many different services as possible
- Easy service development
- Easy installation
While most home automation software focuses on supporting a single piece of hardware, we aim to support them all and make them work together.
- Linux on Raspberry Pi and Raspberry Pi 2
- Linux on x86 (32/64bit)
- Phidgets
- Philips Hue
- InfluxDB (graphing)
- rrd (graphing)
- Bluetooth
- Tellstick
- Pushover.net
- IR remote control (lirc)
- Time
- IRC
- LGTV
- USB-Relay
- System-information
- Network proximity
- Raspberry Pi (GPIOs and camera)
- CEC (Raspberry Pi and Pulse Eight usb-adapter)
- Mouse (usb, buttons and direction)
- USB-info
- Keyboard (usb, click, release, modifiers)
- Sonos
- Integra and Onkyo receivers
In development:
- IPCam
- OneWire
- Spotify
- mpd
- xmms2
- Micropython
- Asterisk (voip)
- Motion
We will eventually provide docker images from the docker registry, but for now dockerfiles can be created by bin/dockerfile-assemble.py and built on your own system. Docker is a good match for our project since we need a host of different libraries and daemons running to support the different services. Providing instructions for all distributions and testing these configurations would be too time consuming. The whole process, however, is described in the generated dockerfile. Feel free to install it locally.
# Create config and data dir:
sudo sh -c "mkdir -p /etc/chains/services && mkdir -p /srv/chains-data"
# Pull and run latest version
sudo docker run -d --privileged --net=host -v /etc/chains:/etc/chains -v /srv/chains-data:/srv/chains/data -v /dev:/dev -v /etc/localtime:/etc/localtime:ro chains/chains-master
# Create config and data dir:
sudo sh -c "mkdir -p /etc/chains/services && mkdir -p /srv/chains-data"
# Create chains master image:
bin/dockerfile-assemble.py master
sudo docker build --no-cache -t chains/chains-master .
# Run chains master
sudo docker run -d --privileged --net=host -v /etc/chains:/etc/chains -v /srv/chains-data:/srv/chains/data -v /dev:/dev -v /etc/localtime:/etc/localtime:ro chains/chains-master
Docker build/install for chains slave node (only if you already have a master node running on different computer)
# Create config and data dir:
sudo sh -c "mkdir -p /etc/chains/services && mkdir -p /srv/chains/data"
# Create chains slave image:
bin/dockerfile-assemble.py slave
sudo docker build --no-cache -t chains/chains-slave .
# Run chains slave
# Exchange 192.168.1.1 for the ip address of your machine running chains-master
sudo docker run -d --privileged --net=host -e "AMQP=192.168.1.1:5672" -v /etc/chains:/etc/chains -v /srv/chains-data:/srv/chains/data -v /dev:/dev -v /etc/localtime:/etc/localtime:ro chains/chains-slave
Chains starts several processes that run in the background. In the linux/unix world such processes are known as daemons.
All services
are also run as seperate background processes.
The manager is the process that starts and stops service
processes for chains.
There is one manager per node
in the chains system.
The reactor is the process that runs rules
. For now there is
There is, for now, only one reactor in a chains system, it runs on the "master" node.
The orchestrator reads the centrally stored configuration for each service
, and tells managers on each node what configuration to apply to services
they start. It also monitors the health of the system by watching heartbeats for all processes.
There is only one orchestrator running in a chains system, like the reactor it runs on the "master" node.
Chains comes with the aptly named chains
command line application.
When using docker this program will work automatically.
It is sometimes useful to run it from a computer that is not a node in the chains network, fortunately this is pretty easy if you know linux basics:
- clone the chains repository into /srv/chains as described above
- symlink /srv/chains/lib/chains into your python site-packages dir
- add /srv/chains/bin to your path
- create /etc/chains/amqp.conf with the same content as your other nodes (host/port pointing to master) The 3 first steps are only necessary because our setup.py is (probably, not tested) not working properly at the moment, sorry!
Service
# List running services
chains service list
# Start a service
chains service start <service_id>
# Stop a service
chains service stop <service_id>
Reactor
# List reactor info
chains reactor list
# Dump the (full) current state of chains:
chains reactor action <reactor_name> getState
# Get the state of a specific service:
chains reactor action <reactor_name> getState <service_id>
Manager
# List managers (all nodes running chains will have a manager)
chains manager list
# Example output:
------------------------------------------------------------
Manager Online Last heartbeat
------------------------------------------------------------
chainsmaster Online 1 sec ago
alarmpi about 996 hours ago
rpi-z Online 1 sec ago
mediacenter Online 1 sec ago
In the Chains documentation we often refer to nodes, devices and services, these are explained below.
Nodes are computers runnning Chains. Multiple machines are supported, and they communicate on a regular tcp/ip network using an included RabbitMQ-server. If you run chains on only one machine you must run the "master" node, this is the hub of the chains system and it takes cares of the rules
described below. Slave nodes are installed on additional computers that you may add to the chains network.
A service
is a program that controls something in chains, usually a piece of hardware like a light controller or internet service like pushover.net.
Example services: PhilipsHue, onewire, timer, pushover.
Devices are how functionality is divided into units in a service
. In a service that control light switches, each light switch would typically be a device
. A device may be able to do several actions
and report several events
.
Properties are information made available from a device
. A light switch device could for example have the properties 'dimlevel', 'power' and 'location'. A property can also be the target of an action
, if the property is something that can be change. An example of this would be the "power" property on a light switch device
, that might switch between "on" and "off".
Nodes, Services, Devices and Properties form a tree-like structure:
Node (computer)
\ Service1
| \ Device1
| | \ Property1
| | \ Property2
| \ Device2
| \ Property1
|
\Service2
| \ Device1
| \ Device2
and so on
While nodes, services and devices deal with the software controlling hardware sensors and such; events, actions and rules are what makes it possible for the former to connect and cooperate.
A service
will often report changes or things that happen in the system. This is called an event
.
A remote control service
would send an event when a button on a remote-control device
is pressed, a temperature sensor service would send an event containing the current temperature and so on.
Some devices are able to do things as well as report events
these are called actions
.
A receiver service could have actions like PowerOn, ChangeSource and Mute, while a light control service
might have actions like LightOn, LightOff and Dim for its lamp devices
.
A rule
is a description of what should happen as a response to an event
in the system. These rules can be chain
ed together to create more advanced logic.
The simplest rules
can be easily created in the upcoming webgui, while for advanced applications the full power of the python programming langauge is available. Special objects are created to represent events
, actions
and current state
in the chains system to simplify creation of rules
.
# TODO: change to match new service/device naming
def rule(context):
# wait for 'switch-2' event sent from 'device' on 'service_id'
yield Event(service='service_id', device='switch-2')
# run action 'power_off' on device 'other_device'
Action(service='other_service', device='some_device', action='power_off')
# and so on
Action(...)
yield Event(...)
Action(...)
We aim at making development of new devices as easy as possible. While it is possible to write everything from scratch, we provide a framework that takes care of common functions and hides unnecessary boilerplate.
from chains.service import Service
class MynewService(Service):
def onInit(self):
# code that runs on service startup, usually setting things up for onStart below
# get some config:
self.username = self.config['username']
def onStart(self):
"""main loop for the service"""
while not self._shutdown:
do_stuff_here
# perhaps send an event:
self.sendEvent('event_name', {'foo': {'value': 'bar', 'actions': ['refoo', 'unfoo'] } }, {'type': 'foo_event', 'location': 'home'})
def action_unfoo(self, myparam):
"""
Do something
@param myparam string A string is needed for this action
"""
action_code_goes_here
The above code will create description of the action "unfoo" on the "Mynew"-service and announce it to the Chains system. For now the best way to write services is to model them after the existing services, PhilipsHue, Tellstck and System are good places to start. We will eventually document this fully in our wiki.
To be able to use all your regular development tools and quickly test changes on a running system, mount the chains repositry into the chains container:
git clone git@github.com:ChainsAutomation/chains.git /srv/chains
docker pull chains/chains-master
docker run -d --privileged --net=host -v /etc/chains:/etc/chains -v /srv/chains:/srv/chains -v /dev/bus/usb:/dev/bus/usb -v /etc/localtime:/etc/localtime:ro chains/chains-master
You can find us in the #chains
channel on the Freenode
IRC network. Or via Slack: https://chainsautomation.slack.com
Chains is a grateful user of a number of great open source projects:
- Python
- PYPY
- NodeJS
- RabbitMQ
- Docker
- Supervisor
- Raspian and Ubuntu (for docker images)
- Bluez
- A number of python libraries
TODO: Expand this list and add links to projects