---
title: "GUDE Rest API driver"
canonical: "https://docs.cuesystem.com/space/CVCDD/1773830208/GUDE%20Rest%20API%20driver"
format: markdown
---
> Macro (toc)

---

# Description

This document describes functions of the XPL driver for GUDE REST API controlled devices. 

# Resources

This link was used as source documentation for creating the driver.

[https://wiki.gude-systems.com/EPC_HTTP_Interface](https://wiki.gude-systems.com/EPC_HTTP_Interface) 

## Declarations

```
Const MAX_NAME_LENGTH			As Long := 50
Const MAX_OUTPUTS				As Long := 32

Global Structure GudeSingleOutputStatus
	Var name 						As Text[MAX_NAME_LENGTH]
	Var state						As Long
End Structure

Global Structure GudeStatus
	Var outputs[MAX_OUTPUTS] As GudeSingleOutputStatus
End Structure


```


# Properties

|  |  |  |  |  |
| --- | --- | --- | --- | --- |
| Property name | Data type | Default value | Description |  |
| IpAddress | Text |  | Ip address of the controlled device |  |
| Port | Long | 80 | TCP REST API control port |  |
| Username | Text | "" | Fill in if the device use username/password basic protection |  |
| Password | Text | "" | Fill in if the device use username/password basic |  |
| UseHttps | Boolean | False | True if the device use https secure connection |  |
| AnswerTimeOut | Time | :0.3 | If the lan connection is very bad, the programmer can set this timeout  longer |  |
| [StatusCacheTime](https://cue.atlassian.net/wiki/spaces/CVCDD/pages/1773830208) | Time | :1.0 | After that timeout the driver will read the status information directly from the device not from cached value. |  |

# Functions

## Close

This function closes the selected relay. 

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets relays are numbered from 1 to max outlet number. Typically 1 to 16.

#### Return value

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

#### Example

```visualbasic

if MyPowerDevice.Close(1) then
  debugprint("MyPowerDevice - relay 1 was successfully closed")
end if

```

## ClosePulse

This function generates close pulse on the selected output. 

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets relays are numbered from 1 to max outlet number. Typically 1 to 16.

newpulsetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Time)</u> ... The close status duration. Minimum value is 1 second.

#### Return value

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

#### Example

```visualbasic
if MyPowerDevice.ClosePulse(1,:5) then
  debugprint("MyPowerDevice - 5 seconds close pulse on the relay 1 was started")
end if
```

## GetCacheTime

This function returns cache time for the device status remember interval. See *StatusCacheTime *property.

#### Syntax

```visualbasic
GetCacheTime() As Time
```

#### Return value

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Time)</u> ... *StatusCacheTime *property actual value.

#### Example

```visualbasic
DebugPrintFormat("Status cache time = {:}", MyPowerDevice.GetCacheTime() )
```

## GetGudeStatus

This function returns status array of all device outputs. It returns last cached status or (if last read operation timeouted - see GetCacheTime) reads the status directly from the device. 

#### Syntax

```visualbasic
GetGudeStatus(ByRef status As GudeStatus) As Boolean
```

#### Parameters

status

GudeStatus ... see GudeStatus structure declaration in the section resources.

#### Return value

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

#### Example

```visualbasic
Var devstatus as Namespace "CUE.Device.GUDE_REST_API".GudeStatus
if MyPowerDevice.GetGudeStatus(devstatus) then
  DebugPrintFormat("Status of the output 1 is {n} (1 .. closed, 0 .. open)",devstatus[1].state)
end if
```


## IsClosed

This function returns closed status of the output. The status is read directly from the device if the StatusCacheTime is timeouted or returns from the internal status cache of the driver.

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets are numbered from 1 to max outlet number. Typically 1 to 16.

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Boolean)</u> True if output is closed, false otherwise.

#### Example

```visualbasic
DebugPrintFormat("Status of the output 5 = {L 'closed' 'open'}", MyPowerDevice.IsClosed(5))
```

## IsOpen

This function returns open status of the output. The status is read directly from the device if the StatusCacheTime is timeouted or returns from the internal status cache of the driver.

#### Syntax

```visualbasic
IsOpen(relaynumber As Long) As Boolean
```

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets are numbered from 1 to max outlet number. Typically 1 to 16.

#### Return value

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Boolean)</u> True if output is open, false otherwise.

#### Example

```visualbasic
DebugPrintFormat("Status of the output 3 = {L 'open' 'closed'}", MyPowerDevice.IsOpen(3))
```

## Open

This function open the selected relay.

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets are numbered from 1 to max outlet number. Typically 1 to 16.

#### Return value

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

#### Example

```visualbasic
if MyPowerDevice.Open(1) then
  debugprint("MyPowerDevice - relay 1 was successfully open")
end if
```

## OpenPulse

This function generates open pulse on the selected output. 

#### Syntax

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

#### Parameters

relaynumber

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... The relay number. Power outlets are numbered from 1 to max outlet number. Typically 1 to 16.

newpulsetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Time)</u> ... The open status duration. Minimum value is 1 second.

#### Return value

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

#### Example

```visualbasic
if MyPowerDevice.OpenPulse(1,:5) then
  debugprint("MyPowerDevice - 5 seconds open pulse on the relay 1 was started")
end if
```

## SetCacheTime

This function sets the cache time for the device. Cache time specifies the interval to remember last read status value. If the cache time was exceeded, the status will be read directly from the device a remembered until next chache time exceeds.

#### Syntax

```visualbasic
SetCacheTime(newcachetime As Time)
```

#### Parameters

newcachetime

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Time)</u> ... Chache time to set. Do not set too long otherwise status functions will be very delayed from the real status of the device. Suggested value is something about 0.1 to 0.5 second. 

#### Example

```visualbasic
if MyPowerDevice.SetCacheTime(:0.5) then
  debugprint("MyPowerDevice - status will be chached for 0,5 second")
end if
```

## SetCommunication

This function set new communication parameters for the device. This parameters set only device driver parameters. The function does not communicate with the device itself.

#### Syntax

```visualbasic
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#Text)</u> ... New ip address  of the device

newport

<u>[Long](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Long)</u> ... New Tcp port

newusername

<u>[Text](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Text)</u> ... New user name

newpassword

<u>[Text](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Text)</u> ... New password

newusehttps

<u>[Boolean](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Boolean)</u> New Usehttps flag. Optional, defaults to false.

newanswertimeout

<u>[Time](https://cue.atlassian.net/wiki/spaces/CVCHELP/pages/495058958#Time)</u> New answer timeout. Optional, defaults to 0.3 second. 

#### Return value

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

#### Example

```visualbasic
if MyPowerDevice.SetCommunication("192.168.3.125", 443, "", "", true) then
  DebugPrint("MyPowerDevice will communicate with the device on 192.168.3.125, 443 and uses https")
end if
```