Ethernet Access Point

When an EG is configured as a permanent Ethernet access point, it allows any modern browser to communicate with the control system over the Wi-Fi/LAN/Internet. A browser is only able to communicate with one EG at a time, so control is limited to the logical areas set in each EG. However, if a common logical address range is set in each EG then these areas can all be controlled even if they span different EG’s.

To set up the EG as an Ethernet access point, you must first run the sb icon bridge wizard Bridge Configuration Wizard to enable the DyNet Ethernet Access Point routing. Refer to Wireless Commissioning > Adding an IP Address.

Basic authentication is provided for web server, Telnet, and FTP connections by adding usernames and passwords in SB.

Add EG users:

In SB, select the EG and open the Device Properties tab.
Enable Web server and/or Telnet (PDEG/PDEB only) applications and related properties.

For security reasons, FTP support has been deprecated in the EG firmware. If visible in SB, you should leave this option disabled.
Open the Users tab and click Add to create new users (maximum: 5 per EG).
Under User Properties, enter the Name/Password and set the Enable property to True.
Under General Permissions, set Web server and/or Telnet to Enabled as needed.

Usernames and passwords have a 40 character limit and are case sensitive.
If usernames and passwords are forgotten and you do not have the job file, they can be retrieved from the EG using Load from Device. They can be backed up or replaced, but cannot be viewed in SB.

Wi-Fi access

For a completely customized interface, mobile apps accessing the connected lighting control system can be manually configured, or the interface can be auto-configured by reading the configuration data (project.xml file) stored in the EG. This saves configuration time and ensures control accuracy on mobile devices.

Once you have completed the logical configuration by entering your area, channel and preset names, you can upload your Project.xml file to the device.

Click sb icon save to device Save to Device after making any configuration changes.

SB has an option to upload a project.xml file by right-clicking the EG and selecting sb icon upload configuration Upload Configuration > Upload Logical Configuration.

To control the system, connect the self-configuring mobile app to the network via Wi-Fi and enter the IP address of the EG. The controls in the app auto-configure based on the project.xml file in the EG. The EG supports up to 30 concurrent sessions for mobile apps

The EG must have an IP address to upload the file. Refer to Wireless Commissioning about adding an IP address. Also, ensure that the EG is on the same subnet as your mobile device. Wireless routers/access points usually give out IP addresses within a certain range, e.g.: 192.168.10.1 to 192.168.10.100.

To establish a secure connection when using an app, you may need install the certificate for the relevant operating system on your mobile devices. Refer to Signify Certificate Installation.

Uploading files

To upload other XML project files to the EG, right-click and select any of the following:

Upload Configuration >
- Upload Logical Configuration
- Upload Device List
- Upload Job Properties
- Upload All

To upload a custom web interface, right-click the EG and select sb icon upload custom web pages Upload Custom Web Pages. You may decide to delete the existing web pages via the checkbox in the Web Page Upload dialog box. Reset the device to apply the new configuration.

Files on the PDEG must use the 8.3 filename format.
Files can be transferred from a project folder on PDDEG-S or on PDEG with firmware 3.53 or later, (PDEG doesn’t support compressed files)
FTP cannot be used to update files on PDDEG-S, PDTS, and PDEG (firmware 3.58 or later)
You can also save your Project.xml file by selecting File > Export > Logical Data.
When transferring a custom web interface, custom settings, or updating the project.xml, be aware that the index.htm file (or another starting web page) must exist before proceeding. Do not use a compressed file format.
To upload files, SB must be connected to the device over Ethernet. Other settings can be modified when SB is connected to either Ethernet or RS-485.

There are two main directories on the device:

Directory A
- Rolling 28-day log files.
Directory B
- /WWW
  - /GZIP contains all pre-compressed user interface files for EG. N.B. any uncompressed files referenced from this folder will return browser errors.
  - /IMAGES contains all images (JPG/GIF/PNG) used within the user interface files.
  - /USER a folder containing user defined custom web pages, if any.
  - /INDEX.HTM existing default homepage for the EG web interface.
  - /PROJECT.XML project specific configuration file created on the EG. This file is not present within the installation files.
  - /VERSION.TXT EG user interface build version.

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.

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

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

Current Temperature
(Get)

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

A
J

-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

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

-
-

0 to 255

Task Accumulator
(Set or Get)

ACC
ACC register value
Command

-
-

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

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

returns:

l=23

HTTPS Secure Access

HTTPS provides a secure connection between your browser and an Ethernet gateway.

HTTPS adds two things to HTTP: secrecy and trust. Secrecy is established with an SSL/TLS TCP connection that encrypts the browser’s data communications.

The most common solution for establishing trust, is based on certificates signed by third-party certificate authorities. Typically, a chain-of-trust is established for a server by preinstalling a signed web-server certificate, supplied by a certificate authority (CA) trusted by the client.

