EPC HTTP Interface

• Im folgenden finden Sie eine Beschreibung der HTTP-Programmierschnittstelle für die ExpertPowerControl Serie der neueren Generation
• Als Interface wird hier Kombination aus CGI und JSON über HTTP erleutert
• Wenn Ihr Gerät über die Ressource status.html verfügt, so können Sie die folgenden Information anwenden. Falls nicht, so ist Ihr Gerät zu dieser Beschriebung inkompatibel

Übersicht

• Im folgenden wird beschrieben wie Sie Kommandos an den EPC über HTTP senden können, und wie sie dynamische Status- bzw. Konfigurations-Werte über HTTP auswerten können.
  • Ein Kommando kann z.B. die Anweisung an den EPC sein einen Ausgang einzuschalten, oder einen Konfigurationswert zu speichern.
  • mit Auswertungen von Status- bzw. Konfigurationswerten ist z.B. die Frage gemeint: "Ist Ausgang Nummer-1 eingeschaltet?", oder "Ist Syslog eingeschaltet?"

CGI GET Request

Kommandos an den EPC werden als HTTP-GET-Request verschickt, im folgenden finden Sie eine Auflistung der Kommandos sowie der jeweils benötigten CGI Paramater.

Ausgang schalten (einfaches Schaltkommando)

Bsp: http://user:gehein@192.168.0.2/ov.html?cmd=1&p=1&s=1

CGI Parameter	gültige Werte	Beschreibung
cmd	1	Kommando 1: Ausgang schalten
p	[1,2, ... , N]	Nummer des zu schaltenden Ausgangs (Powerport)
s	[0,1]	0: ausschalten, 1: einschalten

Ausgang schalten (Schalten in Serie, Batchmode)

Batchmode starten

Bsp: http://user:geheim@192.168.0.2/?cmd=5&p=1&a1=0&a2=1&s=5

CGI Parameter	gültige Werte	Beschreibung
cmd	5	Kommando 5: Batchmode
p	[1,2, ... , N]	Nummer des zu schaltenden Ausgangs (Powerport)
a1	[0,1]	Aktion Nummer1: 0: ausschalten, 1: einschalten
a2	[0,1]	Aktion Nummer2: 0: ausschalten, 1: einschalten
s	[1..65535]	Wartezeit in Sekunden zwischen Aktion1 und Aktion2

Batchmode abbrechen

Bsp: http://user:geheim@192.168.0.2/?cmd=2&p=1

CGI Parameter	gültige Werte	Beschreibung
cmd	2	Kommando 2: Batchmode abbrechen
p	[1,2, ... , N]	Nummer des zu Ausgangs (Powerport)

Reset

Reset ist ein vorkonfigurierter Batchmode, welcher ausschaltet, und nach einer konfigurierbaren Zeit wieder einschaltet. (siehe : Konfiguration: Ausgänge)

Bsp: http://user:geheim@192.168.0.2/?cmd=12&p=2

CGI Parameter	gültige Werte	Beschreibung
cmd	12	Kommando 12: Reset durchführen
p	[1,2, ... , N]	Nummer des Ausgangs an dem ein Reset durchgeführt werden soll

Konfiguration: Ausgänge

Bsp: http://admin:geheim@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	gültige Werte	Beschreibung
cmd	3	Kommando 3: Ausgang (Powerport) konfigurieren
p	[1,2, ... , N]	Nummer des zu konfigurierenden Ausgangs (Powerport)
name	Zeichenkette mit maximal 15 Zeichen	Name des Ausgangs
powup	[0, 1]	0: nach Gerätestart Ausgang ausgeschaltet lassen 1: nach Gerätestart Ausgang einschalten
powrem	[0, 1]	0: aktuellen Schaltzustand für den nächsten Gerätestart nicht merken 1: aktuellen Schaltzustand für den nächsten Gerätestart merken
idle	[0 .. N]	Anzahl der Wartezeit in Sekunden nach Gerätestart vor etwaigen Einschalten des Ausgangs 0=keine Wartezeit
on_again	[0 .. N]	Anzahl der Wartezeit in Sekunden nach Ausschalten eines Ausgangs vor automatischen Wiedereinschalten, 0=kein automatisches Wiedereinschalten
reset	[1 .. N]	Reset duration: Dauer der Power-down Phase in Sekunden beim Reset Kommando
we	[0, 1]	0=Watchdog deaktiviert 1=Watchdog aktiviert
wip	Zeichenkette	Hostname (FQDN) oder IP Adresse des zu des überwachenden Hosts
wt	[0, 1]	0=Watchdog verwendet ICMP Pings 1=watchdog verwendet TCP handshakes
wport	[1..65535]	TCP Portnummer falls wt=1
wint	[1..65535]	Watchdog Ping Interval in Sekunden
wret	[1..65535]	Watchdog Ping Retry: Anzahl der Ping-Signale die unbeantwortet bleiben müssen um den Watchdog Zustand 'Host ausgefallen' einzunehmen

