(NB: If you see strange escape characters or other line noise in this file,
or in fact any other file or output of this package, you forgot to
switch your system to UTF-8.)

«MoaT» is the «Manager of all Things». It began its life as «HomEvenT»,
which is a contraction of "home event", plus funky capitalization.
Its principal author is Matthias Urlichs <matthias@urlichs.de>.
However, the thing is not just for managing events at home, so it was time
for a name change. Plus, frankly, plodding through lots of incompatible
home automation solutions does feel like wading through molasses … or a
boggy moat. Hence the new name.


I wrote MoaT because while playing around with some home automation
stuff, I found that none of the free systems out there fit my needs
particularly well, plus they are not talking to each other.

In my home, I have a heterogenous infrastructure: some switches
need to be wireless, some existing wired switches need to survive;
some devices can only be controlled by infrared, some are in places
where nothing except stringing some wire would work, all the new stuff
is connected with KNX/EIB.


This code uses Unicode, more specifically UTF-8, quite liberally.
For this reason it's imperative to teach Python that the default character
set is UTF-8, not ASCII. Thus, you need to add the following code to
/etc/python2.7/sitecustomize.py:

    import sys
    try:
    	sys.setdefaultencoding("utf-8")
    except AttributeError:
    	pass

This change is very unlikely to be a problem. It's also no longer necessary
with Python 3, which MoaT is migrating to (but it's not quite there yet).


The rest of the documentation is in the doc/ subdirectory.
You'll probably want to start with the tutorial.

Interactive tests and experiments are easy:
just type “make i”, then “help”.


The components I'm mostly concerned with are:

* KNX

A mostly-European 2-wire bus system (like 1wire, one of these is ground;
unlike 1wire, the rest state is 30V and you don't need a separate power
supply. Also unlike 1wire, components are mostly quite intelligent, made by
a lot of manufacturers, and quite expensive unless you know what to look
for).

There's a free daemon for KNX which interfaces the bus to IP multicast.

There's also no way to program (or rather, configure) these devices without
shelling out $$$ for a proprietary configuration thing which only runs on
Windows.

* Wago

This is a industrial controller made by Wago GmbH, Germany.
It runs Linux and it has decent pluggable I/O modules for most needs.
The daemon I wrote to run on that device could probably be adapted quite
easily to use standard Linux GPIO (to run on a Raspberry Pi) instead.

I'm intentionally not using MODBUS or some other standard (which these
controllers also support) since these buses don't afford timed outputs.
It's imperative that my watering system closes the valves after the
prescribed time, however, even if the network goes down …

* 1-wire

This is a two-wire bus system -- one of these wires is Ground, so
apparently it doesn't count. ☺ In practice, you do need a separate power
supply. Personally, I use a cheap shielded four-wire cable (LIYCY).

The bus can be connected rather haphazardly if your wires are not *that*
long, or you can use special branch controllers if you need to be more
careful. It works admirably well in my house.

The system is not that fast. In practice, you can poll a simple on/off
sensor 250 times a second, so the limit with cheap sensors is 40
switches on a bus — 100, if you get somewhat-more-expensive "event
counter" chips instead of dumb sensors. You can also connect a variety
of sensors and A/D converters to that bus, but not at the same time
because doing so will block the bus for up to a second. :-/

On the plus side: the peripherals, including voltage and (calibrated!)
temperature sensors, are really cheap, and a little bit of electronics
knowledge goes a long way. (Who needs "when's sunrise" code, when you
can add a real daylight sensor to your system for less than €5?) There
are also inexpensive LCD panels for remote status displays which don't
warrant their own control computer.

Linux support for 1-wire comes either as an incomplete kernel module,
or a user-space daemon (<http://owfs.sourceforge.net>) with support for
networking and multiple scripting languages. I'm using the latter.

* AMQP

RabbitMQ is a nice message broker. MoaT broadcasts all its events through
the broker so that other systems can pick them up and multiple instances
can talk to each other.

* LIRC

I use infrared to control the window blinds. Good motors cost around
€110 wholesale (or €210 retail ☹).

LIRC is a reasonably integral part of most modern Linux distributions,
so the idea to use it as a simple way to control a couple of Linux
programs ("if I turn off the room lights in my living room at night,
please pause Rhythmbox and/or Totem, turn off power to the stereo, and
let the computer hibernate") has a lot of appeal... and if the lights
are not controlled centrally, see above for the cheap light sensor.

Other systems and projects
--------------------------

* openHAB

Large. Those people know what they're doing. Unfortunately they're doing it
it Java. That language may have some advantages, but I'll happily let
others waste their time writing yet another adapter class.

I use it for visualization, but plan to replace the back-end with a MoaT
instance.

It can talk MQTT, so interfacing to it is simple.

* plutohome

Really large. Not my kettle of fish: writing my own system is bound to
be quicker than figuring out how to hook 1-wire sensors into this beast
of hundreds of C++ classes.

* misterhome

Looks interesting, but frankly I hate Perl. Writing a home automation
*configuration* in Perl is not what I want to do.

* fhem

Started its life talking to FS20; these days, talks to about anything.
Works quie well as a front-end. Again, too much Perl. Also, blocking code.

It can talk MQTT, so interfacing to it is simple.

* xap

This protocol tries to be both high-level enough to serve as a generic
home control infrastructure and low-level enough to be understandable in
dumb devices. My take is that a high-level protocol needs to be more
structured (dare I say XML?) and low-level devices are better handled by
an adapter — the protocol is too verbose for slow interfaces.

The available software is somewhat Windows-centric. The Python module
for it (100% written in C, one wonders why) is one of the most ugly
pieces of code I've *ever* seen.

Writing a front-end adapter might work, and there are some good ideas
in the data structures it models.