Simple Ethernet API
The Simple Ethernet API allows you to send commands to your Expert Control, and receive responses to queries from it, over UDP.
By default, the Simple Ethernet API is turned off. To configure and turn on the Simple Ethernet API, navigate to Main Menu
and click Configure Simple Ethernet API.
Setting up Simple Ethernet API
Configure the Ethernet API – from this window you can alter the following settings:
-
Enable the Ethernet API? – click the switch to turn on the Simple Ethernet API and reveal configuration options.
-
UDP port to listen on – specifies the UDP port on which the Expert Control will listen for commands. The allowed range is 1024-65535, the default port is 1025.
-
Send feedback data? – specifies whether the Expert Control should respond to UDP commands. Click the switch to turn on feedback data and reveal configuration options.
-
IP address to send feedback to – specifies the IP address to which the Expert Control will send UDP messages in response to queries. This is an IPv4 unicast address.
-
UDP port to send feedback to – specifies the UDP port on the specified IP address to be used for UDP messages. The allowed range is 1024-655351, the default port is 1025.
Simple Ethernet API Command Structure
UDP commands for Expert Control must start with the character > and end with the character #.
Characters received when a command has not first been opened by receiving a > character are ignored by the controller. Line feeds and carriage returns are ignored.
Parameters and arguments are separated by a colon (:) and multiple parameter/argument pairs must be separated by a comma (,).
Simple Ethernet API Action Commands
Each type of command is identified using a number. This number tells the Controller what parameters to expect and what to do with the arguments once received.
The available commands are:
| Command Number | Action | Parameters | |
|---|---|---|---|
| 1 | Activate Scene | SC | Absolute Scene number to activate |
| 2 | Space Off | S | Space in which to execute Off |
| 3 | Master Intensity | S | Space in which to master intensity |
| I | The intensity master level, 0-255 | ||
| F | The fade time in centi-seconds (0-65535) | ||
| 4 | Override | S | Space in which to override |
| I | The intensity override level, 0-255 | ||
| T | The Colour temperature to override, 0(coolest)-255(warmest) | ||
| R | The red override to apply (0-255) | ||
| G | The green override to apply (0-255) | ||
| B | The blue override to apply (0-255) | ||
| F | The fade time in centi-seconds (0-65535) | ||
| 5 | Activate Tag | TS | Tag set number |
| TG | Tag number | ||
| 6 | Activate Scene in Space | SR | Index of the relative Scene in the space |
| S | Space in which to activate | ||
Parameters appearing in bold are optional. If not specified, fade time is zero for master intensity commands and two seconds for override commands.
Action Command Examples
The table below shows examples of each of the six action command types along with a description of the outcome of the command.
| Command Number | Example | Description |
|---|---|---|
| 1 | >C:1,SC:1# | Activate Scene 1 |
| 2 | >C:2,S:8# | Turn off Space 8 |
| 3 | >C:3,S:7,I:128# | Change master intensity to 50% (128 out of 255) in space 7, in zero seconds (optional fade parameter not set) |
| 4 | >C:4,S:3,I:255,G:255,F:150# | Override the intensity to be full and Green to be full in Space 3 with a fade time of 1.5 seconds |
| 5 | >C:5,TS:1,TG:5# | Activate Tag 5 in Tag set 1 |
Simple Ethernet API Errors
If a command is malformed or refers to items that do not exist, the command will be ignored. An error code will be returned if the Send feedback data? switch in the Configure the Ethernet API window is enabled.
Errors sent by the Controller begin with an exclamation mark (!) and end with a hash symbol (#). There are two error codes, given in the table below.
| Error | Description |
|---|---|
| !E=1# | Command format error - The command contained unknown parameters, or did not contain the parameters required. |
| !E=2# | Data error - Although the command is correctly formed, the data it referred to (for example, a Space or Tag) does not exist. |
Simple Ethernet API Query Commands
Query commands produce a response from the Controller. In order to utilise query commands, the Send feedback data? switch in the Configure the Ethernet API window must be enabled. Responses are sent to the IP address and UDP port specified in the Configure the Ethernet API window.
Replies sent from the Controller start with a question mark (?) and end with a hash symbol (#). The equals symbol (=) indicates values returned by the Controller in response to a query.
The available commands are:
| Command Number | Query | Query Parameters | Response Parameters | ||
|---|---|---|---|---|---|
| 101 | Is Scene active? | SC | Absolute Scene number to query | A | Active status (0/1) |
| 102 | Is Space off? | S | Space number | O | Off status (0/1) |
| 103 | Get Space Master Intensity | S | Space number | I | Space Master Intensity (0-255) |
| 104 | Get Space Override | S | Space number | S | Space number |
| 105 | Get Tag State | TS | Tag set number | A | Active status (0/1) |
| TG | Tag number | ||||
Query Command Examples
The table below shows examples of each of the five query command types and hypothetical responses, along with a description of the query and the response.
In ‘Is Scene active’ queries, the response parameter A represents Active. For example, an active Scene query returning A=1 means the Scene is active.
In ‘Is Space off’ queries, the response parameter O represents Off. For example, a Space off query returning O=0 means the Space is on (not off).
| Command Number | Command | Command Description | Response | Response Description |
|---|---|---|---|---|
| 101 | >C:101,SC:3# | Is Scene 3 active? | ?C:101, SC:3, A:1# | Yes, Scene 3 is active |
| 102 | >C:102,S:2# | Is Space 2 off? | ?C:102,S:2,O:0# | No (0), Space 2 is not off |
| 103 | >C:103,S:9# | Get Space 9 Master Intensity | ?C:103,S:9,I:186# | Space 9 Master Intensity is 186 |
| 104 | >C:104,S:6# | Get Space 6 Overrides | ?C:104,S:6,I:12,R:128,G:96# | Overrides in Space 6 are: Intensity 12, Red 128 and Green 96 |
| 105 | >C:105,TS:1,TG:6# | Get State of Tag 6 in Tag set 1 | ?C:105,TS:1,TG:6,A:1# | Tag 6 in Tag set 1 is active (1) |