---
title: "NETIO JSON API device driver"
canonical: "https://docs.cuesystem.com/space/CVCDD/1215955083/NETIO%20JSON%20API%20device%20driver"
format: markdown
---
> Macro (toc)

---

# 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.

![image-20240726-120555.png](media://01eb7605-825c-4e30-a1a8-5f252eda2f32)

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

[https://www.netio-products.com/en/download](https://www.netio-products.com/en/download) 

Driver is available on CUE cloud: *NETIO_PowerDistribution_NETIO_JSON_API_Http_Client_1.xx.cvcd*

![image-20240726-115732.png](media://8389c8fc-ff8e-427b-b210-05bdfd684fa1)


# Properties

|  |  |  |  |
| --- | --- | --- | --- |
| Property name | Data type | Default value | Description |
| IpAddress | Text |  | NETIO unit IP address (IPv4) |
| Port | Long | 80 | Port used for HTTP communication |
| Username | Text | netio | Username for JSON API READ-WRITE protocol |
| Password | Text | netio | Password for JSON API READ-WRITE protocol |
| UseHttps | Boolean | False | Reserved for future HTTPS support in NETIO firmware, now use False. |
| 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

```none
Close(relaynumber As Long) As Boolean
```

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> 1 - 8, depends on the maximum number of relays in the NETIO unit

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

#### Example

```none
NetioPower1.Close(2) //closes relay 2 
```


## ClosePulse

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

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> 1 - 8, depends on the maximum number of relays in the NETIO unit

newpulsetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time)</u> 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

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

#### Example

```none
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

```none
Open(relaynumber As Long) As Boolean
```

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> 1 - 8, depends on the maximum number of relays in the NETIO unit

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

#### Example

```none
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

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> 1 - 8, depends on the maximum number of relays in the NETIO unit

newpulsetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time)</u> 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

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs (NETIO is not accessible or relaynumber is out of range).

#### Example

```none
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

```none
IsClosed(relaynumber As Long) As Boolean
```

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> 1 - 8, depends on the maximum number of relays in the NETIO unit

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True if relay is closed, False if relay is open or an error occurs.

#### Example

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


## 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

```none
SetCacheTime(newcachetime As Time)
```

#### Parameters

newcachetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time)</u> new CacheTime value 

#### Example

```none
NetioPower1.SetCacheTime(:2.0)
```


## GetCacheTime

This function returns current CacheTime (see **SetCacheTime **for details). 

#### Syntax

```none
GetCacheTime() As Time
```

#### Return value

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time)</u> current value of CacheTime

#### Example

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


## SetCommunication

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

#### Syntax

```none
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
```

#### Parameters

newipaddress

<u>[Text](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Text)</u> IP address (IPv4) of the NETIO unit

newport

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long)</u> Port used for HTTP communication, typically 80

newusername

<u>[Text](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Text)</u> Username for JSON API READ-WRITE protocol

newpassword

<u>[Text](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Text)</u> Password for JSON API READ-WRITE protocol

newusehttps

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> Optional, reserved for future HTTPS support in NETIO firmware, now use False.

newanswertimeout

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Time)</u> Optional, defaults to :0.3. Timeout for communication with NETIO.

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs.

#### Example

```none
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

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

#### Parameters

status

<span style="color: #4c9aff">NetioStatusStructure</span>: this structure describes the state of the whole NETIO unit and is described below.

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean)</u> True on success or False if an error occurs.

#### Example

```none
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.

![image-20240712-105156.png](media://e6883d37-0c99-44b4-ba17-fccd72110714)

#### Declaration

```none
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".NetioStatusStructure** in the main program and modules.

```none
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.

![image-20240712-105353.png](media://d91943c0-a3f6-4343-b89b-2eed29970ca0)

#### Declaration

```
//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"**.

```none
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))
```