EPC HTTP Interface

Aus Gude Systems GmbH
Zur Navigation springen Zur Suche springen

Overview

  • In this article, you will find a description of the HTTP application programming interface for the Expert Power Control series of the newer generation.
  • As interface, a combination of CGI and JSON via HTTP/HTTPS is described
  • You can send data to the device by sending HTTP-GET requests, along with CGI GET parameters
  • The device will reply with data objects in JSON format, representing the devices' (new) status or config values

Quickstart

If you want to quickstart, please take a look at our HTTP/HTTPS examples using Python


CGI GET Request

Commands to the EPC are sent as an HTTP-GET-request, the following you will find a list of commands and the respective required CGI parameters.

Output switching (easy switching command)

i.E. http://user:secret@192.168.0.2/ov.html?cmd=1&p=1&s=1
CGI Parameter Valid values Description
cmd 1 Command 1: switching output
p [1,2, ... , N] Number of the Output (power port) to be switched
s [0,1] 0: Switch off, 1: Switch on


Output switching (switching in series, Batch mode)

Start Batch mode

i.E. http://user:secret@192.168.0.2/?cmd=5&p=1&a1=0&a2=1&s=5
CGI Parameter Valid values Description
cmd 5 Command 5: Batch mode
p [1,2, ... , N] Number of the Output (power port) to be switched
a1 [0,1] Action number1:
0: Switch off, 1: Switch on
a2 [0,1] Action number2:
0: Switch off, 1: Switch on
s [1..65535] Waiting time in seconds between Action1 and Action2


Cancel Batch mode

i.E. http://user:secret@192.168.0.2/?cmd=2&p=1
CGI Parameter Valid values Description
cmd 2 Command 2: cancel Batch mode
p [1,2, ... , N] Number of the output (power port) to be switched


Reset

Reset is a preconfigured Batch mode, which turns off and turns on again after a configurable time (see : Configuration: Outputs) 

i.E. http://user:secret@192.168.0.2/?cmd=12&p=2
CGI Parameter Valid values Description
cmd 12 Command 12: perform reset
p [1,2, ... , N] Number of the output (power port) on which a reset should be performed


Configuration: Outputs

i.E. http://admin:secret@192.168.0.2/?cmd=3&p=1&name=Output+1&powup=0&powrem=0&idle=0&on_again=0&reset=0&we=0&wip=&wt=0&wport=80&wint=10&wret=6
CGI Parameter Valid values Description
cmd 3 Command 3: configure Output (Power port)
p [1,2, ... , N] Number of the output (power port) to be configured
name Character string with maximum 15 characters Output name
powup [0, 1]

0: leave output switched off after device start
1: Switch Output on after device start

powrem [0, 1] 0: don’t remember actual switching status for next device start
1: remember actual switching status for next device start
idle [0 .. N] Amount of waiting time in seconds after device start before switching on the output
0 = no idle time
on_again [0 .. N] Amount of waiting time in seconds after switching off one output before automatically switching back on,

0= no automatic switching back on

reset [1 .. N] Reset duration: duration of power-down phase in seconds by the reset command
we [0, 1] 0= Watchdog deactivated
1= Watchdog activated
wip Character string Hostname (FQDN) or IP-address of the host to be monitored
wt [0, 1] 0= Watchdog uses ICMP pings
1= Watchdog uses TCP handshakes
wport [1..65535] TCP port number if wt=1
wint [1..65535] Watchdog ping interval in seconds
wret [1..65535] Watchdog ping retry: amount of ping-signals which has to be unanswered to state the watchdog condition “host failed”


Configuration: Inputs

i.E. http://admin:secret@192.168.0.2/?cmd=13&p=1&name=Input+1&hitext=closed&lowtext=open&inverted=1&msgt=0
CGI Parameter Valid values Description
cmd 13 Command 13: configure input
p [1,2, ... , N] Number of the input to be configured
name Character string with maximum 15 characters Input name
hitext Character string with maximum 15 characters Name of the logical-1 condition
lowtext Character string with maximum 15 characters Name of the logical-0 condition
inverted [0,1] Inverts the physical state of the input at inverted=1 . At inverted=0 applies: physical state = logical state
msgt [0,1] Generate messages: at msgt=1 messages will be generated (possibly Syslog, Mail and SNMP-trap) at input condition changes


