EPC HTTP Interface

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

• port.py : switch outlets, show outlet states
• check_gude.py : show sensor value(s)
• io.py : input->output interaction

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

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.

• Examples:
  • o You want to receive the status of the outputs (set Bit-0, see below)
    • wget "http://admin:secret@192.168.0.2/statusjsn.js?components=1"
  • o You want to receive the status of the inputs (set Bit-1, see below)
    • wget "http://admin:secret@192.168.0.2/statusjsn.js?components=2"
  • o You want to receive the status of the outputs and the inputs together (set Bit-0 and Bit-1, see below)
    • wget "http://admin:secret@192.168.0.2/statusjsn.js?components=3"
  • o You want to receive all status information
    • wget "http://admin:secret@192.168.0.2/statusjsn.js?components=1073741823"
    • Advice: 1073741823 conforms 0x3fffffff

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

• https://github.com/gudeads/port.py
• epccontrol2.pl epccontrol2 downward compatible perl script
• epccontrol3.pl perl script showing CGI/JSON in perl

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:
  • use the user, and request the password:
    • wget "http://192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge --user=user --ask-password
  • use the useruser and the Password secret
    • wget "http://192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge --user=user --password=secret
    • Advice: a batch file with such a wget one-liner can be easily started via Windows task scheduler to realize a time switch for example
  • use the user and the password secret
    • wget "http://user:secret@192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge

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:

• https://restfulapi.net/richardson-maturity-model/
• https://www.codementor.io/vit.brunner/the-levels-of-rest-jqi7zs9pe
• https://en.wikipedia.org/wiki/Representational_state_transfer