4. Description of the template elements and attributes

The header of the file is currently fixed to

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

Allowed Position and Usage:
Mandatory header. It must be the first line of the file!

Allowed Attributes

 version=
 Must be "1.0" at the current version.
 encoding=
 Must be "UTF-8" at the current version.

The structure must be closed with

 ?>

The root element of the file is currently fixed to

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

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

Allowed Attributes

 name=
 Must be "" at the current version.
 template_version=
 Must be 1.1 at the current version.

The structure must be closed with

 </Device>

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

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

Allowed Position and Usage:
Mandatory element. <IPBox> must be a sub-element of Root element <Device> (4.2).

Allowed Attributes

 template_version=
 Must be set to "0" at the current version.
 ip_box_is_set=
 Must be "true" at the current version.
 max_relais=
 Defines the total number of relays embedded into this device. If you do not want to use all of the relays, they can be deactivated later in the Web UI by the user.

The structure must be closed with

 </IPBox>

This element describes the IP address of the device.
Example:

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

Allowed Position and Usage:
Mandatory element. <IP_Adresse> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 editable=
 Must be set to "true". The user has to enter the correct address.
 gui_is_optional=
 Must be "false". This field must not be empty.

The structure must be closed with

 </IP_Adresse>

This element describes the IP port of the device.
Example:

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

Allowed Position and Usage:
Mandatory element. <Port> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 editable=
 May be set to "true", if the device has configurable ports. If set to "false", a predefined port has to be entered into the file!
 gui_is_optional=
 Must be "false". This field must not be empty.

The structure must be closed with

 </Port>

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.
Example:

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

Allowed Position and Usage:
Mandatory element. <Model> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 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.

The structure must be closed with

 </Model>

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

Example:

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

Allowed Position and Usage:
Mandatory element. <Company> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 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.

The structure must be closed with

 </Company>

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$.

Example:

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

Allowed Position and Usage:
Mandatory element. <Username> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 editable=
 Must be set to "true".
 gui_is_optional=
 May be set to "true", if the device does not require a username. Must be set to  "false", if a username is needed by the device.

The structure must be closed with

 </Username>
 

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$.

Example:

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

Allowed Position and Usage:
Mandatory element. <Passwort> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 editable=
 Must be set to "true".
 gui_is_optional=
 May be set to "true", if the device does not require a password. Must be set to  "false", if a password is needed by the device.

The structure must be closed with

 </Passwort>

This element enables the editing of the relay names.

Example:

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

Allowed Position and Usage:
Mandatory element. <Relays> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 editable=
 Must be set to "true". The user may rename the relays.
 gui_is_optional=
 Must be set to "false". Every relay needs a name, the field must not be empty.

The structure must be closed with

 </Relays>
 

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> (4.3).

Example (max_relais=“4”):

 <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>

Allowed Position and Usage:
Mandatory element. <Relay> must be a sub-element of Element <Relays> (4.10)

Allowed Attributes

 position=
 Defines the relay enumeration for usage in the url strings later.
 status=
 Must be set to "true".

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

The structure must be closed with

 </Relay>

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

Example:

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

Allowed Position and Usage:
Mandatory element. <Relaytype_CGI> must be a sub-element of Element <IPBox> (4.3).

Allowed Attributes

 is_simple=
 If set to "true", the IP relay has limited capabilities:
 It has only one embedded relay (max_relais="1")
 It has one specific url to switch it on (see <http_request name="relay_on"…>)
 It has another specific url to switch it off (see <http_request name="relay_off"..>)
 It does not answer to a status query (no element <http_response>).
 It must not be used with <http_request name="schalte_relay"…>
 editable=
 Must be set to "true" only together with the attribute is_simple="true", if the user is allowed or required to edit the url strings 
 <http_request name="relay_on"…>) or <http_request name="relay_off"..>. Otherwise, set to "false"
 gui_is_optional=
 Must be set to "false" only together with the attribute is_simple="true", if the user is allowed or required to edit the url strings 
 <http_request name="relay_on"…>) or <http_request name="relay_off"..>. Otherwise, set to "true".

The structure must be closed with

 </Relaytype_CGI>

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.

Example:

 <basic_auth>true</basic_auth>

Allowed Position and Usage:
Optional element. Default is “false”, if not present.
<basic_auth> must be a sub-element of Element <Relaytype_CGI> (4.12)
Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple=“true” !

Allowed Attributes:

 no attributes allowed

The structure must be closed with

 </basic_auth>
 

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

Example:

 <digest_auth>false</digest_auth>

Allowed Position and Usage:
Optional element. Default is “false”, if not present.
<digest_auth> must be a sub-element of Element <Relaytype_CGI> (4.12)
Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple=“true” !

Allowed Attributes

 no attributes allowed

The structure must be closed with

 </digest_auth>
 

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

