EPC HTTP Interface: Unterschied zwischen den Versionen
Mb (Diskussion | Beiträge) |
Fn (Diskussion | Beiträge) |
||
(28 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
− | + | =Overview= | |
− | |||
− | |||
− | + | * In this article, 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 of CGI and JSON via HTTP/HTTPS is described |
− | ** | + | |
− | ** | + | * You can send data to the device by sending HTTP-GET requests, along with CGI GET parameters |
+ | * The device will reply with data objects in [http://www.json.org JSON] format, representing the devices' (new) status or config values | ||
+ | |||
+ | =Quickstart= | ||
+ | If you want to quickstart, please take a look at our HTTP/HTTPS examples using Python | ||
+ | * [https://github.com/gudesystems/port.py port.py] : switch outlets, show outlet states | ||
+ | * [https://github.com/gudesystems/check_gude.py check_gude.py] : show sensor value(s) | ||
+ | * [https://github.com/gudesystems/io.py io.py] : input->output interaction | ||
Zeile 13: | Zeile 18: | ||
==Output switching (easy switching command)== | ==Output switching (easy switching command)== | ||
− | + | i.E. http://user:secret@192.168.0.2/ov.html?cmd=1&p=1&s=1 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 28: | Zeile 33: | ||
==Output switching (switching in series, Batch mode) == | ==Output switching (switching in series, Batch mode) == | ||
===Start Batch mode=== | ===Start Batch mode=== | ||
− | + | i.E. http://user:secret@192.168.0.2/?cmd=5&p=1&a1=0&a2=1&s=5 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 46: | Zeile 51: | ||
===Cancel Batch mode=== | ===Cancel Batch mode=== | ||
− | + | i.E. http://user:secret@192.168.0.2/?cmd=2&p=1 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 61: | Zeile 66: | ||
(see : [[#Configuration: Outputs|Configuration: Outputs]]) | (see : [[#Configuration: Outputs|Configuration: Outputs]]) | ||
− | + | i.E. http://user:secret@192.168.0.2/?cmd=12&p=2 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 73: | Zeile 78: | ||
==Configuration: Outputs== | ==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 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 112: | Zeile 117: | ||
==Configuration: Inputs== | ==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 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 135: | Zeile 140: | ||
==Configuration: IPv4 Network== | ==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 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 157: | Zeile 162: | ||
==Configuration: IP filter (IP-ACL, IP Access Control List)== | ==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= | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 196: | Zeile 201: | ||
==Configuration: SNMP== | ==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= | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 222: | Zeile 227: | ||
==Configuration: Syslog== | ==Configuration: Syslog== | ||
− | + | i.E. http://admin:secret@192.168.0.2/?cmd=17&syslog=1&slgsrv=192.168.0.100 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 236: | Zeile 241: | ||
==Configuration E-Mail== | ==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 | |
{| border="1" cellpadding=3 cellspacing=0 | {| border="1" cellpadding=3 cellspacing=0 | ||
|- bgcolor="#f9f9f9" | |- bgcolor="#f9f9f9" | ||
Zeile 252: | Zeile 257: | ||
|- | |- | ||
| email || Character string with maximum 100 characters || Receiver (To) address | | email || Character string with maximum 100 characters || Receiver (To) address | ||
+ | |} | ||
+ | |||
+ | == Reset device == | ||
+ | i.E. http://admin:secret@192.168.0.2/?cmd=39 | ||
+ | {| border="1" cellpadding=3 cellspacing=0 | ||
+ | |- bgcolor="#f9f9f9" | ||
+ | ! CGI Parameter !! Valid values !! Description | ||
+ | |- | ||
+ | | cmd || 39 || Command 39: Reset device (Power Ports and your configuration remain untouched) | ||
+ | |} | ||
+ | |||
+ | =CGI POST Request= | ||
+ | Commands to the EPC are sent as an HTTP-POST-request, the following you will find a list of commands and the respective required CGI parameters. | ||
+ | |||
+ | == File Upload == | ||
+ | |||
+ | REQUIRES [[EPC_HTTP_Interface#Reset_device]] after upload. | ||
+ | |||
+ | === Firmware Upload === | ||
+ | i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=0 | ||
+ | {| border="1" cellpadding=3 cellspacing=0 | ||
+ | |- bgcolor="#f9f9f9" | ||
+ | ! CGI Parameter !! Valid values !! Description | ||
+ | |- | ||
+ | | file || [bin] || binary, FORMDATA-BODY-TYPE: multipart/form-data | ||
+ | |} | ||
+ | |||
+ | === SSL Certificate Upload === | ||
+ | i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=1 | ||
+ | {| border="1" cellpadding=3 cellspacing=0 | ||
+ | |- bgcolor="#f9f9f9" | ||
+ | ! CGI Parameter !! Valid values !! Description | ||
+ | |- | ||
+ | | file || [pem] || binary, FORMDATA-BODY-TYPE: multipart/form-data | ||
+ | |} | ||
+ | |||
+ | === Config Upload === | ||
+ | i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=2 | ||
+ | {| border="1" cellpadding=3 cellspacing=0 | ||
+ | |- bgcolor="#f9f9f9" | ||
+ | ! CGI Parameter !! Valid values !! Description | ||
+ | |- | ||
+ | | file || [txt] || binary, FORMDATA-BODY-TYPE: multipart/form-data | ||
|} | |} | ||
Zeile 347: | Zeile 395: | ||
|} | |} | ||
+ | i.E.: | ||
− | |||
"outputs": [ | "outputs": [ | ||
{ | { | ||
Zeile 361: | Zeile 409: | ||
} | } | ||
] | ] | ||
+ | |||
+ | ===status 'sensor_values'=== | ||
+ | components=16384 | ||
+ | |||
+ | please refer to [[HTTP JSON Sensor Data]] | ||
+ | |||
+ | ===status 'sensor_descr'=== | ||
+ | components=65536 | ||
+ | |||
+ | please refer to [[HTTP JSON Sensor Data]] | ||
==Configuration values from cfgjsn.js== | ==Configuration values from cfgjsn.js== | ||
Zeile 423: | Zeile 481: | ||
} | } | ||
− | + | Downloads: | |
− | + | *https://github.com/gudeads/port.py | |
+ | *[http://files.gude.info/misc/epccontrol.zip epccontrol2.pl] epccontrol2 downward compatible perl script | ||
+ | *[http://wiki.gude.info/images/8/8b/Epccontrol3.zip epccontrol3.pl] perl script showing CGI/JSON in perl | ||
==PHP Example== | ==PHP Example== | ||
Zeile 512: | Zeile 572: | ||
** uses combination from 'sensor_descr' and 'sensor_values' to output a list of all sensor values on the console | ** 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 [http://gnuwin32.sourceforge.net/packages/wget.htm wget] plus [https://stedolan.github.io/jq/ 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 your SMS gateway | ||
+ | wget "https://my.sms.gateway/?text=Temperature:%20"$TEMPERATURE"&to=0170-555666" --username=smsGwUsername --password=smsGwPassword | ||
=HTTP authentication= | =HTTP authentication= | ||
Zeile 548: | Zeile 619: | ||
==Switching without HTTP implementation== | ==Switching without HTTP implementation== | ||
− | *if you have no HTTP implementation | + | *if you have no HTTP implementation at 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). |
+ | |||
+ | =REST API compliance= | ||
+ | *you have to use HTTP-GET-Requests to get JSON data (device status and device configuration) | ||
+ | *to modifiy device config and device status, you have to use HTTP-GET-Requests plus CGI Paramater, as so called [https://en.wikipedia.org/wiki/Query_string Query String] as part of the URL | ||
+ | This makes the HTTP Api Rest Level 1 compliant. | ||
+ | Links: | ||
+ | *https://restfulapi.net/richardson-maturity-model/ | ||
+ | *https://www.codementor.io/vit.brunner/the-levels-of-rest-jqi7zs9pe | ||
+ | *https://en.wikipedia.org/wiki/Representational_state_transfer |
Aktuelle Version vom 14. Mai 2024, 18:23 Uhr
Overview
- In this article, 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 of CGI and JSON via HTTP/HTTPS is described
- You can send data to the device by sending HTTP-GET requests, along with CGI GET parameters
- The device will reply with data objects in JSON format, representing the devices' (new) status or config values
Quickstart
If you want to quickstart, please take a look at our HTTP/HTTPS examples using Python
- port.py : switch outlets, show outlet states
- check_gude.py : show sensor value(s)
- io.py : input->output interaction
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 |
Reset device
i.E. http://admin:secret@192.168.0.2/?cmd=39
CGI Parameter | Valid values | Description |
---|---|---|
cmd | 39 | Command 39: Reset device (Power Ports and your configuration remain untouched) |
CGI POST Request
Commands to the EPC are sent as an HTTP-POST-request, the following you will find a list of commands and the respective required CGI parameters.
File Upload
REQUIRES EPC_HTTP_Interface#Reset_device after upload.
Firmware Upload
i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=0
CGI Parameter | Valid values | Description |
---|---|---|
file | [bin] | binary, FORMDATA-BODY-TYPE: multipart/form-data |
SSL Certificate Upload
i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=1
CGI Parameter | Valid values | Description |
---|---|---|
file | [pem] | binary, FORMDATA-BODY-TYPE: multipart/form-data |
Config Upload
i.E. http://admin:secret@192.168.0.2/fwupdate.html?type=2
CGI Parameter | Valid values | Description |
---|---|---|
file | [txt] | binary, FORMDATA-BODY-TYPE: multipart/form-data |
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"] }, { [ ... ] } ]
status 'sensor_values'
components=16384
please refer to HTTP JSON Sensor Data
status 'sensor_descr'
components=65536
please refer to HTTP JSON Sensor Data
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"; } }
Downloads:
- https://github.com/gudeads/port.py
- epccontrol2.pl epccontrol2 downward compatible perl script
- epccontrol3.pl perl script showing CGI/JSON in perl
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 your 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 at 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).
REST API compliance
- you have to use HTTP-GET-Requests to get JSON data (device status and device configuration)
- to modifiy device config and device status, you have to use HTTP-GET-Requests plus CGI Paramater, as so called Query String as part of the URL
This makes the HTTP Api Rest Level 1 compliant. Links: