# Status of this project

This is an early preview. I think the structure of the API is mostly
stable (ie the relationship of data types should not change radically),
but names might change for better consistency and semantics (how errors
are handled, side effects like logging, etc.) will change in subtle ways
too. And of course lot's of symbols will be added to make a consistent
and conventient interface.

There is one exception: In future libautomation will depend on
[libelektra](https://www.libelektra.org) and any applications needing
configuration will be recommended to use it as well. This will allow
for spreading configuration handling between library and applications
and facilitate seamless integration. This probably will have some
impact on typical program flow and the API in general.

What is currently completely missing, is algorithms for data processing
(eg filtering), standard feedback loops, etc. While these are clearly
within the scope of this project, it turns out many applications don't
need them. Therefore implementation (and API design) will happen later.
(Hopefully somehow fitting with the existing API.)



# What libautomation is: Design decisions and lessons learned

libautomation was created by abstracting common code from several
applications of industrial and home automation. It is assumed that this
code will be useful for writing more automation applications.

libautomation is intended to do as little as possible, relying on linux
functionalities and external libraries (like libev) as much as possible.
It is written entirely in C and every part of it should be easily
replaceable by custom code, if the application has special needs.

The goal here is to make easy tasks simple and complex projects
possible and easily managable.

As such libautomation is not only (maybe even not mainly) about the
code provided, but very much about the lessons learned from writing
automation applications: How to do things and what not to do because
it leads to problems down the road. These lessons have been turned
into design decisions.


## Use a system daemon instead of a watchdog

While it might seem tempting on embedded automation solutions to use the
watchdog directly in the main application, because this automatically
tests the entire software stack, this approach is too inflexible: Any
additional features need to be integrated into the main application,
which conflicts with trying to keep libautomation very modular.

Instead a system daemon (like procd from OpenWRT) should feed the
watchdog and in turn monitor all applications running on the system.


## An automation system should be resilent against crashing/hanging processes

libautomation aims for custom made (home brewn) automations solutions.
These often don't run on a 10k Euro PLC, yet might be used in an industrial
environment with high levels of EMI, that might cause occasional hardware
faults in cheap HW. It should be easy to write automation applications
in such a way, that the system can recover from such errors by restarting
processes or resetting the system.


## library functions might crash instead of fail

This might seem like an unconventional choice at first. But additional to
the remarks about reliability above, think about the following points:
 * Usually nobody attends the automation system to read error messages.
 * If a syscall returns an error, that can be handled, the library should
   do it. If it can't be handled, then restarting the application or the
   system seems to be a plausible fix.
 * The library API is a lot easier to use when functions cant fail ... ;)

Of course the above is only a guideline, not a principle. If in doubt
failing and not-failing versions of the same function should be provided.


## Multiple processes need to cooperate

There are many constraints on how an automation algorithm is split into
threads and processes:
* Some actions can cause interference with reading sensors, so you typically
  want to have everything in one thread, to control relativ timing of
  operations.
* However not every IO can be made non-blocking, e.g. reading a sensor
  via sysfs might block for a long time until in runs into some timeout.
  Therefore at least multiple threads are needed, if not multiple processes.
* Some input is expensive to read (might come over the network or a slow
  bus), so the effort should be duplicated needlessly.
* Sometimes it becomes desireable two run the same thread twice, controlling
  two machines at the same times. When people write multithreaded applications,
  they often don't anticipate this case, and if they do it usually is untested
  and more complicated then plain running the application twice.

To make it possible to meet all these contraints, clearly an ability to
share (sensor) data between multiple processes is necessary.



# What to find in the directory tree

The repository currently contains the sources and header files of the
library itself in the folder `lib' and some small demo applications,
that are either helpful utilities or small automation applications
in the folders `tools' and `examples'.


## Tools

### atmdump SHMID
The `atmdump' tool prints the contents of the libautomation shared memory
domain SHMID in human readable form to standard output. This is mostly
useful for ad-hoc testing and inspection, but also serves as a demo for
shared memory clients.

### atmd /path/to/configfile
The `atmd' (for libautomation daemon) reads any number of data source (ie
devices) from the configuration file specified on the command line and
makes their periodically updated values available via shared memory. This
is the demo for providing values in shared memory,

`atmd' is also a very important part of the libautomation ecosystem:
In the case where reading a sensor might block for an unacceptable long
time, `atmd' provides reading the sensor in a seperate process, without
any change to the primary application.

Furthermore `atmd' allows organizing data sources into so called
data source groups, which each can have their own policy regarding handling
of errors when reading a sensor. Each data source group lives in their
own config file. Config files can be loaded recursively with the
`dsgrp' keyword.


## Examples

### humiditycontrol /path/to/configfile
is a small air humidity regulator. It measures the relativ humidity and
temperature on two places (typically inside a building and out doors) and
calculates the absolute humidities. If the absolute humidity on the out side
is lower then insides, then a fan is turned on.

There are several configuration settings to control target values, allowed
energy loss when it is cold outsides, etc. This demo is actually useful
for real world applications and can easily get extended and customized to
specific needs, like adding a dehumidifier, etc.

### line_monitor /path/to/configfile
is a building block for an alert system. It monitors some input (typically
a gpio) indicating the status of some equipment. When the input changes
state, it triggers execution of some external programm like a script doing
a mobile call.

The alert command is executed periodically until either the error condition
is fixed or the operator acknowledges the error.

This application is actually used verbatim in a district heating plant.
Well, since I changed the libautomation API after deploying the system,
it isn't actually verbatim any longer ...



# Getting in touch

Libautomation is currently hosted at https://repo.or.cz/libautomation.git -
please ask me if you want push access. I'm easily reachable via e-mail.

If there is sufficient interest, I can open a mailinglist for this
project, but at the moment you need to send all questions and bug
reports to me personally.