AN19 URL API (http GET) protocol to control NETIO 4x power sockets/outlets 110 / 230V

Tags: 
M2M API

The AN19 Application Note demonstrates the use of the “URL API” or “http get” M2M API protocol. By invoking a certain URL, one of  electrical outputs 110/230V can be switched On / Off / Toggle / Short pulse. This protocol is supported by all NETIO 4x devices (NETIO 4 / 4All / 4C).

 

Do you have any questions?

Supported devices: NETIO 4All, NETIO PowerPDU 4C, NETIO 4, PowerCable REST, PowerBOX 3Px, PowerPDU 4PS, PowerDIN 4Pz, PowerBOX 4Kx, PowerPDU 8QS

 

NETIO sockets can be controlled with URL M2M API calls (accessing a URL with parameters) in two ways: 

  1. Using a custom Lua script (NETIO AN04) 
  2. Using the standard URL API (http GET)” M2M API (this AN19) 

 

The difference in the methods described in AN04 (Lua script) and AN19 (M2M API) is that the URL string and following reactions in standard M2M API cannot be modified by the user.

 

The string of characters received by NETIO in the URL is split into individual commands and the device then sets its outputs to the desired states. The Action numbers correspond to the numbering in all M2M protocols.

Output actions:

0 = Output switched off (Off)

1 = Output switched on (On)

2 = Output switched off for a short time (short Off)

3 = Output switched on for a short time (short On)

4 = Output switched from one state to the other (toggle)

5 = Output state unchanged (no change)

 

URL API format example (toggle output 1):
http: //192.168.1.30/netio.cgi?pass= netio-psw&output1=4

 

 

Configuring NETIO 4x smart power sockets

In the NETIO 4x web administration, go to the M2M API Protocols – URL M2M API section, enable URL API and set a passphrase. Modify the port number if needed. Click Save Changes. After saving the changes, the device restarts (about 1 minute).


 

Creating the command string

  • To control the sockets, create a command string in the form of: http:// <netioIP>/netio.cgi?pass=<Passphrase>&output<X>=<action>
  • Replace <netioIP> with the IP address of your NETIO smart sockets. If you use a port different from the default (80), append a colon and the port number to the NETIO IP. 
  • Example (port 8080): 192.168.101.118:8080

Parameters

  • pass=<Passphrase>
    • Passphrase specified in M2M API Protocols – URL M2M API
    • The default Passphrase is the MAC address that is shown on the package label. For security reasons, we recommend to change it.
    • Example (the Passphrase is set to netio-psw): pass=netio-psw
    • If a passphrase is not required, this parameter can be left empty. It can be omitted completely from the command string, or it can be present but empty (only pass=)..

 

  • output<X>=<action>
    • X
      • Specifies the output number (1 to 4).
      • Example – to specify output 2: output2
    • action
      • Specifies the action to perform with the output.
      • 0 – turns the output off
      • 1 – turns the output on
      • 2 – turns the output off for a short time (if the output was off, it will be turned on)
      • 3 – turns the output on for a short time (if the output was on, it will be turned off)
      • 4 – toggles the current output state
      • 5 – leaves the output unchanged
    • Example – to turn on output 3: output3=1
    • To control more outputs at the same time, separate individual parameters with the & sign.
    • Example – to turn on output 2, turn off output 3 and toggle output 4: output2=1&output3=0&output4=4

 

  • delay<X>=<time(ms)>
    • Specifies the pulse duration for actions 2 and 3.
    • If it is not specified or the value is 0, the value specified in the web administration is used.
    • Replace <X> with the output number and <time(ms)> with the time in milliseconds (the minimum value is 100).
    • Example – to specify the pulse duration for output 3 to 500ms: delay3=500
    • Example of a complete command string: http:// 192.168.101.118/netio.cgi?pass=netio-psw&output3=2&delay3=500

 

Return values

The following responses to the http get request are possible:

  • 200 OK
    • Everything went OK
  • 400 Bad request
    • Incorrect format of the command string
  • 401 Unauthorized
    • Incorrect Passphrase
  • 403 Forbidden
    • URL M2M API is disabled on the NETIO device (see Configuring NETIO 4x)

 

Controlling the socket from the command line

For command line control, a utility such as cURL (available for download from http://curl.haxx.se/download.html) or any other command that can access a URL (such as a web browser) can be used.

 

Windows

Download the cURL utility, open the command line (CMD) and go to the bin folder in the curl installation folder.

The command string needs to be enclosed in double quotes and preceded with curl.

Example – turn on socket 1: curl "http:// 192.168.101.118/netio.cgi?pass=netio-psw&output1=1"

 

Mac OS X a Linux

By default, cURL is installed in your operating system. The command to control the outputs is the same as in Windows, see above.

 

Example from the NETIO sockets online demo

Online demos (for each device) are available at  

They can be used to demonstrate the product and test the M2M protocols.

 

FAQ:

 

1) Is it possible to control several outputs at once with a single command?

Yes, one command string can contain multiple commands to control the outputs. These need to be separated with the & sign.

Example: http:// 192.168.101.118/netio.cgi?pass=netio-psw&output1=1&output2=0

 

2) After entering the command string, I am redirected to the web administration. What should I do?

Probably a different port than 80 was set. For ports different than 80, the IP address must be followed by a colon and the port number. If the problems persist, please contact customer support.

Example: http:// 192.168.101.118:8080/netio.cgi?pass=netio-psw&output1=1

 

3) I turn on the socket using the URL but then the Scheduler is supposed to control the same socket. Will the time sequence work as expected?

Yes, after executing a URL M2M API command, the socket can still be controlled via all other channels (Scheduler, WatchDog, mobile app, button, ...)

 

4) Which method does the URL-based CGI M2M API use, http post or http get?

This is the http get method.

 

5) What is the difference between AN04 and AN19?

Both Application Notes describe similar ways of controlling NETIO smart sockets with a URL. The difference is in the command syntax and its processing. 
 

  • The AN19 Application Note uses a standard M2M API. It is easier for the user but the behavior cannot be customized.
  • The AN04 example uses a custom Lua script. In this case, the command syntax and NETIO behavior is determined by the custom script. The AN04 itself is an example of use rather than a protocol definition. 

 

6) Is it possible to read the output states using URL M2M API Get?

No. We recommend to use Telnet or XML-based protocols of the M2M API.

 

7) As a response to the URL command, all I get is a HTML page with a simple “OK”. Is it possible to customize this response?

Not at this moment. In the future, we plan to add a possibility to specify a return code in case of the standard M2M API (AN19) or a custom string in case of the Lua script (AN04).

 

Supported FW versions:

3.0.1 and higher (Archiv firmwware)

 

 

Supported devices:

Ask for a price or technical parameters

For device testing use name/password demo/demo