| blob | 7cd049045a129fc3e5ea1e512258fdb452583619 |
1 # Status of this project
3 This is an early preview. I think the structure of the API is mostly
4 stable (ie the relationship of data types should not change radically),
5 but names might change for better consistency and semantics (how errors
6 are handled, side effects like logging, etc.) will change in subtle ways
7 too. And of course lot's of symbols will be added to make a consistent
8 and conventient interface.
10 There is one exception: In future libautomation will depend on
11 [libelektra](https://www.libelektra.org) and any applications needing
12 configuration will be recommended to use it as well. This will allow
13 for spreading configuration handling between library and applications
14 and facilitate seamless integration. This probably will have some
15 impact on typical program flow and the API in general.
17 What is currently completely missing, is algorithms for data processing
18 (eg filtering), standard feedback loops, etc. While these are clearly
19 within the scope of this project, it turns out many applications don't
20 need them. Therefore implementation (and API design) will happen later.
21 (Hopefully somehow fitting with the existing API.)
25 # What libautomation is: Design decisions and lessons learned
27 libautomation was created by abstracting common code from several
28 applications of industrial and home automation. It is assumed that this
29 code will be useful for writing more automation applications.
31 libautomation is intended to do as little as possible, relying on linux
32 functionalities and external libraries (like libev) as much as possible.
33 It is written entirely in C and every part of it should be easily
34 replaceable by custom code, if the application has special needs.
36 The goal here is to make easy tasks simple and complex projects
37 possible and easily managable.
39 As such libautomation is not only (maybe even not mainly) about the
40 code provided, but very much about the lessons learned from writing
41 automation applications: How to do things and what not to do because
42 it leads to problems down the road. These lessons have been turned
43 into design decisions.
46 ## Use a system daemon instead of a watchdog
48 While it might seem tempting on embedded automation solutions to use the
49 watchdog directly in the main application, because this automatically
50 tests the entire software stack, this approach is too inflexible: Any
51 additional features need to be integrated into the main application,
52 which conflicts with trying to keep libautomation very modular.
54 Instead a system daemon (like procd from OpenWRT) should feed the
55 watchdog and in turn monitor all applications running on the system.
58 ## An automation system should be resilent against crashing/hanging processes
60 libautomation aims for custom made (home brewn) automations solutions.
61 These often don't run on a 10k Euro PLC, yet might be used in an industrial
62 environment with high levels of EMI, that might cause occasional hardware
63 faults in cheap HW. It should be easy to write automation applications
64 in such a way, that the system can recover from such errors by restarting
65 processes or resetting the system.
68 ## library functions might crash instead of fail
70 This might seem like an unconventional choice at first. But additional to
71 the remarks about reliability above, think about the following points:
72 * Usually nobody attends the automation system to read error messages.
73 * If a syscall returns an error, that can be handled, the library should
74 do it. If it can't be handled, then restarting the application or the
75 system seems to be a plausible fix.
76 * The library API is a lot easier to use when functions cant fail ... ;)
78 Of course the above is only a guideline, not a principle. If in doubt
79 failing and not-failing versions of the same function should be provided.
82 ## Multiple processes need to cooperate
84 There are many constraints on how an automation algorithm is split into
85 threads and processes:
86 * Some actions can cause interference with reading sensors, so you typically
87 want to have everything in one thread, to control relativ timing of
88 operations.
89 * However not every IO can be made non-blocking, e.g. reading a sensor
90 via sysfs might block for a long time until in runs into some timeout.
91 Therefore at least multiple threads are needed, if not multiple processes.
92 * Some input is expensive to read (might come over the network or a slow
93 bus), so the effort should be duplicated needlessly.
94 * Sometimes it becomes desireable two run the same thread twice, controlling
95 two machines at the same times. When people write multithreaded applications,
96 they often don't anticipate this case, and if they do it usually is untested
97 and more complicated then plain running the application twice.
99 To make it possible to meet all these contraints, clearly an ability to
100 share (sensor) data between multiple processes is necessary.
104 # What to find in the directory tree
106 The repository currently contains the sources and header files of the
107 library itself in the folder `lib' and some small demo applications,
108 that are either helpful utilities or small automation applications
109 in the folders `tools' and `examples'.
112 ## Tools
114 ### atmdump SHMID
115 The `atmdump' tool prints the contents of the libautomation shared memory
116 domain SHMID in human readable form to standard output. This is mostly
117 useful for ad-hoc testing and inspection, but also serves as a demo for
118 shared memory clients.
120 ### atmd /path/to/configfile
121 The `atmd' (for libautomation daemon) reads any number of data source (ie
122 devices) from the configuration file specified on the command line and
123 makes their periodically updated values available via shared memory. This
124 is the demo for providing values in shared memory,
126 `atmd' is also a very important part of the libautomation ecosystem:
127 In the case where reading a sensor might block for an unacceptable long
128 time, `atmd' provides reading the sensor in a seperate process, without
129 any change to the primary application.
131 Furthermore `atmd' allows organizing data sources into so called
132 data source groups, which each can have their own policy regarding handling
133 of errors when reading a sensor. Each data source group lives in their
134 own config file. Config files can be loaded recursively with the
135 `dsgrp' keyword.
138 ## Examples
140 ### humiditycontrol /path/to/configfile
141 is a small air humidity regulator. It measures the relativ humidity and
142 temperature on two places (typically inside a building and out doors) and
143 calculates the absolute humidities. If the absolute humidity on the out side
144 is lower then insides, then a fan is turned on.
146 There are several configuration settings to control target values, allowed
147 energy loss when it is cold outsides, etc. This demo is actually useful
148 for real world applications and can easily get extended and customized to
149 specific needs, like adding a dehumidifier, etc.
151 ### line_monitor /path/to/configfile
152 is a building block for an alert system. It monitors some input (typically
153 a gpio) indicating the status of some equipment. When the input changes
154 state, it triggers execution of some external programm like a script doing
155 a mobile call.
157 The alert command is executed periodically until either the error condition
158 is fixed or the operator acknowledges the error.
160 This application is actually used verbatim in a district heating plant.
161 Well, since I changed the libautomation API after deploying the system,
162 it isn't actually verbatim any longer ...
166 # Getting in touch
168 Libautomation is currently hosted at https://repo.or.cz/libautomation.git -
169 please ask me if you want push access. I'm easily reachable via e-mail.
171 If there is sufficient interest, I can open a mailinglist for this
172 project, but at the moment you need to send all questions and bug
173 reports to me personally.