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. 

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

Orange_icon.png

 

 

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)
32 – Start Duration test (DALI command 228, 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
  • 200 – The Enlighted Manage has sent the Start test command to the sensor.
  • 400 Bad Fixture ID – Invalid Fixture ID, please correct and try again.
  • 403 Bad Request – The user does not have permission to issue this API call.
  • 404 Not found – This Fixture ID does not represent an emergency fixture. This function is only supported only by emergency fixtures, please select an appropriate Fixture ID.
  • 409 Conflict – Fixture is performing an Emergency Lighting test. Stop the current test and try again.
  • 500 Internal Server error – Oops, it looks like this sensor is offline, it has not been heard for more than 15 minutes.  Please resolve the issue and try again.  If the sensor is powered and the issue persists, this could indicate a wireless network problem where the sensor is out of range or interfered with by another RF source.

 

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
  • 200  – The Enlighted Manage has sent the stop test command to the sensor.
  • 400 Bad Fixture ID – Invalid Fixture ID, please correct and try again. 
  • 400 Bad Body Format – Incorrect body format, please correct and try again.
  • 403 Bad Request – The user does not have permission to issue this API call.
  • 404 Not found – This Fixture ID does not represent an emergency fixture. This function is supported only by emergency fixtures; please select an appropriate Fixture ID.
  • 408 Delayed Response – The sensor took more than 60 seconds to respond but the sensor is online.  If occurring frequently this could indicate wireless network setup or interference issues.
  • 500 Internal Server error – Oops, it looks like this sensor is offline, it has not been heard for more than 15 minutes.  Please resolve the issue and try again.  If the sensor is powered and the issue persists, this could indicate a wireless network problem where the sensor is out of range or interfered with by another RF source.
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
  • 200  – The Enlighted Manage has sent the messages to the sensor.
  • 400 Bad Fixture ID – Invalid Fixture ID, please correct and try again.
  • 403 Bad Request – The user does not have permission to issue this API call.
  • 404 Not found – This Fixture ID does not represent an emergency fixture. This function is supported only by emergency fixtures; please select an appropriate Fixture ID.
  • 409 Conflict – Fixture is performing an Emergency Lighting test. Stop the current test and try again.
  • 500 Internal Server error – Oops, it looks like this sensor is offline! Please resolve the issue and try again.
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
  • 200 – The Enlighted Manage publishes the test results from the sensor connected to the fixture.
  • 400 Bad Fixture ID – Invalid Fixture ID, please correct and try again.
  • 404 Not found – This Fixture ID does not represent an emergency fixture. This function is supported only by emergency fixtures; please select an appropriate Fixture ID.
  • 408 Request Timeout – The sensor took too long to respond; please try again. If occurring frequently this could indicate wireless network setup or interference issues.
  • 500 Internal Server error – Oops, it looks like this sensor is offline, it has not been heard for more than 15 minutes.  Please resolve the issue and try again.  If the sensor is powered and the issue persists, this could indicate a wireless network problem where the sensor is out of range or interfered with by another RF source.

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.

  • Emergency – Returns sensors designated as emergency fixtures in the Energy Manager (EM)
  • Desk – Returns sensors designated as Desk sensors in EM
  • Fixtureless – Returns sensors designed as Fixtureless in EM including Desk sensors.
  • Fixtured – Returns sensors that control lighting fixtures.
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",
}
]
}