
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)