Configuring HTTPS

System Builder has the capability to manage certificates, sign certificates, send certificate signing requests and configure users with different access permissions.

There are three web server certificate options for establishing HTTPS access to the gateway:

System Builder Certificate (Recommended)

For most applications it is preferable to create and upload a System Builder signed certificate on the gateway and install the matching root certificate for each client’s browser or app that will access the server.

Self-Signed Certificate

Request the gateway to generate a self-signed certificate. This allows a secure connection using HTTPS however, the browser will show a non-trusted warning.

Certificate Authority Signed Certificate

If you have a domain, you may select a Certificate Authority signed certificate. System Builder will instruct the EG to create a Certificate Signing Request (CSR) from the private key built in to the EG. The CSR can then be sent to a third-party CA. It is the responsibility of the CA to determine if you are trustworthy. They can respond to the certificate signing request by signing your server certificate and sending you the result. You then upload the signed certificate onto your EG. The signed certificate usually does not need to be installed for each client as third-party CA’s are already known to most browsers, however there may be ongoing costs with this option.

You must have a user configured with Web server, CGI, Certificate read and write enabled. For more information on user permissions, refer to Property Editors – Users.
EG firmware version v3.44 and above supports secure connections via HTTPS. Web pages can be accessed via HTTPS however mobile apps currently only support HTTP.
The Device Site Certificate for TLS connections option is used to establish a TLS TCP connection between the PDDEG-S and other Ethernet enabled devices, such as the DDRC-GRMS-E and the DDBC320-DALI.
The 802.1X certificates option is used when clients only want devices they know about on the network. If the device does not present the correct credentials (certificate) then that ethernet port is disconnected and the device is not allowed to send traffic.

Create System Builder Certificate:

Connect SB to the EG over Ethernet.
Right-click the EG and select Manage Certificate.
Enter the gateway details and location information.
Click Select Certificate Type > System Builder Certificate.
Click the Create and Upload button. After 1-2 minutes, System Builder creates a signed certificate file on the EG. Restart the EG to apply the certificate.
Click the Save Root Certificate to File button to save the (.cer) file to your PC.
Right-click the security certificate (.cer) file on your PC and select Install Certificate to open the Certificate Import Wizard.
In the wizard, click the Next button, then select Place all certificates in the following store and set the Certificate store to the Trusted Root Certification Authorities folder.
Click the Next button and Finish button to complete the import wizard. The wizard displays a security warning.
Click the Yes button to install the certificate. The wizard shows a message that the import was successful.
In Device Properties > Ethernet Applications > Secure connection (HTTP/HTTPS) select HTTPS from the dropdown list.
Click Save to device or press F12 to upload your changes to the EG.

Create Self-Signed Certificate:

Connect SB to the EG over Ethernet.
Right-click the EG and select Manage Certificate.
Enter the EG details and location information.
Click Select Certificate Type – Self-signed Certificate.
Click the Create Certificate button. After 1-2 minutes, System Builder creates a self-signed certificate file on the EG. Restart the EG to apply the certificate.
In Device Properties > Ethernet Applications > Secure connection (HTTP/HTTPS) select HTTPS from the dropdown list.
Click Save to device or press F12 to upload your changes to the EG.

Create Certificate Authority (CA) Certificate:

Connect SB to the EG over Ethernet.
Right-click the EG and select Manage Certificate.
Enter the gateway details and location information.
Click Select Certificate Type – Certificate Authority (CA) certificate.
Click the Request from Gateway button. After 1-2 minutes, System Builder creates a certificate signing request file on the EG.
Click the Save Request to File button to save the (.csr) file to your PC and send the CSR file to a CA for signing.
After the CA returns the signed certificate, click the Select and Upload button, select the certificate file (.pem) and click Open. System Builder uploads the file to the EG. Restart the EG to apply the certificate.
In Device Properties > Ethernet Applications > Secure connection (HTTP/HTTPS), select HTTPS from the dropdown list.
Click Save to device or press F12 to upload your changes to the EG.

Establishing a HTTPS Connection

To confirm your signed certificate, open the EG homepage in your browser by entering https:// followed by the EG’s IP address. When a browser connects to the gateway’s web server, it will prompt you to enter your username and password (as set up in SB in the EG’s Users property editor).

The browser will verify that your server certificate has been signed by a trusted CA, and establish a secure connection with the EG web server.

To see whether a website is safe to visit, you can check the site’s security information by looking at the security status to the left of the URL bar. The browser will alert you if you cannot visit the site safely or privately with a visual indicator such as a red address bar and/or an error message warning that the server certificate is not trusted. Secure HTTPS connections are indicated with a closed padlock icon.