EPC HTTP Interface: Unterschied zwischen den Versionen
Mb (Diskussion | Beiträge) |
Mb (Diskussion | Beiträge) |
||
Zeile 518: | Zeile 518: | ||
# get sensor value by HTTP/Json: | # 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'` | 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 SMS gateway | # send value to SMS gateway |
Version vom 1. März 2017, 13:30 Uhr
- Below 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 between CGI and JSON via HTTP is described
- If your device is equipped with the resource status.html, the following information can be used. If not, your device is unfortunately not compatible to this description.
Overview
- The following section describes how you can send commands to the EPC via HTTP, and how to evaluate dynamic status or configuration values via HTTP.
- For example, a command can be the instruction to the EPC to turn on an output or to save a configuration value.
- With reports of status or configuration values the question is meant for example: “Is output number 1 switched on?” or “Is Syslog switched on?”
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 |
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 |
[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 |
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)
- o You want to receive the status of the inputs (set Bit-1, see below)
- o You want to receive the status of the outputs and the inputs together (set Bit-0 and Bit-1, see below)
- 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"] }, { [ ... ] } ]
Configuration values from cfgjsn.js
JSON object name | Components (decimal) |
Compontents (hexadecimal) |
Description |
---|---|---|---|
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"; } }
download epccontrol3.pl for a more powerfull perl example
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 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
- use the user, and request the password:
Switching without HTTP implementation
- if you have no HTTP implementation on 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).