DALI Emergency APIs - Overview
Enlighted supports Emergency Lighting fixtures equipped with DALI Part 202 (IEC 62386-202) compliant "Self-contained emergency lighting" drivers. These are battery-backed-up drivers, which will automatically cause the fixture LED to become illuminated to the emergency light level when there is a loss of power. The DALI Emergency APIs in this section provide a mechanism where an external application can test the emergency drivers and the condition of their battery packs. The results of those tests are reported back to the external application for the generation of reports to indicate that regular testing has been performed on the emergency lighting system.
The Emergency Lighting APIs allow the external application to send Emergency Lighting commands or get Emergency Lighting status from specific sensors in the system. You can send these commands to sensors or fixtures designated as emergency fixtures connected to the DALI emergency driver. You can initiate an emergency fixture test and request the test results after the test has finished. While the fixture is performing the emergency test, you will not be able to perform any lighting control operations on the fixture.
Only a single DALI type 1 emergency driver can be connected to an Enlighted sensor. In this way the granularity of the system is such that the there is one sensor per emergency fixture and one emergency driver per emergency fixture so that there is no ambiguity in locating an emergency driver that has failed the testing.
When the sensors are running the emergency lighting test, they are displayed as a distinctive orange icon on the floor plan of Manage. You will see the list of sensors running the emergency test in the Sensor tab under Devices.
Note: JSON is the only accepted MIME type for the DALI Emergency APIs
Start the Functional or Duration Test for a Fixture
When this API call is issued, the sensor sends a message to the connected DALI driver to initiate a Functional or Duration test on the fixture. You can only send this command to sensors or fixtures designated as emergency fixtures.
The Functional test checks the unit's functionality to ensure that the lamps and circuitry are all working correctly. The Duration test allows the device to change to emergency mode, checking for the lamps and the circuit's status to ensure that the device is working correctly.
Since you will not be able to perform any lighting control operations on the fixture during this time, set the fixture light level before starting the test. Otherwise, the fixture will stay at the light level it was when the test was started. Use the Manual Override for a Fixture API to set the fixture light level. Likewise, set the fixture color temperature prior to starting the test using the Change Color API.
Include the Fixture ID of the sensor controlling the fixture in the PUT request. Use the Get Sensor Details by Floor API to obtain the Fixture ID. The driver begins executing the Functional or Duration test when it receives the request. The API returns OK to indicate that the Enlighted Manage (EM) has sent the sensor's start test command.
Request
PUT https: //{em_ip_address_or_hostname}/ems/api/org/fixture/v1/{fixture-id}/emergencyMode
{
"emergencyMode": "..."
}
Response
{
“emFixtureStatus”: ems/api/org/fixture/v1/{fixture-id}/emFixtureStatus
}
Parameters
| Request | Description |
| fixture-id |
Sensor or Fixture ID. Use the Get Sensor Details by Floor API to obtain the Fixture ID. |
| Request Body |
|
| emergencyMode |
16 – Start Functional test (DALI command 227, referencing 8bit value for DALI Command 250) |
| Response | |
|
emFixtureStatus |
URI for the API user to request the emergency fixture status of the fixture to confirm fixture status change |
| Status |
|
Sample Code
Start the functional test (16) on the emergency fixture with the Fixture ID '28'. The API returns status code 200 OK to indicate that the Enlighted Manage has sent the start test command to the sensor with Fixture ID '28'.
PUT https: //10.45.9.120/ems/api/org/fixture/v1/28/emergency Mode
{
"emergencyMode": "16"
}
HTTP/1.1 200
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 62
Date: Sat, 26 Sep 2020 10:36:51 GMT
{
“emFixtureStatus”: "ems/api/org/fixture/v1/28/emFixtureStatus"
}
Driver Status to Normal (Stop Test)
When this API call is issued, the emergency drivers connected to the Enlighted sensor will return to a 'normal' state by stopping all emergency tests.
Include the Fixture ID of the sensor controlling the fixture in the PUT request. Use the Get Sensor Details by Floor API to obtain the Fixture-ID.
The API returns OK to indicate that the Enlighted Manage (EM) has sent the stop test command to the sensor. If the API cannot get the results after trying for 60 seconds, the API displays a timeout message that the sensor took too long to respond. If you are trying to get driver test status for a non-emergency lighting fixture, the API returns an invalid Fixture ID. Check to ensure that the sensor is not offline, correct the API syntax, and reissue the call.
Request
PUT https: //{em_ip_address_or_hostname}/ems/api/org/fixture/v1/{fixture-id}/emergencyMode
{
“emergencyMode”: “...”
}
Response
{
“emFixtureStatus”: ems/api/org/fixture/v1/{fixture-id}/emFixtureStatus
}
| Request | Description |
| fixture-id |
Sensor or Fixture ID. Use the Get Sensor Details by Floor API to obtain the Fixture ID. |
| Request Body |
|
| emergencyMode |
2 – Stop Test (corresponds to DALI command 229, referencing 8bit value for DALI Command 250) |
| Response | |
| Status |
|
| emFixtureStatus |
URI for the API user to request the emergency fixture status of the fixture to confirm fixture status change |
Sample Code
Using the Fixture ID returned by the Get Sensor Details by Floor, stop running the emergency test for all drivers connected to the sensor with Fixture ID '28'. It returns status code 200 OK to indicate that the Enlighted Manage has sent the stop test command to the sensor. The response provides the URI to get the emergency fixture status of the fixture.
PUT https: //10.45.2.13/ems/api/org/fixture/v1/28/emergencyMode
{
“emergencyMode”: “2”
}
Response
HTTP/1.1 200
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 62
Date: Sat, 26 Sep 2020 10:36:51 GMT
{
“emFixtureStatus”: "ems/api/org/fixture/v1/28/emFixtureStatus"
}
Update Test Parameters for a Fixture
This API updates relevant driver test parameters for the emergency driver connected to the sensor. Use the Fixture ID returned by the Get Sensor Details by Floor API to update the following driver test parameters for the emergency driver connected to the sensor.
- Enlighted Manage Dim Level – This is the light level at which a fixture will be illuminated during an emergency (0-100%). The fixture manufacturer sets the default value.
- Test timeout – This is the timeout period, after which a driver will stop a test or stop trying to run a test. This parameter is relevant to duration tests, and the value is defined in 15-minute increments. The minimum timeout is 15 minutes (0), and the default is seven days.
- Prolong time – This is the length of time the light will stay in the emergency state after an emergency event, such as a power failure, ends. The value is defined in 30-second increments; the default value is 0 seconds.
Note: You will not be able to update test parameters on a fixture that is already performing an emergency test. Stop the test and then send the API request.
Request
PUT https: //{em_ip_address_or_hostname}/ems/api/org/fixture/v1/{fixture-id}/emParameters
{
"emDimLevel": "..."
"testTimeout": "..."
"prolongTime": "..."
}
Response
{
“emFixtureStatus”: ems/api/org/fixture/v1/{fixture-id}/emFixtureStatus
}
Parameters
| Request | Description |
| Fixture-id |
Sensor or Fixture ID. Use the Get Sensor Details by Floor API to obtain the Fixture ID. |
| Request Body |
|
| emDimLevel |
Light level (0-100%); 8bit value corresponds to DALI command 233 |
| testTimeout | Timeout period to stop the test. Min. timeout 15 minutes, max. 7 days; 8bit value corresponds to DALI command 238 |
| prolongTime |
Length of time, the light stays on after an emergency event. Specify in 30-second increments; default is 0 seconds; 8bit value corresponds to DALI command 239. |
| Response | |
| Status |
|
| emParameters |
URI for the API user to request the emergency test parameters of the fixture to confirm fixture test parameters |
Sample Code
Using the Fixture ID returned by the Get Sensor Details by Floor API, update the driver test parameters' values for the emergency driver connected to the sensor with Fixture ID '28'. The API returns status code 200 to indicate the Enlighted Manage has sent the appropriate messages to the sensor.
Note that if you attempt to update the test parameters on a fixture that is already performing a test, then Manage will reject the API request.
PUT https: //{em_ip_address_or_hostname}/ems/api/org/fixture/v1/28/emParameters
{
"emDimLevel": "120"
"testTimeout": "84"
"prolongTime": "20"
}
Response
HTTP/1.1 200
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 54
Date: Sat, 26 Sep 2020 10:36:51 GMT
{
“emParameters”: "ems/api/org/fixture/v1/28/emParameters"
}
Get Fixture Status by Fixture
This API retrieves the latest Duration and Functional test results as well as driver status from the emergency driver connected to the sensor. Note that only one emergency driver per sensor is allowed. Use the Fixture ID returned by the Get Sensor Details by Floor API to send the command to the sensor controlling the fixture.
The response includes driver test results, date, and time when the test results were last updated. Note that the test start and completion time will return null until the test is completed or stopped. A valid start and end time are displayed after the test has been completed.
If the API cannot get the results after trying for 60 seconds, the API displays a timeout message that the sensor took too long to respond. If you are trying to get emergency lighting test results from a non-emergency lighting fixture, the API returns an invalid Fixture ID message. Check to ensure that the sensor is not offline, correct the API syntax, and reissue the call.
Request
GET https: //{em_ip_address_or_hostname}/ems/api/org/fixture/v1/{fixture-id}/emFixtureStatus
Response
{
"fixtures": [
"id": "{fixture-id}",
"emTestResults": {
"startTime": "YYYY-MM-DD 24HH:MM",
"completionTime": "YYYY-MM-DD 24HH:MM",
"failurestatus": "0-255",
"emergencyMode": "0-255",
"emergencyStatus": "0-255",
"durationResult": "0-255",
"batteryCharge": "0-255"
}
]
}
Parameters
| Request | Description |
| fixture-id |
Sensor or Fixture ID. Use the Get Sensor Details by Floor API to obtain the Fixture ID. |
| Response | |
| fixture-id | Sensor or Fixture ID. |
|
emTestResults: |
|
|
startTime |
System time at which the driver started the duration test. The time is returned in the format yyyy-mm-dd hh:mm. ('null' if no test has been since last sensor reset) |
|
CompletionTime |
System time at which the driver completed its duration test or functional test. The time is returned in the format yyyy-mm-dd hh:mm. ('null' if no test has been completed since last sensor reset) |
|
emergencyMode |
Emergency mode of the Fixture. Corresponds to DALI command 250. |
|
emergencyStatus |
Emergency test status. Corresponds to DALI command 253 |
|
durationResult |
Represents 2-minute intervals of the length of the duration test. Corresponds to DALI command 243. |
|
batteryCharge |
Represents the battery charge status. Corresponds to DALI command 241. |
| failureStatus |
Corresponds to DALI command 252. Value: 0-255 |
| Status |
|
Sample Code
Send a request to retrieve the latest duration and functional fixture status results from the emergency driver connected to the sensor with Fixture ID '28'. The API returns the Enlighted Manage test results from the sensor.
GET https: //10.45.3.19/ems/api/org/fixture/v1/28/emFixtureStatus
Response
HTTP/1.1 200
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 241
Date: Sat, 26 Sep 2020 10:36:51 GMT
{
"fixtures": [
"id": "28",
"emTestResults": {
"startTime": "2020-07-20 21:41",
"completionTime": "2020-07-20 22:40",
"failurestatus": "32",
"emergencyMode": "2",
"emergencyStatus": "10",
"durationResult": "116",
"batteryCharge": "254"
}
]
}
Get the List of Emergency Fixtures by Floor
This API retrieves the fixture details and Fixture IDs for the sensors based on the designated sensor or fixture type.
Note: This API is an enhancement to the Get Sensor Location by Floor API, allowing you to filter results based on sensor type. Enlighted Manage (EM) versions below 3.10 do not support filtering based on sensor type.
The sensors in Manage are classified into the following types:
- Emergency sensors – Returns sensors designated as emergency fixtures in the Manage (EM)
- Desk sensors – Returns sensors designated as Desk sensors in EM. See Enable Desk Sensors.
- Fixtureless sensors – Returns sensors designed as Fixtureless in EM including Desk sensors.
- Fixtured sensors – Returns sensors that are not designated as fixtureless sensors.
Refer to the article Adding and Managing Fixture Database in the Manage to understand how fixture types are categorized and added to the Manage as fixtures and fixtureless sensors.
The API response is filtered based on the category of sensors. When the category or class is not specified in the API call, the response is not filtered. If the Floor ID is incorrect, the command returns 400 with the message "Floor ID does not exist, please correct and try again".
Request
GET https://{em_ip_address_or_hostname}/ems/api/org/fixture/location/list/floor/{floor_id}/1?class={filter}
Parameters
| Request | Description |
|
em_ip_address_or_hostname |
The Manage IP address or hostname |
| floor-id |
Floor ID. Use the Get All Floors API to obtain the Floor ID. |
| filter |
Filter: Class Value. Specify only one filter class, if the filter class is not specified, then the response is not filtered.
|
| Response | |
| fixture-id | Sensor or Fixture ID. |
|
Fixture: |
|
|
id |
Fixture identifier |
|
name |
Name of the Fixture |
|
xaxis |
Scaled reference of the distance measured in the horizontal dimension from the lower-left corner of the uploaded floor plan |
|
yaxis |
Scaled reference of the distance measured in the vertical dimension from the lower-left corner of the uploaded floor plan. |
|
macaddress |
MAC Address |
|
groupid |
Profile group identifier. The ID of the profile associated with the fixture. |
|
class |
Sensor Type: Emergency, Desk, Fixtureless, Fixtured |
Sample Code
Send a request to retrieve fixture details filtered based on the type of sensors 'fixtured' on Floor 2. The API returns the fixture details of all sensors that control light fixtures (fixtured) on Floor 2.
GET https: //10.4.23.19/ems/api/org/fixture/location/list/floor/2/fixtured
HTTP/1.1 200
{
fixture: [
{
id: 28
name: Sensor00c017,
xaxis: 966,
yaxis: 391,
macaddress: 0:c0:17,
groupid: 185,
class: fixtured
}
{
id: 1364
name: Sensor00629dd,
xaxis: 270,
yaxis: 90,
macaddress: 6:29:dd,
groupid: 196,
class: fixtured
}
{
id:17
...
}
]
}
Get Driver Test Parameters by Fixture
This API retrieves the driver test parameters for all emergency drivers connected to a sensor in an emergency fixture. Use the Fixture ID returned by the Get Sensor Details by Floor API to send the command to the sensor controlling the fixture.
The command returns relevant driver test parameters for drivers connected to a sensor of an emergency fixture. See the description of the parameters returned in the table below.
If the API cannot get the results after trying for 60 seconds, the API displays a timeout message that the sensor took too long to respond. If you are trying to get emergency lighting test results from a non-emergency lighting fixture, the API returns an invalid Fixture ID. Check to ensure that the sensor is not offline, correct the API syntax, and reissue the call.
Request
GET https://{em_ip_address_or_hostname}/ems/api/org/fixture/v1/{fixture-id}/emParameters
Response
{
"sensor": [
"id": "{fixture-id}",
"emParameters": {
"emDimLevel": "0-255",
"emMaxLevel": "0-255",
"emMinLevel": "0-255",
"testTimeout": "0-255",
"prolongTime": "0-255",
"ratedDuration": "0-255",
"features": "0-255"
"testDelayTimeHigh": "0",
"testDelayTimeLow": "0",
"functionTestInterval": "0",
"durationTestInterval": "0",
}
]
}
Parameters
| Request | Description |
| em_ip_address_or_hostname |
The Manage IP address or hostname |
| fixture-id |
Sensor or Fixture ID. Use the Get Sensor Details by Floor API to obtain the Fixture ID. |
| Response | |
| fixture-id | Sensor or Fixture ID. |
|
emParameters: |
|
|
emDimLevel |
The level at which a fixture will be illuminated during an emergency; corresponds to DALI command 233. |
|
emMaxLevel |
The maximum dim light level of the fixture. Not all drivers support this functionality. Corresponds to DALI command 248. |
|
emMinLevel |
The minimum dim level of the fixture, not all drivers support this functionality. Correspond to DALI command 247. |
|
testTimeout |
Represents the timeout period at which a driver will stop the test. The minimum timeout duration is 15 minutes. The default is 7 days. Value is defined in 15-minute increments. Corresponds to DALI command 242, DTR= 0x6. |
|
prolongTime |
Represents the time period for which the light will remain in emergency mode after the emergency event ends. Value is defined in 30-second increments. The default is 0 seconds. Corresponds to DALI command 242, DTR = 0x07. |
|
ratedDuration |
The rated duration of the Manage battery in 2-minute intervals. A value of 255 represents a time of 510 minutes or longer. Corresponds to DALI command 249. |
|
features |
Defines which features are or are not available on the driver. Corresponds to DALI command 249. |
|
testDelayTimeHigh |
Represents the highest time delay for the test. The sensor will always set the value to '0'. Corresponds to DALI command 234. |
|
testDelayTimeLow |
Represents the lowest time delay for the test. The sensor will always set the value to '0'. Corresponds to DALI command 235. |
|
functionTestInterval |
The sensor will always set the value to '0'. Corresponds to DALI command 236. |
|
durationTestInterval |
The sensor will always set the value to '0'. Corresponds to DALI command 237. |
Sample Code
Send a request to retrieve the driver test parameters for all emergency drivers connected to the sensor with the Fixture ID '28'. The API returns the test parameters for emergency drivers connected to the sensor with Fixture ID '28' designated as an emergency fixture.
GET https: //10.14.3.29/ems/api/org/fixture/v1/28/emParameters
Response
HTTP/1.1 200
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 197
Date: Sat, 26 Sep 2020 10:36:51 GMT
{
"sensor": [
"id": "28",
"emParameters": {
"emDimLevel": "134",
"emMaxLevel": "254",
"emMinLevel": "28",
"testTimeout": "255",
"prolongTime": "125",
"ratedDuration": "250",
"features": "134"
"testDelayTimeHigh": "0",
"testDelayTimeLow": "0",
"functionTestInterval": "0",
"durationTestInterval": "0",
}
]
}