CGI access

This section describes the Common Gateway Interface (CGI) available from the default or custom web pages. The web pages enable the user to send commands from the device to the network and request information from the network.

CGI uses Basic Authentication when calling GetDyNet.cgi or SetDyNet.cgi

Using credentials of an Ethernet Gateway configured user, the username and password are Base64 encoded and provided in the Authorization header of the HTTPS request.

Example:
headers:

{     'Authorization': 'Basic ' + Base64.encode(username + ':' + password); }
The default web interface is preloaded directly under the B:/WWW folder.

The CGI has been modelled on the Dynalite Text protocol and Dynalite Tasking syntax. In these protocols many of the command parameters are optional, so if a parameter is not specified then the default value (or the value that was previously specified) for this parameter is used for subsequent CGI requests. Alternatively, you may explicitly specify a value for all parameters each time a command is executed.

Issues to consider:

  • If your default page is no longer index.htm, then you must change the option in Device Properties.

  • The filename WebPage.cgi is reserved for retrieving webpage data.

  • The filename SetDyNet.cgi is reserved for issuing DyNet commands.

  • The filename GetDyNet.cgi is reserved for retrieving DyNet status.

  • All files names are case sensitive on this device, following Unix and web standards.

  • The ? character is used to initialise a CGI string and the & char is used for delimiting.
    Example: 192.168.2.2/SetDyNet.cgi?a=3&p=2

DyNet commands and status requests

Following table lists the HTTP/CGI requests available from the device.
Required parameters are shown in bold.

Function CGI request Parameters Value Required Value Range Description

Preset
(Set or Get)

P or PRESET
Preset number
Command

A
C, J, F

Yes

0 to 65535

Also supports special presets:
0=Reset Preset
65520=Off
65532=Restored Saved
65533=Toggle
65534=Panic
65535=Don’t care preset

Channel Level
(Set or Get)

L or LEVEL
Channel level
Command/Parameter

A
C, J, F

Yes

0 to 100

Channel level in percentage
255 is special don’t know/don’t care value.

Colour Temperature
(Set or Get)

CT
Colour Temperature
Command/Parameter

A
C, J, F

Yes

0 to 65535

Colour temperature in Kelvin (2500-7000)
0xFFFF (65535) = 'undefined'

Program/Save Preset
(Set)

PP or S
Preset number
Command

L, A
C, J

Yes

0 to 255

Saves the current channel levels to the specified preset

Start Task
(Set)

STT
Task Number
Command

-
DC, BN

Yes

0 to 255

If DC and BN are not provided, the device’s DC and BN will be used.

Stop Task
(Set)

SPT
Task number
Command

-
DC, BN

Yes

0 to 255

If DC and BN are not provided, the device’s DC and BN will be used.

Pause Task
(Set)

PT
Task number
Command

-
DC, BN

Yes

0 to 255

If DC and BN are not provided, the device’s DC and BN will be used.

Enable Event
(Set)

EEVT
Event number
Command

-
-

Yes

0 to 255

0 = All Events
Other values: particular event number

Disable Event
(Set)

DEVT
Event number
Command

-
-

Yes

0 to 255

0 = All Events
Other values: particular event number

Trigger Event
(Set)

TEVT
Event number
Command

-
-

Yes

1 to 255

0 = All Events
Other values: particular event number

Read Task Port Value
(Get)

RPV
Task port number
Command

-
SBP

Yes

0 to 255

SBP is optional for task sub-port number

Write on Task Port
(Set)

WPV
Task port number
Command

-
SBP

Yes

0 to 255

SBP is optional for task sub-port number

Write on Sub-Task Port
(Set)

SBP
Task Sub-Port Number
Parameter

RPV or WPV

Yes

0 to 255

Value to Write to Port
(Set)

V
Value to write
Parameter

WPV
SBP

Yes

0 to 255

Specifies the value to write to task port.

Nudge Up
(Set)

NU
Increment factor
Command

A
C, J

Yes

0 to 100

Channel level in percentage

Nudge Down
(Set)

ND
Decrement factor
Command

A
C, J

Yes

0 to 100

Channel level in percentage

Ramp Level
(Set)

RL or RAMPLEVEL
Ramp level value
Command

A
C, J

Yes

0 to 100

Channel level in percentage

Stop Fade
(Set)

SF or STOPFADE
Stop fading
Command

A
C, J

No

Current Temperature
(Get)

TPTR or TEMPERATURE
Temperature in +/- xx.yy format
Command

A
J

No

-64 to 64

Returned temperature shall be in +/- xx.yy format

Temperature Setpoint
(Set or Get)

TPSP or TEMPERATURESETPOINT
Temperature in +/- xx.yy format
Command

A
J

Set: Yes
Get: No

-64 to 64

Returned temperature is in +/- xx.yy format

DALI Driver Runtime Status
(Get)

(See note)