Konfiguration: Eingänge

Bsp: http://admin:geheim@192.168.0.2/?cmd=13&p=1&name=Input+1&hitext=closed&lowtext=open&inverted=1&msgt=0

CGI Parameter	gültige Werte	Beschreibung
cmd	13	Kommando 13: Eingang konfigurieren
p	[1,2, ... , N]	Nummer des zu konfigurierenden Eingangs
name	Zeichenkette mit maximal 15 Zeichen	Name des Eingangs
hitext	Zeichenkette mit maximal 15 Zeichen	Name des logical-1 Zustandes
lowtext	Zeichenkette mit maximal 15 Zeichen	Name des logical-0 Zustandes
inverted	[0,1]	invertiert bei inverted=1 den physical state des Inputs. Bei inverted=0 gilt: physical state = logical state
msgt	[0,1]	Generate messages: bei msgt=1 werden Nachrichten erzeugt (ggf. Syslog, Mail und SNMP-Trap) bei Input-Zustandsänderungen

Konfiguration: IPv4 Netzwerk

Bsp: http://admin:gehein@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	gültige Werte	Beschreibung
cmd	4	Kommando 4: Ipv4 Netzwerk Konfiguration
host	Zeichenkette mit maximal 15 Zeichen	hostname (fqdn)
ip	Zeichenkette mit maximal 15 Zeichen	IPv4 Adresse
nm	Zeichenkette mit maximal 15 Zeichen	IPv4 Netzwerkmaske
gw	Zeichenkette mit maximal 15 Zeichen	IPv4 Adresse eines externen Gateways
dns	Zeichenkette mit maximal 15 Zeichen	IPv4 Adresse eines externen DNS-Servers
dhcp	[0, 1]	0: DHCP ausgeschaltete 1: nach Gerätestart DHCP Anfrage starten

Konfiguration: IP Filter (IP-ACL, IP Access Control List)

Bsp: http://admin:geheim@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	gültige Werte	Beschreibung
cmd	6	Kommando 6: IP-ACL konfigurieren
ping	[0, 1]	0: nicht auf ICMP Echo-Request Anfragen antworten 1: auf ICMP Echo-Request Anfragen mit ICMP Echo-Reply antworten
acl	[0, 1]	0: IP-Filter deaktivieren, der IPv4 Zugriff wird nicht eingeschränkt 1: IP-Filter aktivieren, nur Geräte oder Netzwerke genannt in ipsec0 bis ipsec7 haben IPv4 Zugriff
ipsec0	Zeichenkette mit maximal 18 Zeichen	Host- bzw. Netzwerk-Adresse dem der IPv4 Zugriff bei eingeschaltetem IP-Filter gewährt werden soll (CIDR Schreibweise, z.B. 10.0.0.0/24)
ipsec1 .. ipsec7	wie ipsec0	wie ipsec0

Konfiguration: HTTP

Bsp: http://admin:geheim@192.168.0.2/cmd=18&apwd=admin&upwd=user&port=80&pwd=1&refr=1&sprp=0

CGI Parameter	gültige Werte	Beschreibung
cmd	18	Kommando 18: HTTP konfigurieren
pwd	[0, 1]	0: HTTP Authentifizierung ausschalten 1: HTTP Authentifizierung (HTTP Auth-Basic), Passwörter für 'user' bzw 'admin' werden erforderlich
apwd	Zeichenkette mit maximal 15 Zeichen	Passwort des Benutzers 'admin'
upwd	Zeichenkette mit maximal 15 Zeichen	Passwort des Benutzers 'user'
port	[1..65535]	HTTP Server Port
refr	[0,1]	HTTP Auto Refresh (automatisches Aktualisieren der Status Information im Web-Browser) 0: Autorefresh ausgeschaltet, 1: Autorefresh eingeschaltet
sprp	[0,1]	0=keine Benutzer-Authentifizierung verlangen für ov.html 1=Benutzer Authentifizierung verlangen für ov.html (start-page-requires-password)

