EPC HTTP Interface: Unterschied zwischen den Versionen

Aus Gude Systems GmbH
Zur Navigation springen Zur Suche springen
Zeile 333: Zeile 333:
 
   }
 
   }
 
  }
 
  }
 +
 +
download [http://wiki.gude.info/images/8/8b/Epccontrol3.zip epccontrol3.pl] for a more powerfull perl example
 +
  
 
==PHP Beispiel==
 
==PHP Beispiel==

Version vom 7. Oktober 2013, 10:49 Uhr

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.0f
  • 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
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)


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
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
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
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
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=18apwd=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=8get=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&components=2&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

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:


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=260“