Example:

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

Allowed Position and Usage:
Mandatory element.
<http_request> must be a sub-element of Element <Relaytype_CGI> (4.12)

Allowed Attributes

 name=
 Mandatory attribute.
 With the definitions here in this field the following http request in the Element <url_string> 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
 name="relay_on": Limitation: Must be used only together with the Element <Relaytype_CGI> and attribute is_simple="true". The following <url_string> is switching the relay on.
 name="relay_off": Limitation: Must be used only together with the Element <Relaytype_CGI> and attribute is_simple="true". The following <url_string> is switching the relay off.
 name="schalte_relay": Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple="true". The following <url_string> is switching the relay on or off. 
 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$.
 name="relay_status": Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple="true". The following <url_string> is requesting the current switch status from the relay. 
 This function is invoked every 5 seconds. The PBX is updating the relay status into the variables $Relay_STATUS$ or $Relay_STATUS_X$.
 response_is_in_http_body=
 Optional attribute.
 Default is "true", if not present.
 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".
 method=
 Optional attribute.
 Default is "GET", if not present.
 The http method to send the url string to the IP relay. Values may be 
 "GET"
 "PUT"
 "POST"
 relay_turn_value_on=
 Optional attribute. 
 Default is "1", if not present. Accepts any string value.
 Limitation: Must only be used together with name="schalte_relay" or with name="relay_status".
 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.
 relay_turn_value_off=
 Optional attribute. 
 Default is "0", if not present. Accepts any string value.
 Limitation: Must only be used together with name="schalte_relay" or with name="relay_status".
 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.

The structure must be closed with

 </http_request>

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

 <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 Element <Username>4.8
 $Passwort$ : the password as defined in Element <Passwort> (4.9)
 $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 Element <request_type>just_one_relay_at_a_time (4.17). 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 Element <Relay> (4.11)

Allowed Position and Usage:
Mandatory element. <url_string> must be a sub-element of Element <http_request> (4.15)

Allowed Attributes

 editable=
 Must be set to "true" only together with the attribute is_simple="true", if the user is allowed or required to edit the url strings 
 <http_request name="relay_on"…>) or <http_request name="relay_off"..>. Otherwise, set to "false"
 gui_is_optional=
 Must be set to "false" only together with the attribute is_simple="true", if the user is allowed or required to edit the url strings 
 <http_request name="relay_on"…>) or <http_request name="relay_off"..>. Otherwise, set to "true".

The structure must be closed with

 </url_string>

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

Example:

 <request_type>just_one_relay_at_a_time</request_type>

Allowed Position and Usage:
Optional element. If not present: Default is no special handling enabled.
<request_type> must be a sub-element of Element <http_request> (4.15)
Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple=“true.

Allowed Attributes:

 no attributes allowed

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.
 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=
 Please note: The status values of the relays, that are not currently switched, are left empty. The previous status of these unchanged relays is not sent in the string!

The structure must be closed with

 </request_type>

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

 <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 Element <Username>4.8
 $Passwort$ : the password as defined in Element <Passwort> (4.9)
 $Relay$ : the relay position as defined in Element <Relay> (4.11). Limitation: Must only be used together with Element <request_type>just_one_relay_at_a_time (4.17). 
 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 Element <request_type>just_one_relay_at_a_time (4.17). 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 Element <Relay> (4.11)

Allowed Position and Usage:
Optional element. Default if not present: No http BODY content will be send.
<http_body_request> must be a sub-element of Element <http_request> (4.15)
Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple=“true”.
Must only be used with Element <http_request> (4.15) and method=“PUT” or method=“POST”. method=“GET” is not supported!

Allowed Attributes

 no attributes allowed

The structure must be closed with

 </http_body_request>

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.
Example:

 <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 Element <Relay> (4.11). 
 Limitation: Must only be used together with Element <request_type>just_one_relay_at_a_time (4.17). The position is then determined by the loop counter.
 $Relay_STATUS$ : The status of the relay. When sending a switch command, this is the desired status. After a status query, this is the actual status. 
 Limitation: Must only be used together with Element <request_type>just_one_relay_at_a_time (4.17). 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 Element <Relay> (4.11)

Allowed Position and Usage:
Optional element. Default if not present: The reply will be discarded.
<http_ response> must be a sub-element of Element <http_request> (4.15)
Limitation: Must not be used together with the Element <Relaytype_CGI> and attribute is_simple=“true”.
Must only be used with Element <http_request> (4.15) and name=“schalte_relay” or name=“relay_status”.

Allowed Attributes

 use_body=
 Must be set to "true" to evaluate and update the status of the relays. A string with variables must be entered to do this.
 If set to "false" the information in the reply will be discarded.

The structure must be closed with

 </http_response>

<- Previous Chapter | Next Chapter ->