Linknx / Wiki / Action's

Action's_syntax

Authors:

General

The type of action is determined by the type attribute.
Supported values for this attribute are: set-value, copy-value, toggle-value, set-string, send-read-request, cycle-on-off, repeat, conditional, start-actionlist, formula, set-rule-active, send-sms, send-email, dim-up, shell-cmd, ioport-tx, script and cancel.

Another optional attribute valid for all actions is delay defining a number of seconds between the moment action is triggered and the moment it's really executed.
If it's directly followed by 'd', 'h', 'm', 's' or 'ms', the numeric value is interpreted as number of days, hours, minutes, seconds or milliseconds (ms only supported since 0.0.1.28).

We can use an object in some actions like for sms, email or ioport for send his value.
you have to had the parameter var="true" and in "data" add the object like this : ${id_of_the_object}
ex. : <action type="ioport-tx" data="pl A1 xdim ${id_of_the_object}" ioport="X10" var="true"></action>

set-value

The value defined by the value attribute will be assigned to the object referred to by the id attribute.
Example

<action type="set-value" id="kitchen_heating" value="comfort" />

copy-value

This action can be used to copy an object's value to another object. The copy converts the value to a string then converts the string to the target object's value. This allows for example to copy an 8bit integer value into a floating point object or to a string object.

<action type="copy-value" from="heating_mode" to="prev_heating_mode"/>

toggle-value

This action can be used for binary objects and is switching object's value between "on" and "off" once.

<action type="toggle-value" id="door_light"/>

set-string

This action can set an object's value using a character string. The following pattern ${obj_id} will be replaced by the actual value of object obj_id when the action is executed.

<action type="set-string" id="lcd_text" value="T° ext: ${ext_temp}°C" />

send-read-request

This action can send a read request on the KNX bus. This is useful with objects that don't transmit their actual value periodically. This action will force the KNX device that has the "read" flag set in ETS to reply with a read response containing the actual value. If the linknx object has the "update" flag set, it will update its internal value with the received one.

<action type="send-read-request" id="gas_counter_value">

cycle-on-off

Attribute id reffering to the object to switch on and off.
Attributes on and off defining the delay in seconds for on and off states.
Attribute count defining the number of on/off cycles to perform.
An optional stopcondition child element to abort the cycle when the condition is met. See [Condition's_Syntax] for details.
Example

<action type="cycle-on-off" id="closet_lights" on="5" off="5" count="10">

Please note that each cycle begins with switching the object to on and ends with switching it to off. In result this action is always leaving the object finally in an "off" state.

repeat

Since version 1.28 there is a possibility to create a simple repetition loop that repeats a list of actions periodically a predefined number of times. All actions in the list are started at the same time, but you can delay some of them using the delay="x" parameter like on any action.

Attribute period defining the delay in seconds between repetitions.
Attribute count defining the number of repetitions to perform.
One or more action child elements to execute count times every period.
Example

&lt;action type="repeat" period="2" count="3"&gt;
     &lt;action type="toggle-value" id="door_light"/&gt;
     &lt;action type="toggle-value" id="door_light" delay="500ms"/&gt;
&lt;/action&gt;

conditional

One condition child elements that is evaluated when the action is executed.
One or more action child elements to execute if condition above is true.
Example

&lt;action type="conditional"&gt;
  &lt;condition type="object" id="alarm_email_enabled" value="on" /&gt;
  &lt;action type="send-email"  to="help@example.com" subject="Foreign contaminant"&gt;Intrusion in your shrubbery!&lt;/action&gt;
&lt;/action&gt;

The condition doesn't allow use of trigger attribute because the evaluation is triggered by the action execution.
If parameter delay is added to the <action type="conditional"> tag, the condition will be evaluated after the delay has elapsed.

start-actionlist

This special action can be used to force execution of the complete actionlist from a given rule. Example

&lt;action type="start-actionlist" list="true" rule-id="flashing_lights" /&gt;

execute actions "if-true" or "on-true" of the rule, or:

&lt;action type="start-actionlist" list="false" rule-id="flashing_lights" /&gt;

to execute actions "if-false" or "on-false" of the rule

formula

Can be used to compute a value based on formula axm+byn+c.

x and y are optional. If provided, they need to refer to a valid object.
a, b and c are optional, too. They need to be valid (floating) numbers. The defaults for a and b are 1.0, the default value for c is 0.
m and n are optional, too. They need to be valid (floating) numbers. The defaults for both are 1.0.

The result will be written to the id.

Example

&lt;action type="formula" id="object_id_result" n="1.0" m="2.0" c="3.0" b="4.0" a="5.0" y="object_id_y" x="object_id_x" &gt;&lt;/action&gt;

Formula : id=ax^m+by^n+c => object_id_result = 5object_id_x^2+4object_id_y^1+3

set-rule-active

Can be used to to enable or disable (with optional parameter active set to 'no') a given rule-id.

Example

&lt;action type="set-rule-active" active="no" rule-id="flashing_lights" /&gt;

&lt;action type="set-rule-active" active="yes" rule-id="flashing_lights" /&gt;

cancel

Attribute rule-id defines the rule for which all pending actions will be cancelled.
Example

&lt;action type="cancel" rule-id="flashing_lights" /&gt;

Pending actions are the actions waiting for execution due to the delay attribute, or action that spread over a period of time like dim-up or cycle-on-off. For these actions that spread over time, what has already been executed at the moment of cancel will not be undone. Only the processing that is not yet done will be skipped. Actions that are inside repeat or conditional actions can not be canceled if they are started. But the repetition itself, or the initial sleep due to delay attribute can be interrupted.

send-sms

Attribute id defines the phone number where to send SMS.
Attribute value defines the text of the message.
Attribute from defines the optional sender ID to be inclued in the message Example

&lt;action type="send-sms"  id="32494123456" value="Foreign contaminant" /&gt;

send-email

Attribute to defines the e-mail's recipient.
Attribute subject defines the message subject.
Element's text defines the e-mail body.
Example

&lt;action type="send-email"  to="help@example.com" subject="Foreign contaminant"&gt;Intrusion in your shrubbery!&lt;/action&gt;

dim-up

Attribute id refers to the dimmer value object to control. This object must be a scaling object (5.xxx, EIS6)
Attributes start and stop define the dimming value (between 0 and 255) of starting and end point.
Attribute duration defines the number of seconds elapsed between starting and end point.
Example

&lt;action type="dim-up" id="dim_value_kitchen" start="0" stop="240" duration="1800" /&gt;

shell-cmd

Attribute cmd defines the shell command to execute.
Example

<action type="shell-cmd" cmd="killall -v eibd" />

ioport-tx

See [IO_Ports]

script

See [Lua_Scripting]

Wiki: Condition's_Syntax
Wiki: IO_Ports
Wiki: Lua_Scripting
Wiki: Main_Page

Linknx Wiki