AN73: CUE system integrates NETIO PDUs using JSON API

Tags: 
3rd party HW-SW

The AN73 demonstrates how to control power output(s) on NETIO PDUs via the CUE ecosystem. By using JSON API.

Do you have any questions?

NETIO decided to streghten possition in Control systems, IOT and Atomation of integration. NETIO PDUs can be easily and directly control from CUE Systems .It will help end users to control and remotely restart of  auditoriums, conference systems or complex systems.

List of NETIO devices being able to integrated with Cue. NETIO devices shall be running with FW 4.0.0.+

•    PowerBOX 3Px
•    PowerBOX 4Kx
•    PowerPDU 8KS
•    PowerPDU 8QS
•    PowerPDU 4KS
•    PowerPDU 4PS
•    PowerDIN 4PZ 
•    PowerCable 2KZ
•    PowerCable 2PZ

 

 

CUE gateway can control NETIO Outputs: 

  • Output ON
  • Output OFF
  • Reset with defined delay 

CUE HW supporting integration

  • ControlCUE
  • touchCUE
  • signCUE
  • appCUE
     

 

NETIO device configuration

IP address 

Set a fixed IP address for the NETIO unit. Either use a static IP address in the NETIO or a reserved IP address on the DHCP server for the MAC address of the NETIO unit.

API setting

In section M2M API protocols / JSON API set the following:

  • Enable JSON API
  • Enable READ-WRITE
  • Set a secure Username and Password for access. The default values for username and password are “netio“.

 

 

Output settings 

NETIO devices with multiple outputs have different switching delays set for each output in the default state so that when a command to switch all outputs is executed at the same time, the outputs are switched sequentially to avoid a current peak.

If you would be uncomfortable with this behavior and want the relays to respond immediately to commands from the control system, set the delay to 0.

In section Outputs tap on the required relay and on the tab General set the Output PowerUp interval to 0 milliseconds.

 

 

Cue System configuration

 

NETIO JSON API device driver

Description 

NETIO_JSON_API driver is designed to control NETIO power distribution units using HTML JSON API protocol. The driver connects to the HTTP channel of the CUE units.

 

The driver allows controlling output relays on NETIO units and reading the status of inputs and outputs (power consumption, currents, voltages, etc. depending on what data the connected NETIO unit provides).

 

 

Resources 

Driver is available on CUE cloud: NETIO_PowerDistribution_NETIO_JSON_API_Http_Client_1.00.cvcd
 

 

Properties

Property name

Data type

 Default value Description
Ip Address Text   NETIO unit IP address (IPv4)
Port Long 80 Port used for HTTP communication
Username Text netio Username for JSON API READ-WRITE protocol {default – netio}
Password Text netio Password for JSON API READ-WRITE protocol {default – netio}
UseHTTPs Boolean False Reserved for future HTTPs support in NETIO firmware, now use False. **NETIO supports HTTPs from 5.0.3+
AnswerTimeOut Time :0.3 Timeout for communication with NETIO
CacheTime Time :1.0

To avoid unnecessary (time consuming) communication data read from NETIO unit is cached for CacheTime. If the age of data is less than CacheTime, data is not read directly from the NETIO unit, but from this cache. If data is older, data is read from NETIO unit directly. 

 

 

 

Functions 

Close 

This function closes the relay with relaynumber.

Syntax

Close(relaynumber As Long) As Boolean

 

Parameters

relaynumber

  • Long 1 - 8, depends on the maximum number of relays in the NETIO unit

Return value

  • Boolean True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

Example

NetioPower1.Close(2) //closes relay 2

 

ClosePulse 

This function closes the relay with relaynumber and after newpulsetime opens this relay. 

Syntax 

ClosePulse(relaynumber As Long,newpulsetime As Time) As Boolean

 

Parameters 

relaynumber

  • Long 1 - 8, depends on the maximum number of relays in the NETIO unit newpulsetime
  • Time Pulse time for which the relay will be closed. The minimum value is 100 ms (0:0.1). If the specified value is shorter, it will be set to 100 ms.

 

Return value 

Boolean True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

Example 

NetioPower1.ClosePulse(1, :2.0)

//closes relay 1, waits 2 seconds and then opens the relay 1

 

Open 

This function opens the relay with relaynumber.

Syntax

ClosePulse(relaynumber As Long,newpulsetime As Time) As Boolean

 

Parameter

  • Long 1 - 8, depends on the maximum number of relays in the NETIO unit

Return value 

  • Boolean True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

Example 

NetioPower1.Open(2) //opens relay 2

 

OpenPulse

This function opens the relay with relaynumber and after newpulsetime closes this relay. This function is useful e.g. for resetting the device.

