avr: added README for app light controller.

avr/apps/light_control/README

@@ -0,0 +1,120 @@
+
+App for Trigger Activated Light
+==============================
+
+1. Introduction
+---------------
+
+This app listens for VALUE_REPORT messages on the bus. If a preselected value from a preselected node
+is received and falls inside lower and upper limit the LED stripe attached to the node which runs this
+app will be turned on in the preselected color for a preselected time. If in this time another matching
+message is received the light timer gets restarted. If no matching message is received within the
+preselected time the light is turned off again.
+
+Typical usage is to watch for a motion message from some node with a motion sensor and react to that.
+This app can monitor up to two triggers.
+
+Turning on the light can be conditioned on received values from a VALUE_REPORT falling inside other specific
+limits (e.g. only allow the light to be turned on if a LIGHT sensor reports that it is dark enough for the
+light to be usefull).
+
+
+
+2. Values
+---------
+
+2.1. LIGHTCTL_TRIGGER1_SOURCE
+
+This can be used to make this app react to MOTION messages:
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_TRIGGER1_SOURCE -v 0:0:VALUEID:ADDR
+
+VALUE is the value id from a VALUE_REPORT message
+ADDR is the address of the sending node.
+
+Example:
+ React to value report messages with value id 7 from node with address 4
+   aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_TRIGGER1_SOURCE -v 0:0:7:4
+
+
+2.2. LIGHTCTL_TRIGGER1_LIMITS
+
+Sets the limits for the value of a trigger message which actually triggers the app.
+
+E.g. MOTION messages have values 0 (no motion) and 1 (motion detected). So a value of 1 or higher should
+trigger. In this case the lower limit is 1 and the upper limit is 65535 (the highest possible value, but in this
+specific case of MOTION messages you could also use "1").
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_TRIGGER1_LIMITS -v 1:65535
+
+This commands makes all values higher than 0 trigger.
+
+
+2.3. LIGHTCTL_GUARD_SOURCE
+
+A guard source can be set to make triggers conditional.
+
+E.g. if there is enough light in a room turning on a lamp wouldn't make too much sense. In this case
+you could define another VALUEID-ADDR pair which can modify the behaviour of this app.
+
+Example:
+ React to value report messages with value id 0x0b from node with address 9
+   aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_GUARD_SOURCE -v 0:0:0x0b:9
+
+2.4. LIGHTCTL_GUARD_LIMITS
+
+If a message matching LIGHTCTL_GUARD_SOURCE is received its value will be used to modify the
+trigger behaviour of the app. If the value falls into the lower and upper limit triggers will
+be generated (otherwise trigger messages will be ignored).
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_GUARD_LIMITS -v LOWER_LIMIT:HIGH_LIMIT
+
+E.e. when using LIGHT sensors light is only to be turned when the reported value is below 60 the
+correct limits could be set like this:
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_GUARD_LIMITS -v 0:60
+
+
+2.5. LIGHTCTL_MODE
+
+There are 3 modes:
+- 0: OFF  (unconditionally OFF)
+- 1: ON   (unconditionally ON)
+- 2: AUTO (ON when triggered by e.g. MOTION message)
+
+
+2.6. LIGHTCTL_VALUE
+
+Set the color to be used when LED strip is switched ON.
+ aqhome-tool setdata -N nodes/XXXXXXXX/LIGHTCTL_VALUE -v GREEN:RED:WHITE:BLUE
+
+Example:
+  Set color of LED strip to blue (half intensity)
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_VALUE -v 0x80
+  or in modern format:
+  aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_VALUE -v 0:0:0:0x80
+
+
+2.7. LIGHTCTL_HOLDTIME
+
+On-Time after activation:
+ aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_HOLDTIME TIME_IN_1/10_SECS
+
+Example:
+ Keep light on after activation for 20 seconds
+ aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_HOLDTIME -v 200
+
+
+
+3. Examples
+-----------
+
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_TRIGGER1_SOURCE -v 0:0:7:4 # Value 7 on device with address 4
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_TRIGGER1_LIMITS -v 1:65535 # lower limit 1, higher limit 65535
+
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_GUARD_SOURCE -v 0:0:0x0b:9 # value 0xb on device with address 9
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_GUARD_LIMITS -v 0:60       # allow ON between 0 (lower limit) and 60 (high limit)
+
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_MODE -v 2                  # mode: 0=off, 1=on, 2=auto
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_HOLDTIME -v 6000           # keep ON for at least 600 secs
+aqhome-tool setdata -N nodes/xxxxxxxx/LIGHTCTL_VALUE -v "#0000ff00"       # set color (GGRRWWBB or GREEN:RED:WHITE:BLUE)
+
+
+
+