Quelltext der Seite EPC HTTP Interface

Im folgenden finden Sie eine Beschreibung der HTTP-Programmierschnittstelle für die ExpertPowerControl Serie (kurz: EPC) der neuesten Generation.

Dies betrifft die Produkte:
* Expert Power Control NET D4x 1200, ab Firmware v2.1.1
* expert net control 2i2o 2100/2150, ab Firmware v1.1.0
* expert net control 2so 2101/2151, ab Firmware v1.0.0
* Expert Power Control NET 8x 8210 / 8211, ab Firmware v4.0.0
* Expert Power Control NET 4x 8212/8213, ab Firmware v4.0.0


=Ü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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! 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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! 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:<br>0: ausschalten, 1: einschalten
|-
| a2 || [0,1] || Aktion Nummer2:<br>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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 2 || Kommando 2: Batchmode abbrechen
|-
| p || [1,2, ... , N] || Nummer des zu Ausgangs (Powerport)
|}


==Konfiguration: Ausgänge==
 Bsp: http://admin:geheim@192.168.0.2/?cmd=3&components=128&p=1&name=Output+1&powup=0&powrem=0&idle=0&on_again=0&we=0&wip=&wt=0&wport=80&wint=10&wret=6
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! 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<br>1: nach Gerätestart Ausgang einschalten
|-
| powrem || [0, 1] || 0: aktuellen Schaltzustand für den nächsten Gerätestart nicht merken<br>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<br>0=keine Wartezeit
|-
| on_again || [0 .. N] || Anzahl der Wartezeit in Sekunden nach Ausschalten eines Ausgangs vor automatischen Wiedereinschalten, 0=kein automatisches Wiedereinschalten
|-
| we || [0, 1] || 0=Watchdog deaktiviert<br>1=Watchdog aktiviert
|-
| wip || Zeichenkette || Hostname (FQDN) oder IP Adresse des zu des überwachenden Hosts
|-
| wt || [0, 1] || 0=Watchdog verwendet ICMP Pings<br>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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 13 || Kommando 13: Eingang konfigurieren
|-
| p || [1,2, ... , N] || Nummer des zu konfigurierenden Eingangs (Powerport)
|-
| name || Zeichenkette mit maximal 15 Zeichen || Name des Ausgangs
|}


==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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! 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<br>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=
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 6 || Kommando 6: IP-ACL konfigurieren
|-
| ping || [0, 1] || 0: nicht auf ''ICMP Echo-Request'' Anfragen antworten<br>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 <br>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=18apwd=admin&upwd=user&port=80&pwd=1&refr=1&sprp=0
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 18 || Kommando 18: HTTP konfigurieren
|-
| pwd || [0, 1] || 0: HTTP Authentifizierung ausschalten<br>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)<br>0: Autorefresh ausgeschaltet, 1: Autorefresh eingeschaltet
|-
| sprp || [0,1] || 0=keine Benutzer-Authentifizierung verlangen für ov.html<br>1=Benutzer Authentifizierung verlangen für ov.html (start-page-requires-password)
|}


==Konfiguration: SNMP==
 Bsp: http://192.168.0.2/cmd=8get=1&set=1&trap=1&cpub=public&cpriv=private&trapv=2&tr0=192.168.0.100&tr1=&tr2=&tr3=&tr4=&tr5=&tr6=&tr7=
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 8 || Kommando 8: SNMP konfigurieren
|-
| get || [0, 1] || 0: keine SNMP-Get Anfragen beantworten<br>1: SNMP-Get Anfragen bei gültiger public-community beantworten
|-
| set || [0, 1] || 0: keine SNMP-Set Anfragen beantworten<br>1: SNMP-Set Anfragen bei gültiger private-community beantworten
|-
| trap || [0, 1] || 0: keine SNMP-traps verschicken<br>1: SNMP-traps verschicken 
|-
| trapv || [1,2] || 1: versende SNMP-v1 traps<br>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
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 17 || Kommando 17: Syslog konfigurieren
|-
| syslog || [0, 1] || 0: syslog ausgeschaltet<br>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&components=2&mail=1&auth=0&mailsrv=mx.mydomain.de&sender=epc%40mydomain.de&email=user%40mydomain.de
{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! CGI Parameter !! gültige Werte !! Beschreibung
|-
| cmd || 15 || Kommando 15: E-Mail konfigurieren
|-
| mail || [0, 1] || 0: E-Mail Benachrichtigungen deaktiviert<br>1: E-Mail Benachrichtigungen aktiviert
|-
| auth || [0, 1] || 0: mit E-Mail Server ohne SMTP-Authentifizierung verbinden<br>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)

{| border="1" cellpadding=3 cellspacing=0
|- bgcolor="#f9f9f9"
! 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";
   }
 }

==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. [http://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication Basic Authentication Credentials]
* fehlen bei eingeschaltetem HTTP-Passwortschutz die [http://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication 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 [http://de.wikipedia.org/wiki/Base64 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 Beispiele==
*[http://gnuwin32.sourceforge.net/packages/wget.htm wget] bietet die Möglichkeit eine HTTP Client zu verwenden um deratige GET Requests zu erzeugen, und eignet sich damit besonders für Script- bzw. Maschienengesteuertes, automatisiertes schalten.
* verwendet 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
* verwendet 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
* verwendet den Benutzer ''user'' und das Password ''geheim''
** wget "http://user:geheim@192.168.0.1/?cmd=1&p=1&s=1" --auth-no-challenge