Syntax

OpenPulse(relaynumber As Long,newpulsetime As Time) As Boolean

 

Parameter

relaynumber

  • Long 1 - 8, depends on the maximum number of relays in the NETIO unit newpulsetime
  • Time Pulse time for which the relay will be opened. The minimum value is 100 ms (0:0.1). If the specified value is shorter, it will be set to 100 ms.

Return value

Boolean True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

Example 

NetioPower1.OpenPulse(3, :5.0)
//opens relay 3, waits 5 seconds and then closes the relay 3

 

IsClosed

This returns if the relay with relaynumber is closed (returns True) or opened (returns False).

Syntax

IsClosed(relaynumber As Long) As Boolean

 

Parameter

relaynumber

  • Long 1 - 8, depends on the maximum number of relays in the NETIO unit

Return value 

  • Boolean True if relay is closed, False if relay is open or an error occurs.

Example 

PageNetio.IndicatorNetioOutput1.SetValue(NetioPower1.IsClosed(1))
//sets the graphic object IndicatorNetioOutput1 that displays
//the status of NETIO output

 

SetCacheTime 

This function sets the driver CacheTime to newcachetime if you need to change a value that was set in the driver properties. To avoid unnecessary (time consuming) communication data read from NETIO unit is cached for CacheTime. If the age of data is less than CacheTime, data is not read directly from the NETIO unit, but from this cache. If data is older, data is read from NETIO unit directly.

Syntax

SetCacheTime(newcachetime As Time)

 

Parameter

newcachetime

  • Time new CacheTime value 

Example 

Var T As Time
T := NetioPower1.GetCacheTime() //CacheTime is written to variable

 

SetCommunication 

This function sets the IP communication parameters if you don't want to use the parameters set in the Properties, or if you need to change them.

Syntax

SetCommunication(newipaddress As Text,newport As Long,newusername As Text,newpassword As Text,Optional newusehttps As Boolean := False,Optional newanswertimeout As Time := :0.3) As Boolean

 

Parameter

newipaddress

  • Text IP address (IPv4) of the NETIO unit

newport

  • Long Port used for HTTP communication, typically 80

newusername

  • Text Username for JSON API READ-WRITE protocol

newpassword

  • Text Password for JSON API READ-WRITE protocol

newusehttps

  • Boolean Optional, reserved for future HTTPS support in NETIO firmware, now use False.

newanswertimeout

  • Time Optional, defaults to :0.3. Timeout for communication with NETIO.

Return value 

  • Boolean True on success or False if an error occurs.

 

Example 

NetioPower1.SetCommunication("192.168.1.42", 80, "netio", "supersecretnetiopassw0rd")

 

GetDeviceStatus 

This function reads the state of the whole NETIO unit and stores it in a variable status of the NetioStatusStructure type.

Syntax