Konfiguration: SNMP

Bsp: 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	gültige Werte	Beschreibung
cmd	8	Kommando 8: SNMP konfigurieren
get	[0, 1]	0: keine SNMP-Get Anfragen beantworten 1: SNMP-Get Anfragen bei gültiger public-community beantworten
set	[0, 1]	0: keine SNMP-Set Anfragen beantworten 1: SNMP-Set Anfragen bei gültiger private-community beantworten
trap	[0, 1]	0: keine SNMP-traps verschicken 1: SNMP-traps verschicken
trapv	[1,2]	1: versende SNMP-v1 traps 2: versende SNMP-v2 traps
cpub	Zeichenkette mit maximal 15 Zeichen	Name der public SNMP-Community
cpriv	Zeichenkette mit maximal 15 Zeichen	Name der private SNMP-Community
cpriv	Zeichenkette mit maximal 15 Zeichen	Name der private SNMP-Community
tr0	Zeichenkette mit maximal 100 Zeichen	IPv4 Adresse oder FQDN des externen SNMP-trap-receivers, ggf. mit alternativer Portangabe, z.B. nagios.mydomain.de:10161
tr1 .. tr7	wie tr0	wie tr0

Konfiguration: Syslog

Bsp: http://admin:geheim@192.168.0.2/?cmd=17&syslog=1&slgsrv=192.168.0.100

CGI Parameter	gültige Werte	Beschreibung
cmd	17	Kommando 17: Syslog konfigurieren
syslog	[0, 1]	0: syslog ausgeschaltet 1: versende syslog nachrichten
slgsrv	Zeichenkette mit maximal 100 Zeichen	IPv4 Adresse oder FQDN des externen syslog Servers, ggf. mit alternativer Portangabe, z.B. nagios.mydomain.de:10514

Konfiguration E-Mail

Bsp: http://admin:geheim@192.168.0.2/?cmd=15&mail=1&auth=0&mailsrv=mx.mydomain.de&sender=epc%40mydomain.de&email=user%40mydomain.de

CGI Parameter	gültige Werte	Beschreibung
cmd	15	Kommando 15: E-Mail konfigurieren
mail	[0, 1]	0: E-Mail Benachrichtigungen deaktiviert 1: E-Mail Benachrichtigungen aktiviert
auth	[0, 1]	0: mit E-Mail Server ohne SMTP-Authentifizierung verbinden 1: E-Mail Server SMTP-Authentifizierung (PLAIN) verbinden
mailsrv	Zeichenkette mit maximal 100 Zeichen	IPv4 Adresse oder FQDN des externen SMTP Servers, ggf. mit alternativer Portangabe, z.B. mymx.mydomain.de:10125
sender	Zeichenkette mit maximal 100 Zeichen	Sender (From) Adresse
email	Zeichenkette mit maximal 100 Zeichen	Empfänger (To) Adresse

JSON Daten

Alle dynamischen Daten des EPCs können als JSON Formatierte Daten per HTTP abgefragt werden.

Hinweis: http://json.org/

Variable Daten werden in in zwei Kategorien eingeteilt.

• Status Werte
  • verfügbar im JSON-Format mit statusjsn.js
  • verfügbar für user und admin

• Konfigurations Werte
  • verfügbar im JSON-Format mit cfgjsn.js
  • verfügbar für admin

Beim Anfragen der JSON Daten muss jeweils von Ihnen entschieden werden welche Teile der Daten übertragen werden sollen. Dies geschieht mit dem CGI Paramater components.

components muss als dezimaler CGI Parameter übertragen werden, durch setzen einzelner Bits bestimmen Sie welche Teile der dynamischen Daten Sie benötigen.