Configuration: IPv4 Network

i.E. http://admin:secret@192.168.0.2/?cmd=4&host=enc-2i2o-gude&ip=192.168.0.2&nm=255.255.255.0&gw=192.168.0.1dns=192.168.0.1&dhcp=1
CGI Parameter Valid values Description
cmd 4 Command 4: IPv4 network configuration
host Character string with maximum 15 characters Host name (fqdn)
ip Character string with maximum 15 characters IPv4 address
nm Character string with maximum 15 characters IPv4 network mask
gw Character string with maximum 15 characters IPv4 address of an external Gateway
dns Character string with maximum 15 characters IPv4 address of an external DNS-server
dhcp [0, 1] 0: DHCP switched off
1: start DHCP request after device start


Configuration: IP filter (IP-ACL, IP Access Control List)

i.E. http://admin:secret@192.168.0.2/?cmd=6&ping=1&acl=1&ipsec0=192.168.1.0%2F24&ipsec1=&ipsec2=&ipsec3=&ipsec4=&ipsec5=&ipsec6=&ipsec7=
CGI Parameter Valid values Description
cmd 6 Command 6: configure IP-ACL
ping [0, 1] 0: don’t answer on ICMP Echo-Request
1: answer on ICMP Echo-Requests with ICMP Echo-Reply
acl [0, 1] 0: deactivate IP filter, IPv4 access won’t be restricted
1: activate IP filter, just devices or networks mentioned in ipsec0 till ipsec7 have IPv4 access
ipsec0 Character string with maximum 18 characters Host- or Network address which should have IPv4 access when IP filter is switched on (CIDR spelling, e.g. 10.0.0.0/24)
ipsec1 .. ipsec7 like ipsec0 like ipsec0


Konfiguration: HTTP

Bsp: http://admin:secret@192.168.0.2/cmd=18&apwd=admin&upwd=user&port=80&pwd=1&refr=1&sprp=0
CGI Parameter Valid values Description
cmd 18 Command 18: configure HTTP
pwd [0, 1] 0: Switch off HTTP authentication
1: HTTP athentication (HTTP Auth-Basic), passwords for 'user' or 'admin' are necessary
apwd Character string with maximum 15 characters Password of the user 'admin'
upwd Character string with maximum 15 characters Password of the user 'user'
port [1..65535] HTTP Server Port
refr [0,1] HTTP Auto Refresh (automatic refresh of status information in the web browser)
0: Autorefresh switched off, 1: Autorefresh switched on
sprp [0,1] 0=don't demand user authentication for ov.html
1=demand user authentication for ov.html (start-page-requires-password)

Configuration: SNMP

i.E. http://192.168.0.2/cmd=8&get=1&set=1&trap=1&cpub=public&cpriv=private&trapv=2&tr0=192.168.0.100&tr1=&tr2=&tr3=&tr4=&tr5=&tr6=&tr7=
CGI Parameter Valid values Description
cmd 8 Command 8: configure SNMP
get [0, 1] 0: don’t answer SNMP-Get requests
1: answer SNMP-Get requests at valid public-community
set [0, 1] 0: don’t answer SNMP-Set requests
1: answer SNMP-Set requests at valid public-community
trap [0, 1] 0: don’t send SNMP-traps
1: send SNMP-traps
trapv [1,2] 1: send SNMP-v1 traps
2: send SNMP-v2 traps
cpub Character string with maximum 15 characters Name of the public SNMP-Community
cpriv Character string with maximum 15 characters Name of the private SNMP-Community
tr0 Character string with maximum 100 characters IPv4 address or FQDN of the external SNMP-trap-receiver, possibly with alternate Port declaration, e.g. nagio.mydomain.de:10161
tr1 .. tr7 like tr0 like tr0


Configuration: Syslog

