AN29: Node-RED example of URL API communication with NETIO 4x

Tags: 
User library

Node-RED is a programming tool for wiring together hardware devices, APIs and online services. The AN29 Application Note shows how to control 110/230V smart sockets from Node-RED using URL API. Invoking an URL is a simple but only a one-way solution (it is possible to control NETIO 4x outputs from Node-RED but it is not possible to measure consumption).

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

 

The NETIO Node-RED script (flow) demonstrates how to control output 1 from a Node-RED Dashboard. Five buttons displayed in the Dashboard call the five possible actions that can be performed with the output (on, off, short off (restart), short on, toggle). 

The Node-RED environment can run on a PC, a Raspberry Pi, in a cloud (MS Azure, IBM) and so on.

 

URL API control of a NETIO 4x smart socket device only allows write access – it is not possible to read output states or consumption measurements. To do that, a different M2M protocol needs to be used.

AN29 can be used as a driver for NETIO 4x sockets as well as for PowerCable REST products that support URL API.

 

 

Examples of using NETIO with Node-RED:

 


Flow (Node-RED script) for AN29:

 

Dashboard for AN29:

 

How URL API works

The string of characters received by the NETIO device in the URL is split into individual commands and the device then sets its outputs to the desired states according to the action number.

 

Actions with the output:

  • 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 example (toggles the state of output 1):
http: //192.168.1.30/netio.cgi?pass=netio-psw&output1=4

 

 

Configuring NETIO 4x

In the M2M API Protocols - URL M2M API section of the NETIO 4x web interface, enable URL M2M API.

Set the Passphrase and click Save Changes. After saving the changes, the device restarts (about 1 minute).

 

Online demo access on NETIO device web

NETIO 4All Online demo

The online demo is a physical NETIO device connected to the Internet at a public IP address. The manufacturer makes available a demo device of each model. The online demos have different configurations, so it is possible to test the behavior without having the device physically in hand.

In the online demo, configuration changes cannot be saved.

To access the online demo of a product, click “TRY ON-LINE DEMO” at the respective product page.

 

Node-RED

Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. Node-RED provides a browser-based flow editor and a wide choice of nodes and options. It is built on Node.JS, making it ideal to run on low-cost hardware such as the Raspberry Pi as well as in the cloud.

Node-RED is a popular platform for IoT (Internet of Things) applications. A flow (that is, a script or a project) can be easily transferred as a configuration json file.

 

AN29 flow (script)

The configuration for NETIO Node-RED AN29 is specified in a json structure and can be pasted via the clipboard.

 NETIO AN29: Download Node-RED flow

 

[{"id":"53632275.7d628c","type":"tab","label":" NETIO AN29 (URL API)","disabled":false,"info":""},{"id":"bf404b4d.c9abf8","type":"http request","z":"53632275.7d628c","name":"HTTP Request (GET)","method":"GET","ret":"txt","url":"http://netio-4all.netio-products.com:8080/netio.cgi?pass=&{{msg.payload}}","tls":"","x":600,"y":160,"wires":[["2277782e.54d148","3c4f1015.9d8298"]]},{"id":"8a190541.5e1018","type":"function","z":"53632275.7d628c","name":"Action Selector","func":"switch(msg.payload)\n{\n    case 0:\n        return {payload : \"output1=0\"};\n    case 1:  \n        return {payload : \"output1=1\"};\n    case 2: \n        return {payload : \"output1=2\"};\n    case 3: \n        return {payload : \"output1=3\"};\n    case 4:\n        return {payload : \"output1=4\"};\n}","outputs":1,"noerr":0,"x":400,"y":160,"wires":[["bf404b4d.c9abf8"]]},{"id":"2277782e.54d148","type":"debug","z":"53632275.7d628c","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","x":810,"y":120,"wires":[]},{"id":"3c4f1015.9d8298","type":"ui_text","z":"53632275.7d628c","group":"e4da58a6.64a3d8","order":5,"width":"6","height":"3","name":"","label":"Response from server: ","format":"{{msg.payload}}","layout":"col-center","x":840,"y":200,"wires":[]},{"id":"24ae69d.9d70496","type":"ui_button","z":"53632275.7d628c","name":"Output 1 = ON","group":"a380c23b.f3499","order":1,"width":0,"height":0,"passthru":false,"label":"Output 1 = ON","tooltip":"","color":"","bgcolor":"","icon":"","payload":"1","payloadType":"num","topic":"","x":120,"y":80,"wires":[["8a190541.5e1018"]]},{"id":"bbd4e78b.886a18","type":"ui_button","z":"53632275.7d628c","name":"Output 1 = OFF","group":"a380c23b.f3499","order":2,"width":0,"height":0,"passthru":false,"label":"Output 1 = OFF","tooltip":"","color":"","bgcolor":"","icon":"","payload":"0","payloadType":"num","topic":"","x":120,"y":120,"wires":[["8a190541.5e1018"]]},{"id":"e75f5457.45d01","type":"ui_button","z":"53632275.7d628c","name":"Output 1 = Short ON","group":"a380c23b.f3499","order":3,"width":0,"height":0,"passthru":false,"label":"Output 1 = Short ON","tooltip":"","color":"","bgcolor":"","icon":"","payload":"2","payloadType":"num","topic":"","x":140,"y":160,"wires":[["8a190541.5e1018"]]},{"id":"77f6af6b.abc61","type":"ui_button","z":"53632275.7d628c","name":"Output 1 = Short OFF","group":"a380c23b.f3499","order":4,"width":0,"height":0,"passthru":false,"label":"Output 1 = Short OFF (Restart)","tooltip":"","color":"","bgcolor":"","icon":"","payload":"3","payloadType":"num","topic":"","x":140,"y":200,"wires":[["8a190541.5e1018"]]},{"id":"645a9bee.f96f5c","type":"ui_button","z":"53632275.7d628c","name":"Output 1 = Toggle","group":"a380c23b.f3499","order":5,"width":0,"height":0,"passthru":false,"label":"Output 1 = Toggle","tooltip":"","color":"","bgcolor":"","icon":"","payload":"4","payloadType":"num","topic":"","x":130,"y":240,"wires":[["8a190541.5e1018"]]},{"id":"e4da58a6.64a3d8","type":"ui_group","z":"","name":"Response from server","tab":"1bb571ba.89b2ce","order":2,"disp":true,"width":"6","collapse":false},{"id":"a380c23b.f3499","type":"ui_group","z":"","name":"Control Output 1","tab":"1bb571ba.89b2ce","order":1,"disp":true,"width":"6","collapse":false},{"id":"1bb571ba.89b2ce","type":"ui_tab","z":"","name":" NETIO AN29 (URL API)","icon":"dashboard","order":1,"disabled":false,"hidden":false}]

