Effects scripts

Effects scripts are written in xml in a way similar to Ant scripts.

The syntax is not case sensitive, except tag name in "start tag" and "end tag" which must be written in the same way to match each other (ie. <tag>...</tag>, <Tag>...</Tag> are ok but <tag>...</TAG> does not work).

All attribute values can be set in string literal or be called from an already set variable (see tag <var /> below).
To call a variable as an attribute value, put $variable_name in the value (ie my_attr="$my_var").

Comments can be added in a script with the html/xml syntax : <!-- ... -->.
Everything inside a comment block will be ignored during script execution.

Scripts samples can be found into effects directory.
After installation, effects scripts are stored into effects directory too.

---

The available tags are the following :

<effect></effect>

Begins and ends a script.
Contains information attributes about the script :

• name : name of the script (mandatory)
• comment : description of the script (optional)

ie.: <effect name="Example" comment="Example effect with 3 lights"> ... </effect>

<var />

Set a variable with a value.
Attributes :

• name : name of the target variable (mandatory)
• value : value to set (mandatory)

ie.: <var name="var1" value="10" />, <var name="var2" value="$var1" />

<getcolor />

Store the color attributes and the 'on' state of a light
Attributes :

• id : id of the source light (mandatory).
• name : name of the stored color attributes (mandatory).

ie.: <getcolor id="2" name="color2" /> store the color and status informations of light id 2 under the name "color2"

<setcolor />

Set the color attributes and the 'on' state of a light or a lights group from a previously stored attributes (see <getcolor />)
Attributes :

• id : id of the target light or lights group (mandatory).
• name : name of the stored color attributes to use (mandatory).
• type : value "light" or "group" (optional). "light" is the default type if not present.
• transitiontime : value of transitiontime in 1/10 second (optional) (see official light api for more details)

ie.: <setcolor id="1" name="color2" /> set stored color and status attribute "color2" to light id 1

<light /> or <group />

Set state attributes for a light or a group of lights
Attributes :

• id : id of the target light or group (mandatory).
• attribute : list of attribute(s) to be set for the light or group (at least 1 is mandatory). (see official light api or official group api for attributes details)

ie.: <light id="1" on="true" bri="$stdbri" /> turn on light with id 1 and set brightness with value stored in var 'stdbri'
<light id="4" on="true" effect="colorloop" /> turn on light with id 4 and launch a colorloop on it
<group id="0" on="false" /> turn off all lights

<scene />

Recall a scene with its name (use <group /> with attribute scene to recall a scene with its id - see official api for group state)
Attribute :

• name : name of the scene to recall (mandatory).

ie.: <scene name="myscene" />

Remarks :

• If the scene name exists several times, the first scene id returned by the bridge and matching the name is taken.
• When recalling a scene, it takes some times before lights attributes are updated in the bridge (light on/off, color informations, ...), so it can be difficult to use the result in a script even with a timer.

<timer />

Set a timer in seconds and 1/10 of second
Attribute :

• duration : duration of the time in second (mandatory). One decimal is allowed.

ie.: <timer duration="5" /> wait five seconds, <timer duration="0.5" /> wait 0.5 seconds

<loop></loop>

Set a loop block to repeat n times
Attribute :

• repeat : number of repetitions for the loop (mandatory).

ie.: <loop repeat="2"> ... </loop>
Remark : loops can be nested, ie. <loop repeat="3"> ...<loop repeat="2"> .. </loop> ... </loop>