i.E. http://admin:secret@192.168.0.2/?cmd=17&syslog=1&slgsrv=192.168.0.100
CGI Parameter Valid values Description
cmd 17 Command 17: configure Syslog
syslog [0, 1] 0: syslog switched off
1: send syslog messages
slgsrv Character string with maximum 100 characters IPv4 address or FQDN of the external syslog server, possibly with alternate port declaration, e.g. Nagios.mydomain.de:10514


Configuration E-Mail

i.E. http://admin:secret@192.168.0.2/?cmd=15&mail=1&auth=0&mailsrv=mx.mydomain.de&sender=epc%40mydomain.de&email=user%40mydomain.de
CGI Parameter Valid values Description
cmd 15 Command 15: configure E-Mail
mail [0, 1] 0: E-Mail notifications deactivated
1: E-Mail notifications activated
auth [0, 1] 0: connect to E-Mail server without SMTP authentication
1: connect to E-Mail server with SMTP authentication (PLAIN)
mailsrv Character string with maximum 100 characters IPv4 address or FQDN of the external SMTP server, possibly with alternate port declaration, e.g. mymx.domain.de:10125
sender Character string with maximum 100 characters Transmitter (From) address
email Character string with maximum 100 characters Receiver (To) address

Reset device

i.E. http://admin:secret@192.168.0.2/?cmd=39
CGI Parameter Valid values Description
cmd 39 Command 39: Reset device (Power Ports and your configuration remain untouched)

CGI POST Request

Commands to the EPC are sent as an HTTP-POST-request, the following you will find a list of commands and the respective required CGI parameters.

Upload file

i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=0
CGI Parameter Valid values Description
type [0,1,2] 0: Upload firmware (.bin)
1: Upload SSL certificate (.pem)
2: Upload config (.txt)
file [bin/pem/txt] Represented as binary, BODY-TYPE: multipart/form-data 
REQUIRES Reset

JSON Data

All dynamic data of the EPC can be requested as JSON formatted data via HTTP.

Advice: http://json.org/

Variable datas are divided into two categories.

  • Status values
    • available in JSON format with statusjsn.js
    • available for user and admin
  • Configuration values
    • available in JSON format with cfgjsn.js
    • available for admin


When JSON datas are requested, you have to decide which parts of the datas should be transmitted. This happens with the CGI Parameter components.

components has to be transmitted as decimal CGI parameter, by setting single bits you determine which parts of the dynamic datas you need.

  • status.html
    • One additional example gives status.html
    • This one gets all status and all configuration values via HTTP-GET-Request and depicts these hierarchically in the browser after receiving.


Status values from statusjsn.js

JSON object name Components
(decimal)		 Compontents
(hexadecimal)		 Description
outputs 1 0x00000001 Output status
inputs 2 0x00000002 Internal inputs status
dns_cache 4 0x00000004 Content of the actual DNS cache
ethernet 8 0x00000008 Ethernet status / counter
misc 16 0x00000010 Miscellaneous status info (Firmware version, Bootloader version, etc.)
events 128 0x00000080 Message-events counter
port_summary 256 0x00000100 Summarized status information of the outputs and inputs
hardware 512 0x00000200 Summarized status information of the general hardware
gsm_status 1024 0x00000400 Status information for GSM products
gsm_log 2048 0x00000800 Call-log for GSM products
gsm_counters 4096 0x00001000 Summarized status information for GSM products
sim 8192 0x00002000 Sim card status for GSM products
sensor_values 16384 0x00004000 Actual values of available sensors (temperature, etc.)
sensor_descr 65536 0x00010000 Field description of the actual available sensors (temperature, etc.)


status 'outputs'

components = 1 (Bit-0)

Variable Data type Description Possible values
status['outputs'] array Array with N elements, N=number of outputs
status['outputs'][n] object Compilation of status information per output
status['outputs'][n].name String Output name E.g. “Power Port 1”
status['outputs'][n].state Number Switching status 0=switched off
1=switched on
status['outputs'][n].type Number Output type 0=Powerport1
1=GPIO output
status['outputs'][n].batch array batch[0]: total waiting time in seconds
batch[1]: remaining waiting time in seconds
batch[2]: switching sequence (binary)
batch[3]: total number of switching commands
batch[4]: number of the current
batch[5]: reason of Batch mode

