Description of the template elements and attributes#

XML-header#

The header of the file is currently fixed to

<?xml version="1.0" encoding="UTF-8"?>

Root element <Device>#

The root element of the file is currently fixed to

<Device name="" template_version="1.1">...</Device>

Allowed Position and Usage:\ Mandatory element. It must be positioned directly below of the Header <?xml> (4.1).

<IPBox> element#

This element describes the device type IP relay with http command interface.

<IPBox template_version="0" ip_box_is_set="true" max_relais="1">...</IPBox>

<IP_Adresse> element#

This element describes the IP address of the device.

<IP_Adresse editable="true" gui_is_optional="false"></IP_Adresse>

<Port> element#

This element describes the IP port of the device.

<Port editable="true" gui_is_optional="false">80</Port>

<Model> element#

This element describes the model name of the device. It will be visible in Devices -> Device wizard in the column “Device Template” and will be copied into the column “Name”. Under “Name”, the copy can be edited by the user.

<Model editable="true" gui_is_optional="false">Example model</Model>

|attribute | note| |---|---|---| |editable | May be set to "true" or "false", Will be ignored! Has no effect in the Web UI. | |gui_is_optional| May be set to "true" or "false", Will be ignored! Has no effect in the Web UI. |

<Company> element#

This element describes the vendor name of the device. It will be visible in Devices -> Device wizard in the column “Device Template”.

<Company editable="true" gui_is_optional="false">The Relay Works</Model>

<Username> element#

This element describes the username used for authentication. Will be used by the functionality of elements <basic_auth> and <digest_auth>. In an url string it can be used by the variable $Username$.

<Username editable="true" gui_is_optional="true"></Username>

<Passwort> element#

This element describes the username used for authentication. Will be used by the functionality of elements <basic_auth> and <digest_auth>. In an url string it can be used by the variable $Passwort$.

<Passwort editable="true" gui_is_optional="true"></Passwort>

<Relays> element#

This element enables the editing of the relay names.

<Relays editable="true" gui_is_optional="false">...</Relays>

<Relay> element#

This element defines the relay position in the data structure and predefines a relay name. <Relay> has to occur several times, until it matches with the number of relays defined in the attribute max_relais of element <IPBox>.

<Relay position="1" status="true">Example Relay 1</Relay>
<Relay position="2" status="true">Example Relay 2</Relay>
<Relay position="3" status="true">Example Relay 3</Relay>
<Relay position="4" status="true">Example Relay 4</Relay>

It is recommended to enter a predefined relay name in the element structure!

<Relaytype_CGI> element#

This element defines, that the relay accepts control or/and status commands by an http interface.

<Relaytype_CGI editable="true" gui_is_optional="true">...</Relaytype_CGI>

<basic_auth> element#

This element enables the basic authentication method specified in RFC 7617 before sending commands to the IP relay.

This is a very simple method using standard fields in the HTTP header. If enabled, it uses Username (4.8) and Passwort (4.9) as credentials.

<basic_auth>true</basic_auth>

<digest_auth> element#

This element enables digest authentication method specified in RFC 2617 before sending commands to the IP relay. If enabled, it uses Username and Passwort as credentials.

<digest_auth>false</digest_auth>

<http_request> element#

This element defines the functionality and http method used to send commands to the relay.\

<http_request name="schalte_relay" method="PUT" response_is_in_http_body="false" relay_turn_value_on="true" relay_turn_value_off="false" />

attribute: name#

With the definitions here in this field the following http request in the Element is connected to the PBX functionality. The PBX performs three basic functions after the initialisation:

• Switch the relay on

• Switch the relay off

• Retrieve the relay status

This is triggered in the PBX by a configuration switch or a user request from a telephone.

Before invoking this function, the PBX is updating the future relay status into the variables $Relay_STATUS$ or $Relay_STATUS_X$.

This function is invoked every 5 seconds. The PBX is updating the relay status into the variables $Relay_STATUS$ or $Relay_STATUS_X$.

attribute: response_is_in_http_body#

If set to "true", the IP relay replies with the status in the body of the http reply answer.

It is then necessary to add a <http_response> entry with the variables $Relay_STATUS_1$, etc..

If set to "false", the IP relay does not reply with the status. "false" is not allowed in combination with name="relay_status".

