Pharos Express includes a Simple Ethernet API which lets you send simple UDP commands to activate scenes or tags, master intensity, turn off spaces and more. In addition to these action commands, the Simple Ethernet API also allows an external system to query the controller’s current state.
With the Simple Ethernet API, installations using Express Control can achieve sophisticated results by integrating with home automation platforms and building management systems.
Enable and Configure the Simple Ethernet API
By default, the Simple Ethernet API is turned off and must be enabled before use. To configure and turn on the Simple Ethernet API, click the menu in the top-left corner of Express software and select “Configure Simple Ethernet API”. This opens the “Configure the Ethernet API” helper.
This helper allows you to modify the properties of the Simple Ethernet API. The following settings are available:
- 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 Express Control will listen for commands.
- Send feedback data? – specifies whether the Express 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 Express Control will send UDP messages in response to queries.
- UDP port to send feedback to – specifies the UDP port on the specified IP address to be used for UDP messages.
Simple Ethernet API Command Structure
UDP commands for Express Control must start with the character > and end with the character #.
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 any arguments. Available commands are summarised by the table below.
| 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 in bold are optional. If not specified, fade time is zero for master intensity commands and two seconds for override commands.
Action Command Examples
This command activates scene 1.
- C:1 means the command is ‘Activate Scene’
- SC:1 means the scene to be activated is number 1
This command turns off space 8.
- C:2 means the command is ‘Space Off’
- S:8 means the space to be turned off is number 8
This command sets the master intensity to 50% in space 7 in 0 seconds
- C:3 means the command is ‘Master Intensity’
- S:7 means the space to be mastered is space 7
- I:128 means the final intensity is 50% (128 out of 255)
- The fade parameter, F, has not been specified, so defaults to 0 centiseconds
For more examples and additional information, read our dedicated online help pages.
Simple Ethernet API Query Commands
In addition to the action commands explained above, the Simple Ethernet API provides a number of query commands. Express Control provides a response when these commands are received. The available commands are listed in the table below.
| 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 TG | Tag set number Tag number | A | Active status (0/1) |
Query Command Examples
This query asks whether scene 3 is active.
- C:101 means the query is a ‘Is scene active’ command.
- SC:3 means the scene being queried is number 3.
The response states that scene 3 is active.
- C:101 means that the reply is in response to a ‘Is scene active’ command.
- SC: 3 means that the response relates to scene 3.
- A:1 means that the scene is active.
💡 Tip: In ‘Is scene active’ and ‘get tag state’ queries, the response parameter A represents Active. For example, an active scene query returning A=1 means the Scene is active.
This query asks whether tag 6 in tag set 1 is active.
- C:105 means the query is a ‘Get tag state’ command.
- TS:1 means the tag set being queried is number 1.
The response states that tag 6 in tag set 1 is active.
- TG:6 means the tag in tag set 1 being queried is number 6.
- A:1 means the queried tag is active.
The Simple Ethernet API is documented in more detail on our dedicated online help pages.
