EPC HTTP Interface

Aus Gude Systems GmbH
Zur Navigation springen Zur Suche springen
  • 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.


  • 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 aus statusjsn.js

json object name compontents
(dezimal)		 compontents
(hexadezimal)		 Beschreibung
outputs 1 0x00000001 Status Ausgänge
inputs 2 0x00000002 Status interne Eingänge
dns_cache 4 0x00000004 Inhalt des aktuellen DNS Caches
ethernet 8 0x00000008 Ethernet Status/Zähler
misc 16 0x00000010 Diverses Status infos (Firmwave Version, Bootloader Version, etc)
events 128 0x00000080 Zähler von Message-Events
port_summary 256 0x00000100 zusammenfassende Status Informationen von Aus- und Eingängen
hardware 512 0x00000200 zusammenfassende Status Informationen zur Hardware im allgemeinen
gsm_status 1024 0x00000400 Status informationen bei GSM produkten
gsm_log 2048 0x00000800 Anruf-log bei GSM produkten
gsm_counters 4096 0x00001000 zusammenfassende Status Informationen bei GSM produkten
sim 8192 0x00002000 Zustand der SIM Karte bei GSM produkten
sensor_values 16384 0x00004000 Aktuelle Werte der vorhandenen Sensoren (Temperatur, etc)
sensor_descr 65536 0x00010000 Feld-Beschreibung der aktuell vorhandenen Sensoren (Temperatur, etc)


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"]
  },
  {
    [ ... ]
  }
]

Konfigurations Werte aus cfgjsn.js

json object name compontents
(dezimal)		 compontents
(hexadezimal)		 Beschreibung
mail 2 0x00000002 Mail Client/Server Konfiguration
http 4 0x00000004 HTTP Server Konfiguration
messages 32 0x00000020 Konfigration welche Sensoren/Messeinheiten Nachrichten versenden
syslog 64 0x00000040 Syslog Konfiguration
port_cfg 128 0x00000080 Konfiguration Ausgänge (Powerports)
ipv4 256 0x00000100 IP Konfigration (IP Adresse, Netzwerkmaske, etc)
ipacl 512 0x00000200 Konfiguration der IP-ACL (Filter Liste)
beeper 1024 0x00000400 Konfiguration des u.U. integrierten Beeper (Alarmgebers)
snmp 2048 0x00000800 SNMP Konfiguration
input_cfg 4096 0x00001000 Input Konfiguration
gsm_codes 8192 0x00002000 Konfiguration des GSM Codes (bei Produkten mit GSM)
gsm_numbers 16384 0x00004000 Konfiguration einiger spezieller GSM Telefonnummern (bei Produkten mit GSM)
gsm_phonebook 32768 0x00008000 Konfiguration einer GSM Telefonnummern-liste (bei Produkten mit GSM)
gsm_flags 65536 0x00010000 Konfiguration einzelner GSM Features (bei Produkten mit GSM)
gsm_provider 131072 0x00020000 Konfiguration der GSM Provider spezifischen Nummern (bei Produkten mit GSM)


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:


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)
Abgerufen von „https://wiki.gude-systems.com/index.php?title=EPC_HTTP_Interface&oldid=278“