QBS
DALI driver runtime status
Command

DC, BN, C
CN

No

Reply if CN not specified:
QBS=x
Reply if CN specified (e.g. CN=5):
QBS=x;x;x;x;x

0: Lamp failure, driver offline
5: Lamp failure, driver online
6: Lamp OK, driver offline
7: Lamp OK, driver online

C: See note
CN: See note

Preset Offset
(Set)

O or OFFSET
Preset offset
Command

A
J

Yes

0 to 127
or
0 to 65535

Set the preset offset for an area.
Maximum value: DyNet1 message = 127
DyNet2 message = 65535

Reply Timeout
(Set or Get)

REPLYTIMEOUT
Reply timeout in milliseconds
Command

-
-

Set: Yes
Get: No

200 to 20000

This is the amount of time that device will wait for a any request message (when GetDyNet.cgi is used) to get back with a reply. If there is no reply after this time, device will reply with an error back to the client.

Task Register X
(Set or Get)

X
X register value
Command

-
-

No

0 to 255

Task Accumulator
(Set or Get)

ACC
ACC register value
Command

-
-

No

0 to 255

Area
(Set or Get)

A or AREA
Area number
Parameter

-
-

Yes

Area: 0 to 65535
Channel: 1 to 255

If no area specified, request is processed for most recent area received and saved by the export. Otherwise channel level for requested area is returned without storing the requested area.

Join
(Set or Get)

J or JOIN
Join value
Parameter

-
-

Yes

0 to 255

Channel Number
(Set or Get)

C or CHANNEL
Channel number
Parameter

-
-

Yes

0 to 65535

Number of Physical Channels
(Get)

CN
Number of physical channels Parameter

-
-

Yes

0 to 65535

Box Number
(Set or Get)

BN
Box number value in physical address Parameter

-
-

Yes

0 to 255

Device Code
(Set or Get)

DC
Device Code value in physical address Parameter

-
-

Yes

0 to 255

Fade Time
(Set)

F or FADE
Fade time in milliseconds
Parameter

-
-

Yes

0 to 5,242,710 ms
'Get DALI driver runtime status' (QBS)

  • The QBS command must be added to the end of the CGI string.

  • C=x specifies a physical channel number.

  • CN=x (optional) queries X consecutive physical channels starting with C.
    Thus, x should not exceed (total channels + 1) - C.

Example: 192.168.2.2/GetDyNet.cgi?DC=100&BN=13&C=23&CN=3&QBS

The reply to this request would include the driver status for channels 23, 24, and 25.

DyNet commands and status request examples

To control DyNet Areas, DyNet logical commands use the HTTP Set method with the SetDyNet.cgi file. DyNet logical status requests use the HTTP Get method with the GetDyNet.cgi file.

Example 1: Recall Preset 2 in Area 3

http://192.168.10.10/SetDyNet.cgi?a=3&p=2

This sets area 3 to preset 2. Multiple parameters may be used in the one request; however, only one of them should be of the command type. The response from this HTTP request automatically redirects the browser back to the calling page as detailed below:

<html><body onload=history.back()></body></html>

Example 2: Request the Current Preset in Area 3

http://192.168.10.10/GetDyNet.cgi?a=3&p or http://192.168.10.10/GetDyNet.cgi?a=3

The response from this HTTP request contains the state retrieved from the DyNet area.

A single numeric value is returned indicating the current preset or channel level. If the logical entity does not exist a single full stop character "." is returned. If the response shown below is returned from the request, then area 3 is in preset 4:

p=4

Example 3: Set the Preset Offset in Areas 2 to 6

http://192.168.10.10/SetDyNet.cgi?a=2&o=6

If the current preset is 4, the reply will be:

p=4 o=6

Example 4: Check and Update Reply Timeout

Reading the current setting:

http://192.168.10.10/GetDyNet.cgi?replytimeout

returns:

replytimeout=200

Now set it to a new value:

http://192.168.10.10/SetDyNet.cgi?replytimeout=2000
(this is typically for wireless devices that can have a very slow response times)

Example 5: Program Area 2, Channel 3 and Level 25% to Preset 10

http://192.168.10.10/SetDyNet.cgi?a=2&c=3&j=255&l=25&pp=10

Example 6: Fade Area 2, Channel 3 to 25% Channel Level With 5 Seconds Fade Time

http://192.168.10.10/SetDyNet.cgi?a=2&c=3&j=255&l=25&f=5000

Example 7: Request the Saved Channel Level in Area 2, Channel 3 for Preset 4

http://192.168.10.10/GetDyNet.cgi?a=2&c=3&j=255&p=4

Example 8: Request the Current Channel Level in Area 3, Channel 2 (Returns 23%)

http://192.168.10.10/GetDyNet.cgi?a=3&c=2&j=255&l

or

http://192.168.10.10/GetDyNet.cgi?a=3&c=2&j=255

returns:

l=23