attribute: method#

The http method to send the url string to the IP relay. Values may be:

• GET
• PUT
• POST

attribute: relay_turn_value_on#

The string replaces the string "1" from the variables $Relay_STATUS$ or $Relay_STATUS_X$ for switching the relay on when sending the url string to the relay.

And also replaces the string "1" representing the on-state when receiving the relay status.

attribute: relay_turn_value_off#

Accepts any string value.

The string replaces the string "0" from the variables $Relay_STATUS$ or $Relay_STATUS_X$ for switching the relay off when sending the url string to the relay.

And also replaces the string "0" representing the off-state when receiving the relay status.

<url_string> element#

This element defines a URL string to send to the IP relay when switching or querying the status.

   <url_string editable="true" gui_is_optional="false">/url/for/turning/box/on</url_string>

This URL string may contain variables:

• $Username$: the username as defined in the <Username> element

• $Passwort$: the password as defined in the <Passwort> element

• $Relay_STATUS$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. Limitation: Must only be used together with <request_type>just_one_relay_at_a_time</request_type>. The position is then determined by the loop counter.

• $Relay_STATUS_x$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. x represents the relay position as defined in the <Relay> element

<request_type> element#

This element defines some special handling, when sending URL strings to certain types of IP relays.

<request_type>just_one_relay_at_a_time</request_type>

content "just_one_relay_at_a_time"#

Some devices with multiple relays allow only to switch or request the status from one relay at a time (e.g. Phillips Hue).

This flag enables to run through <http_request name=”relay status”> in a loop, until the status of all relays is requested.

In this loop, the variables $Relay$ and $Relay_STATUS$ are increased by one to reflect the relay position.

content "just_one_relay_at_a_time_no_fill_ups:#

Special handling implemented initially for Energenie PMS LAN devices. This device is able to receive a switching command for all 4 relays, but not more than one relay at a time may be switched.

These devices require to leave the status of the relays, that are not switched, empty.

Example for Energenie PMS LAN devices. The xml template contains this definition:

<request_type>just_one_relay_at_a_time_no_fill_ups</request_type>
<http_body_request>cte1=$Relay_STATUS_1$&amp;cte2=$Relay_STATUS_2$&amp;cte3=$Relay_STATUS_3$&amp;cte4=$Relay_STATUS_4$</http_body_request>

To switch relay 2 on, this http request string will be sent: cte1;cte2=1;cte3=;cte4=

<http_body_request> element#

This element is enabling the sending of content in the http BODY to the IP relay.

<http_body_request>{
    &quot;hue&quot;: 50000,
    &quot;on&quot;:$Relay_STATUS$,
    &quot;bri&quot;: 200
}
</http_body_request>

This content may contain variables:

• $Username$: the username as defined in the <Username> element

• $Passwort$: the password as defined in the <Passwort> element

• $Relay$: the relay position as defined in <Relay> Limitation: Must only be used together with <request_type>just_one_relay_at_a_time</request_type>. The position is then determined by the loop counter.

• $Relay_STATUS$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. Limitation: Must only be used together with <request_type>just_one_relay_at_a_time</request_type>. The position is then determined by the loop counter.

• $Relay_STATUS_x$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. x represents the relay position as defined in the <Relay> element

<http_response> element#

This element is enabling the receiving of content in the http reply BODY of the IP relay. The reply reflects the status of the relay after switching or a status request. The string in front of the variables is searched for in the response and the variables are expected thereafter. If additional strings are in between of the variables, these strings have to be entered in to the response definition, too.

   <http_response use_body="true">&lt;html&gt; $Relay_STATUS_1$ $Relay_STATUS_2$ $Relay_STATUS_3$ $Relay_STATUS_4$ &lt;/html&gt;</http_response>

This content may contain these variables:

• $Relay$: the relay position as defined in <Relay> Limitation: Must only be used together with <request_type>just_one_relay_at_a_time</request_type>. The position is then determined by the loop counter.

• $Relay_STATUS$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. Limitation: Must only be used together with <request_type>just_one_relay_at_a_time</request_type>. The position is then determined by the loop counter.

• $Relay_STATUS_x$: The status of the relay. When sending a switch commend, this is the desired status. After a status query, this is the actual status. x represents the relay position as defined in the <Relay> element