GetDeviceStatus(ByRef status As Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".NetioStatusStructure) As Boolean

 

Parameter

Status

  • NetioStatusStructure: this structure describes the state of the whole NETIO unit and is described below.

Return value 

  • Boolean True on success or False if an error occurs.

Example 

Var S As Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".NetioStatusStructure
Var NetioTotalCurrent As Double
Var NetioInputVoltage As Double
Var NetioOutput1Current As Double

 
NetioPower1.GetDeviceStatus(S)
NetioTotalCurrent := S.GlobalMeasure.TotalCurrent
NetioInputVoltage := S.GlobalMeasure.Voltage
NetioOutput1Current := S.Outputs[1].Current

 

Structures 

The GetDeviceStatus function returns the NetioStatusStructure data structure that describes the entire status of the NETIO unit. Here is a description of this data structure and its substructures. See the original NETIO manuals for details of each item. Some NETIO products can only pass limited data, in which case this data will be left blank in the structure.

 

 

Declaration

Global Structure NetioStatusStructure
        Var Agent                                            As NetioAgentStructure
        Var GlobalMeasure                             As NetioGlobalMeasureStructure
        Var Outputs[MAX_OUTPUTS]               As NetioOutputStructure
        Var Inputs[MAX_INPUTS]                 As NetioInputStructure
        Var PAB[MAX_PABS]                             As NetioPABStructure
        Var Watchdogs[MAX_WATCHDOGS]   As NetioWatchdogStructure
        Var Rules[MAX_RULES]                   As NetioRulesStructure
End Structure

 
Global Structure NetioAgentStructure
        Var Model                                            As Text [MAX_NAME_LENGTH]
        Var DeviceName                                As Text [MAX_NAME_LENGTH]
        Var MAC                                              As Text [17]
        Var SerialNumber                              As Text [20]
        Var JSONVer                                   As Text [10]
        Var MessageUTCTime                            As Time                //absolute time
        Var Uptime                                           As Time                //time interval
        Var Version                                          As Text [10]
        Var OemID                                            As Long
        Var VendorID                                  As Long
        Var NumOutputs                                As Long
        Var NumInputs                                 As Long
End Structure

 
Global Structure NetioGlobalMeasureStructure
        Var Voltage                                          As Double
        Var TotalCurrent                              As Double
        Var OverallPowerFactor                 As Double
        Var TotalPowerFactor                   As Double
        Var OverallPhase                              As Double
        Var TotalPhase                                As Double
        Var Frequency                                 As Double
        Var TotalEnergy                               As Double
        Var TotalReverseEnergy                 As Double
        Var TotalEnergyNR                             As Double
        Var TotalReverseEnergyNR               As Double
        Var TotalLoad                                 As Double
        Var EnergyStartUTC                            As Time                //absolute time
End Structure

 

Global Structure NetioOutputStructure
        Var ID                                               As Long 
        Var Name                                             As Text[MAX_NAME_LENGTH]
        Var State                                            As Long //possible values are named constants STATE_XX below
        Var Action                                           As Long //possible values are named constants ACTION_XX below
        Var Delay                                            As Time                //time interval
        Var Current                                          As Double
        Var PowerFactor                               As Double
        Var Phase                                            As Double
        Var Energy                                           As Double
        Var ReverseEnergy                             As Double
        Var EnergyNR                                  As Double
        Var ReverseEnergyNR                           As Double
        Var Load                                             As Double
End Structure
Global Structure NetioInputStructure
        Var ID                                               As Long
        Var Name                                             As Text[MAX_NAME_LENGTH]
        Var State                                            As Long
        Var S0Counter                                 As Long
End Structure
Global Structure NetioPABStructure
        Var Type                                             As Text[MAX_NAME_LENGTH]
        Var Name                                             As Text[MAX_NAME_LENGTH]
        Var Enabled                                          As Boolean
        Var In                                               As Boolean
End Structure
Global Structure NetioWatchdogStructure
        Var Name                                             As Text[MAX_NAME_LENGTH]
        Var Enabled                                          As Boolean
        Var Fail                                             As Boolean
        Var LastStatus                                As Boolean
        Var Timestamp                                 As Time                        //absolute time
End Structure

 
Global Structure NetioRulesStructure
        Var Name                                             As Text[MAX_NAME_LENGTH]
        Var Enabled                                          As Boolean
        Var Result                                           As Long
End Structure

 

Example 

Note: The declaration of a data variable with this structure must be referenced by the Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1" in the main program and modules.

Var S As Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".NetioStatusStructure
Var NetioOutput2Energy As Double

 
NetioPower1.GetDeviceStatus(S)

NetioOutput2Energy := S.Outputs[2].Energy

 

Constants 

The following named constants are used in the NETIO driver.

 


 

Example 

//declaration of the maximum number of items in arrays in structures
Global Const MAX_OUTPUTS              As Long := 8
Global Const MAX_INPUTS                       As Long := 2
Global Const MAX_PABS                 As Long := 32
Global Const MAX_WATCHDOGS            As Long := 32
Global Const MAX_RULES                As Long := 32

 
//possible values of the Action item in the NetioOutputStructure structure
Global Const ACTION_OFF               As Long := 0
Global Const ACTION_ON                As Long := 1
Global Const ACTION_SHORT_OFF  As Long := 2
Global Const ACTION_SHORT_ON   As Long := 3
Global Const ACTION_TOGGLE             As Long := 4
Global Const ACTION_NO_CHANGE  As Long := 5
Global Const ACTION_IGNORE             As Long := 6

 
//possible values of the State item in the NetioOutputStructure structure
Global Const STATE_OFF                As Long := 0
Global Const STATE_ON                 As Long := 1

 

 

Example 

Note: When using constants in the main program or modules, these constants must be referenced by Namespace CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".

Var S As Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".NetioStatusStructure

 
NetioPower1.GetDeviceStatus(S)
Page1.Indicator1.SetValue(S.Outputs[1].State = Namespace "CUE.Device.NETIO_PowerDistribution_NETIO_JSON_API_Http_Client.1".STATE_ON)

 
//the example on lines 1-4 is equivalent to using the following direct command

PageNetio.IndicatorNetioOutput1.SetValue(NetioPower1.IsClosed(1))

 

 

Special thanks

Let us thank especially Richard Milek for the driver and integration development. We are excited to have such partner as Cue.
 

Ask for a price or technical parameters

For device testing use name/password demo/demo