Importing the NETIO AN29 flow (script) to node-RED

In the menu, select Import -> Clipboard.

 

Then, copy the text to the indicated field and click Import.

 

Installing missing nodes

The nodes are loaded into the selected flow. It is possible that an error message is displayed with a list of nodes that are being imported but are not installed in Node-RED yet. In this case, the missing nodes need to be installed. If there are nodes missing, select Manage palette in the menu.

 

Select Install and find the missing nodes.

 

How does the AN29 (URL API) Flow work

 

  • Five buttons created in the Flow are displayed in the Dashboard.
  • After clicking the Output 1 = ON button in the Dashboard, the payload is set to 1 (defined in each of the buttons in order to specify the action).
  • The Action Selector node selects the string that corresponds to the action (input payload) and creates the resulting URL string for controlling the device as the output payload.
  • The HTTP Request (GET) node concatenates the IP address + the action from the input payload value, and sends the resulting string using a HTTP GET Request. The server response (status) is returned as the output.
  • The msg.payload node displays the response from the HTTP server running in the NETIO 4x device.
  • The Response from server node displays the server response in the Dashboard.

 

Description of nodes used

Button node

Adds a button to the Dashboard.

Clicking the button node generates a message containing msg.payload.

The payload is set to the number specifying the URL API action.

 

Possible actions with the output are:

  • 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)

 

Function node

The function node is a special node that enables writing custom JavaScript function.

AN29 uses a simple JavaScript switch statement. The switch statement is used to choose the URL string based on the msg.payload input value (0-4). (Button nodes send values from 1 to 4 corresponding to the desired action).

return {payload : "output1=0"}; means that the function node passes on a payload containing the "output1=0" string. Here it is possible, for example, to change the number of the output to control by modifying "output1=0" to "output2=0".

 

HTTP Request node

This node sends a HTTP Request and returns the status response.

This node contains the IP address of the NETIO 4x device.

The pre-filled address points to the online demo, where you can test the connection without having a NETIO device at your desk.

http://netio-4all.netio-products.com

 

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)
     

 

 

URL string specified in the HTTP Request node

http:// netio-4c.netio-products.com/netio.cgi?pass=netio-psw&{{{payload}}}

The IP address can be changed; however, the {{{payload}}} at the end must be kept – it contains the string with the output and action numbers prepared in the previous node.

 

 

Text node

Displays a text field in the Dashboard. In AN29 it is used to display the response from the http server in the smart sockets device.

The Label is displayed in the Dashboard, and the Name is the node name displayed in the flow in Node-RED.

 

Debug node

Displays selected properties of the msg object. By default, it is set to msg.payload, and therefore it displays the server response in Node-RED.

 

 

Node-RED Dashboard

The Dashboard is a graphical representation of dashboards element.

The Dashboard can be opened by clicking the indicated symbol, or at the address of your Node-RED server with ui appended, e.g.: 127.0.0.1:1880/ui

 

 

The menu in the Dashboard includes a link to NETIO products website: 

 

 

FAQ

1) Is it possible to use an IP address different from the pre-filled one?

Yes, the IP address can be specified in the HTTP Request node. Numerical as well as textual form is acceptable.

Example: https:// 192.168.101.118/netio.cgi?pass=netio-psw&{{{payload}}}

The default is the DNS name of the NETIO 4All online demo, so that you can test AN29 without having a physical device at your desk.

Online demo: http://netio-4all.netio-products.com

 

2) Is it possible to control a different output than the output No. 1?

Yes. If the smart outlet device has multiple outputs, the output number can be changed in the function node.

Example: "output2=1".

 

3) I have changed the flow in Node-Red but the changes are not reflected in the Dashboard.

To save and display all changes in the flow, it is necessary to click Deploy in the upper right-hand corner in Node-RED.

 

4) The program used to work fine but now it does not work.

It is possible that the action string in the function node or the IP address string in the HTTP Request node were changed. The string must be specified exactly.

 

5) Is it possible to read the output states or power meter values using the URL M2M API?

No. We recommend using JSON or XML-based protocols of the M2M API (AN30 and AN31).

 

6) How can I install Node-RED on my PC?

The official Node-RED website provides detailed instructions and a free installer.

Website: https://nodered.org/docs/getting-started/

 

7) Is it possible to install Node-RED on devices other than a PC?

Node-RED is a generic platform for IoT applications. It can run e.g. on Raspberry Pi, Arduino or Microsoft Azure.

 

 

 

Supported FW versions for NETIO 4x:

3.1.0 and higher  (Firmaware archive)

 

Supported FW versions of PowerCable xxx:

2.0.2 and higher (Firmware archive)

 

 

Supported devices

Ask for a price or technical parameters

For device testing use name/password demo/demo