Skip to content

IP relay templates#

Minimum API level

API version 7.0 or higher

Scope#

This document is describing the xml Templates for IP relays with http command set in the following PBX systems:

  • COMpact 4000

  • COMpact 5000/5000R

  • COMpact 5200/5200R

  • COMpact 5500R

  • COMmander 6000/6000R/6000RX

The document is meant for developers wanting to integrate IP relays not currently supported into the PBX system.

Usage#

Auerswald xml templates for IP relays describe the switching and status monitoring of these relays as devices under the control of the PBX systems. These xml templates provide an adaption to various control and status messages, that are used for different devices. The commands for your specific device can be found in the documentation of your IP relay vendor.

Auerswald has some predefined templates in the firmware of the PBX. These predefined templates can be exported in Devices ->Device wizard -> File Management. It is very useful to take one of these predefined templates and modify it to match your device.

These templates may be imported into the PBX on the Web UI page Devices->Device wizard->Import->Import from file. Under Devices->Device wizard->File Management you can delete imported templates.

Info

The export and import of these files may need admin privileges in your PBX systems.

Basic Structure#

All templates need a minimum set of elements to work. You may find additional information in the examples and the detailed description of elements and attributes. Mandatory elements must be part of every template. Here is the minimum set of elements for an XML template file.

The line end character is UNIX style: Only 0Dhex is needed.

Please note

There are no commands in this structure here, so this template will have no useful function:

  <?xml version="1.0" encoding="UTF-8"?>
  <Device name="" template_version="1.1">
     <IPBox template_version="0" ip_box_is_set="true" max_relais="1">
       <IP_Adresse></IP_Adresse>
       <Port>80</Port>
       <Model>Example model</Model>
       <Company>The Relay Works</Company>
       <Username></Username>
       <Passwort></Passwort>
       <Relays>
             <Relay position="1" status="true">Example Relay 1</Relay>
       </Relays>
       <Relaytype_CGI>
              <http_request>
                     <url_string></url_string>
              </http_request>
       </Relaytype_CGI>
     </IPBox>
  </Device>

Examples#

Simple single IP relay#

This simple IP relay has very basic features:

  • No authentication

  • No status request command

  • Only two commands for on and off

  • Does not answer to switching with a status reply

  • It is reachable via port 80

The command for switching the relay on: http:///control?cmd=GPIO,12,1

The command for switching the relay off: http:///control?cmd=GPIO,12,1

This command structure is implemented into this template: 

<?xml version="1.0" encoding="UTF-8"?>
  <Device name="" template_version="1.1">
     <IPBox template_version="0" ip_box_is_set="true"  max_relais="1">
       <IP_Adresse editable="true" gui_is_optional="false"></IP_Adresse>
          <Port editable="true" gui_is_optional="false">80</Port>
          <Model>Simple GPIO 12</Model>
          <Company>Maker Box</Company>
          <Username editable="false" gui_is_optional="true"></Username>
          <Passwort editable="false" gui_is_optional="true"></Passwort>
          <Relays editable="true" gui_is_optional="true">
              <Relay position="1" status="true">GPIO12-Relais</Relay>
          </Relays>
          <Relaytype_CGI is_simple="true">
            <http_request name="relay_on">
                 <url_string editable="true" gui_is_optional="false">/control?cmd=GPIO,12,1</url_string>
            </http_request>
            <http_request name="relay_off">
               <url_string editable="true" gui_is_optional="false">/control?cmd=GPIO,12,0</url_string>
            </http_request>
          </Relaytype_CGI>
     </IPBox>
  </Device>

IP relay with 4 ports#

This IP relay has 4 switches:

  • It uses basic authentication

  • It answers switching with a status reply

  • It supports status requests

  • It is reachable via port 80.

Switching the relays at position 1 and position 3 on or off: http:///cgi/control.cgi?login=p:username:password&p=1010
Explanation: After p= the 4 relays are represented by a 1 for on or a 0 for off. Relay position 1 is on the left, relay position 4 is on the right side.

This switching command is answered by a status reply in the http BODY: 

<html>1 0 1 0</html>
Explanation: After <html> the 4 relays are represented by a 1 for on or a 0 for off. Relay position 1 is on the left, relay position 4 is on the right side.

The command for the status request: http:///cgi/control.cgi?login=p:username:password&port=list

This status query command is answered by a status reply in the http BODY: 

<html>1 0 1 0</html>
Explanation: After <html> the 4 relays are represented by a 1 for on or a 0 for off. Relay position 1 is on the left, relay position 4 is on the right side.

This command structure is implemented into this template: 

<?xml version="1.0" encoding="UTF-8"?>
<Device name="" template_version="1.1">
   <IPBox template_version="0" ip_box_is_set="true" max_relais="4">
       <IP_Adresse editable="true" gui_is_optional="false"></IP_Adresse>
       <Port editable="true" gui_is_optional="false">80</Port>
       <Model editable="true" gui_is_optional="true">Great 4</Model>
       <Company editable="true" gui_is_optional="true">Good Switches</Company>
       <Username editable="true" gui_is_optional="false"></Username>
       <Passwort editable="true" gui_is_optional="false"></Passwort>
       <Relays editable="true" gui_is_optional="true">
              <Relay position="1" status="true">Power-Relay 1</Relay>
              <Relay position="2" status="true">Power-Relay 2</Relay>
              <Relay position="3" status="true">Power-Relay 3</Relay>
              <Relay position="4" status="true">Power-Relay 4</Relay>
       </Relays>
       <Relaytype_CGI editable="true" gui_is_optional="true">
          <basic_auth>true</basic_auth>
          <digest_auth>false</digest_auth>
          <http_request name="schalte_relay" method="GET">
               <url_string>/cgi/control.cgi?login=p:$Username$:$Passwort$&amp;p=$Relay_STATUS_1$$Relay_STATUS_2$$Relay_STATUS_3$$Relay_STATUS_4$</url_string>
               <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>
          </http_request>
          <http_request name="relay_status" response_is_in_http_body="true" method="GET">
               <url_string> /cgi/control.cgi?login=p:$Username$:$Passwort$&amp;port=list</url_string>
               <http_response>&lt;html&gt;$Relay_STATUS_1$ $Relay_STATUS_2$ $Relay_STATUS_3$ $Relay_STATUS_4$  &lt;/html&gt;</http_response>
          </http_request>
       </Relaytype_CGI>
   </IPBox>
</Device>