Split actuator into 2

[khatus.git] / README.md

diff --git a/README.md b/README.md
index 7ab320b..ea6a29c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -12,68 +12,88 @@ Design
 ------
 
 ```
- parallel   +----------+  +----------+     +----------+
- stateless  | sensor_1 |  | sensor_2 | ... | sensor_n |
- collectors +----------+  +----------+     +----------+
-                |             |                 |
-              data          data              data
-                |             |                 |
-                V             V                 V
- serial     +-----------------------------------------+
- stateful   |              controller                 |
- observer   +-----------------------------------------+
-                              |
-                          decisions
-                              |
-                              V
- serial     +-----------------------------------------+
- stateless  |              actuator                   |
- executor   +-----------------------------------------+
-                              |
-                        system commands
-                              |
-                              V
-                            ~~~~~~
-                            ~ OS ~
-                            ~~~~~~
+parallel    +----------+  +----------+          +----------+
+stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
+collectors  +----------+  +----------+          +----------+
+                 |             |           |         |
+               data          data        data      data
+                 |             |           |         |
+                 V             V           V         V
+serial      +----------------------------------------------+
+stateful    |                controller                    |
+observer    +----------------------------------------------+
+                               |
+                       decision messages
+decision                       |
+messages                       |
+copied to                      |
+any number                     |
+of interested                  |
+filter/actuator                |
+combinations                   |
+                               |
+                               V
+                 +-------------+-+---------+---------+
+                 |               |         |         |
+                 V               V         V         V
+parallel    +------------+ +------------+     +------------+
+stateless   | filter_1   | | filter_2   | ... | filter_n   |
+filters     +------------+ +------------+     +------------+
+                 |               |         |         |
+                 V               V         V         V
+parallel    +------------+ +------------+     +------------+
+stateless   | actuator_1 | | actuator_2 | ... | actuator_n |
+executors   +------------+ +------------+     +------------+
+                 |              |          |         |
+              commands       commands   commands  commands
+                 |              |          |         |
+                 V              V          V         V
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            ~~~~~~~~~~~~~ operating system ~~~~~~~~~~~~~~~~~
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ```
 
 ### Actuator
-By default, actuator is left disconnected from the controller's output, so if
+Actuator is anything that takes action upon controller messages. A few generic
+ones are included:
+
+- `khatus_actuate_alert_to_notify_send`
+- `khatus_actuate_status_bar_to_xsetroot_name`
+
+and, by default, are left disconnected from the controller's output, so if
 desired - it needs to be manually attached when starting `khatus`. For example,
 in my `.xinitrc` I have:
 
 ```sh
 $BIN/khatus \
-2> >($BIN/twrap.sh >> $HOME/var/log/khatus.log) \
-| $BIN/khatus_actuator \
-    -v pid="$$" \
-    -v display=":0" \
-2> >($BIN/twrap.sh >> $HOME/var/log/khatus-actuator.log) \
+2> >($BIN/twrap >> $HOME/var/log/khatus.log) \
+| tee \
+    >($BIN/khatus_actuate_status_bar_to_xsetroot_name) \
+    >(grep -v MpdNowPlaying | $BIN/khatus_actuate_alert_to_notify_send) \
+2> >($BIN/twrap >> $HOME/var/log/khatus-actuators.log) \
 &
 ```
+(where `twrap` is a simple script which prefixes a timestamp to each line)
 
-(`twrap.sh` is a simple script which prefixes a timestamp to each line)
-
-The idea is to later have multiple, (some more-general and some more-specific)
-actuators which can be selected as needed, say for example:
+The idea is to give maximum flexibility for what to do with the controller
+output, say, for instance:
 
 ```sh
 $BIN/khatus \
 | tee \
->(awk '/^STATUS_BAR/ {sub("^" $1 " *", ""); system("xsetroot -name \" " $0 " \"")}') \
+... \
 >(grep '^REPORT' | actuate_report_to_email) \
 >(grep '^ALERT' | grep mpd | actuate_alert_to_email) \
 >(grep '^ALERT' | grep IntrusionAttempt | actuate_intruder_to_iptables_drop) \
 >(grep '^ALERT' | grep NewDevice | actuate_alert_to_notify_send)
 >(grep '^ALERT' | grep DiskError | actuate_call_mom)
+...
 ```
-
-... and/or any other such fun you might imagine.
+... and so on, for any other such fun you might imagine.
 
 ### Errors
 Any errors encountered by any sensor are propagated as alerts by the
 controller, which are in turn actualized as desktop notifications by the
-actuator:
+`khatus_actuate_alert_to_notify_send` actuator:
 
 ![screenshot-self-error-propagation](screenshot-self-error-propagation.jpg)