i.E.: 

"outputs": [
  {
    "name": "Power Port 1",
    "state": 1,
    "type": 1,
    "batch": [0, 0, 0, 0, 0],
    "wdog": [0, 2, "0.0.0.0"]
  },
  {
    [ ... ]
  }
]

status 'sensor_values'

components=16384

please refer to HTTP JSON Sensor Data

status 'sensor_descr'

components=65536

please refer to HTTP JSON Sensor Data

Configuration values from cfgjsn.js

JSON object name Components
(decimal)		 Compontents
(hexadecimal)		 Description
mail 2 0x00000002 Mail client/server configuration
http 4 0x00000004 HTTP server configuration
messages 32 0x00000020 Configuration of which sensors/measurement modules send messages
syslog 64 0x00000040 Syslog configuration
port_cfg 128 0x00000080 Outputs configuration (Power ports)
ipv4 256 0x00000100 IP configuration (IP address, network mask, etc.)
ipacl 512 0x00000200 IP-ACL configuration (filter list)
beeper 1024 0x00000400 Possibly integrated beeper (alarm transmitter) configuration
snmp 2048 0x00000800 SNMP configuration
input_cfg 4096 0x00001000 Input configuration
gsm_codes 8192 0x00002000 GSM code configuration (for products with GSM)
gsm_numbers 16384 0x00004000 Configuration of some special GSM phone numbers (for products with GSM)
gsm_phonebook 32768 0x00008000 Configuration of a GSM phone number list (for products with GSM)
gsm_flags 65536 0x00010000 Individual GSM features configuration (for products with GSM)
gsm_provider 131072 0x00020000 Configuration of GSM provider specific numbers (for products with GSM)

Easy code examples

The following examples switch on the first output each and show the switching status of all outputs.

The examples use a combination of:

  • transferring of one HTTP GET Request with CGI data (here: output-1 switch on)
  • the subsequent output of status information (JSON parse) (here: output of names and switching status of all outputs)

If your development environment has methods of sending HTTP-GET Requests and methods of parsing JSON-data, you can accordingly implement the mentioned examples below.

Perl Example

#!/usr/bin/perl
use LWP::UserAgent;
use JSON;

$browser = LWP::UserAgent->new;
$response = $browser->get("http://192.168.0.2/statusjsn.js?components=1&cmd=1&p=1&s=1");

if ($response->is_success) {
  $json = decode_json($response->content);
  foreach my $output(@{$json->{outputs}}) {
    print $output->{name} . " is " . ($output->{state} ? "on" : "off") . "\n";
  }
}

Downloads:

PHP Example

<?php
  $data = file_get_contents('http://192.168.0.2/statusjsn.js?components=1&cmd=1&p=1&s=1');
  if ($data) {
    $json = json_decode($data);
    foreach ($json->outputs as $output) {
      echo $output->name . ' is ' . ($output->state ? 'on' : 'off') . PHP_EOL;
    }
  }
?>

C++/Qt Example

  • main.cpp
#include <QApplication>
#include <QDebug>
#include <QtScript>
#include "main.h"  

QUrl url("http://192.168.0.2/statusjsn.js?components=1&cmd=1&p=1&s=1");

QEpcDemo::QEpcDemo() {
    connect(&manager, SIGNAL(finished(QNetworkReply*)),
            this, SLOT(httpReplyFinished(QNetworkReply*)));
}

void QEpcDemo::startGetRequest() {
    manager.get(QNetworkRequest(url));
}