• Beispiele:
  • Sie möchten den Status der Ausgänge erhalten (setzen Sie Bit-0, siehe unten)
    • wget "http://admin:geheim@192.168.0.2/statusjsn.js?components=1"
  • Sie möchten den Status der Eingänge erhalten (setzen Sie Bit-1, siehe unten)
    • wget "http://admin:geheim@192.168.0.2/statusjsn.js?components=2"
  • Sie möchten den Status der Ausgänge und Eingänge zusammen erhalten (setzen Sie Bit-0 und Bit-1, siehe unten)
    • wget "http://admin:geheim@192.168.0.2/statusjsn.js?components=3"
  • Sie möchten alle Status Informationen erhalten
    • wget "http://admin:geheim@192.168.0.2/statusjsn.js?components=1073741823"
    • Hinweis: 1073741823 entspricht 0x3fffffff

• status.html
  • Ein weiteres Beispiel gibt status.html
  • Diese holt sich alle Status- und alle Konfigurations-Werte per HTTP-GET-Request, und stellt diese nach Erhalt hierarchisch im Browser da.

Status Werte

status 'outputs'

components = 1 (Bit-0)

Variable	Datentyp	Beschreibung	mögliche Werte
status['outputs']	array	array mit N Elementen, N=Anzal der Outputs
status['outputs'][n]	object	zusammenstellen der Status Informationen pro Output
status['outputs'][n].name	String	Name des Outputs	z.B. "Power Port 1"
status['outputs'][n].state	Number	Schaltzustand	0=ausgeschaltet, 1=eingeschaltet
status['outputs'][n].type	Number	Output Typ	0=Powerport, 1=GPIO output

Bsp:

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

Code Beispiele

Die folgenden Beispiele schalten jeweils den ersten Output ein, und geben den Schaltzustand aller Outputs aus.

Die Beispiele verwenden eine Kombination aus:

• dem Übermitteln eines HTTP GET Request mit CGI Daten (hier: Ausgang-1 einschalten)
• der anschließenden Ausgabe von Status Informationen (JSON parse) (hier: Ausgabe der Namen und Schaltzustände aller Ausgänge)

Verfügt Ihre Entwicklungsumgebung Methoden zum Versenden von HTTP-GET-Requests, und Methoden zum Parsen von JSON-Daten, so können Sie die unten angegebenen Beispiele entsprechend umsetzen.

Perl Beispiel

#!/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";
  }
}

download epccontrol3.pl for a more powerfull perl example

PHP Beispiel

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

• 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*);
};

HTTP Authentifizierung

Basic Authentication

• der HTTP-Server verlangt, bei eingeschaltetem HTTP-Passwortschutz, HTTP-GET-Requests inklusive der sog. Basic Authentication Credentials
• fehlen bei eingeschaltetem HTTP-Passwortschutz die Basic Authentication Credentials, oder ist das darin übermittelte Passwort falsch, so Antwortet der HTTP Server mit dem HTTP Error Code 401 (Unauthorized)

Beispiele

• angenommen das Passwort für den Benutzer Namens user sei geheim
• die Basic-Auth-Credentials im HTTP Header müssen dann lauten
  • Authorization:Basic dXNlcjpnZWhlaW0=
  • denn die Zeichenkette user:geheim lautet in der Base64 Schreibweise: dXNlcjpnZWhlaW0=
• ein kompletter GET-Request welcher den ersten Powerport einschaltet sieht demnach folgendermaßen aus:

GET /?cmd=1&p=1&s=1 HTTP/1.0
Authorization:Basic dXNlcjpnZWhlaW0=

• in hexadezimaler Schreibweise als Byte-Kette:

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 bietet die Möglichkeit eine HTTP-Client-Implementierung zu verwenden um derartige GET-Requests zu erzeugen, und eignet sich damit besonders für script- bzw. maschienengesteuertes, automatisiertes schalten.
• Beispiele:
  • verwende den Benutzer user, und frage das Passwort ab:
    • wget "http://192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge --user=user --ask-password
  • verwende den Benutzer user und das Password geheim
    • wget "http://192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge --user=user --password=geheim
  • verwende den Benutzer user und das Password geheim
    • wget "http://user:geheim@192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge

Schalten ohne HTTP Implementierung

• steht Ihnen keine HTTP Implementierung zur Verfügung, z.B. beim Einsatz einer Mediensteuerung, so können sie dennoch per HTTP schalten indem Sie eine wie oben gezeigte Byte-Kette zum HTTP Port als ein einzelnes TCP-Paket versenden (idR. zu TCP Port 80)