void QEpcDemo::httpReplyFinished(QNetworkReply* reply) {
    int ret = 1;

    if (reply->error() == QNetworkReply::NoError) {
        QScriptEngine engine;
        QScriptValue sv = engine.evaluate("(" + QString(reply->readAll()) + ")");
        int i = sv.property("outputs").property("length").toInteger();
        QScriptValueIterator it(sv.property("outputs"));
        while ((i-- > 0) && it.hasNext()) {
            it.next();
            QString name(it.value().property("name").toString());
            int state = it.value().property("state").toInteger();
            qDebug() << QString("'%1' is %2")
                .arg(name)
                .arg(state ? QString("on") : QString("off"));
        }
        ret = 0;
    } else {
        qDebug()
            << "httpReplyFinished ERROR: "
            << reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt()
            << reply->error()
            << reply->errorString();
    }

    reply->deleteLater();
    QApplication::exit(ret);
}

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QEpcDemo epcdemo;
    epcdemo.startGetRequest();
    return app.exec();
}
  • main.h
#include <QObject>
#include <QtNetwork>

class QEpcDemo : public QObject
{
    Q_OBJECT
public:
    QEpcDemo();
    void startGetRequest();
private:
    QNetworkAccessManager manager;
private slots:
    void httpReplyFinished(QNetworkReply*);
};

Advanced code examples

Measurement values and sensors

  • http_sensor_value.pl:
    • uses combination from 'sensor_descr' and 'sensor_values' to output a list of all sensor values on the console

using JSON Query tool: jq

Sometimes you can omit using a programming language by using wget plus jq as HTTP/Json toolset combination. Lets say you want to send a certain temperature sensor value via SMS, using your ISP's SMS Gatway. 

# get sensor value by HTTP/Json:
TEMPERATURE=`wget http://192.168.0.1/statusjsn.js?components=81920 -o /dev/null -O - | jq '.sensor_values[0].values[0][0].v'`

echo "Temperature is : $TEMPERATURE"

# send value to your SMS gateway
wget "https://my.sms.gateway/?text=Temperature:%20"$TEMPERATURE"&to=0170-555666" --username=smsGwUsername --password=smsGwPassword

HTTP authentication

Basic authentication

  • when HTTP-password protection is activated, the HTTP-server requires HTTP-GET-Requests incl. of the so-called Basic Authentication Credentials
  • if the Basic Authentication Credentialsare missing when http-password protection is activated, or the transmitted password therein is incorrect, the HTTP server replies with the HTTP Error Code 401 (Unauthorized)

Examples

  • assumed the password for the user named user would be secret
  • the Basic-Auth-Credentials in the HTTP Header have to be
    • Authorization:Basic dXNlcjpnZWhlaW0=
    • because the character string user:secret is dXNlcjpnZWhlaW0= in Base64 spelling
  • a complete GET-Request which switches on the first power port is as follows:
GET /?cmd=1&p=1&s=1 HTTP/1.0
Authorization:Basic dXNlcjpnZWhlaW0=
  • in hexadecimal spelling as byte string:
47 45 54 20 2f 3f 63 6d  64 3d 31 26 70 3d 31 26  |GET /?cmd=1&p=1&|
73 3d 31 20 48 54 54 50  2f 31 2e 30 0d 0a 41 75  |s=1 HTTP/1.0..Au|
74 68 6f 72 69 7a 61 74  69 6f 6e 3a 42 61 73 69  |thorization:Basi|
63 20 64 58 4e 6c 63 6a  70 6e 5a 57 68 6c 61 57  |c dXNlcjpnZWhlaW|
30 3d 0d 0a 0d 0a                                 |0=....|

wget

  • wget offers the opportunity to use HTTP client implementation to create such GET-Requests and is thereby especially suitable for script or machine controlled, automatic switching.
  • Examples:

Switching without HTTP implementation

  • if you have no HTTP implementation at hand, when using a media control system for example, you can still switch via HTTP by sending a byte string (like above mentioned) to the HTTP port as an individual TCP package (usually to TCP Port 80).

REST API compliance

  • you have to use HTTP-GET-Requests to get JSON data (device status and device configuration)
  • to modifiy device config and device status, you have to use HTTP-GET-Requests plus CGI Paramater, as so called Query String as part of the URL

This makes the HTTP Api Rest Level 1 compliant. Links:

Abgerufen von „https://wiki.gude-systems.com/index.php?title=EPC_HTTP_Interface&oldid=1067“