Change Color API

Changes the color temperature of the fixtures to a specified setting for the specified duration.

Request

POST https: //{em_ip_address_or_hostname}/ems/api/org/sensor/tunable-white/change-color/value/target colorvalue/time  

 <fixtures>
  <fixture>
   <id>63</id>
  </fixture>
  <fixture>
    <id>145</id>
  </fixture>
</fixtures> 

Parameters

Request
em_ip_address or hostname The Manage IP address or hostname
targetcolorvalue Color Temperature value indicating the requested color temperature in Kelvin degrees.
The valid range depends on the Fixture Manufacturer Table (FMT)  supplied by the manufacturer for the fixture.
time Duration in minutes
Response
Status If the request is successfully handled “Change color success” message is displayed. When sensor details are missing or inaccurate in the Post command, “Sensors list is empty while requesting API” message is displayed.

Sample Code 

Change the color temperature value to 3200 for 60 minutes for fixtures with ID ‘63’ and ‘145’. The response ‘Change color success’ indicates that the color change is applied to the Tunable White fixtures successfully. Note that the response is a group response for all fixtures. The response is reported as a success if the message is successfully sent to the sensors.

POST https://10.8.1.90/ems/api/org/sensor/tunable-white/change-color/value/3200/60

<fixtures>
  <fixture>
   <id>63</id>
  </fixture>
  <fixture>
    <id>145</id>
  </fixture>
</fixtures> 

Response Success:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <response>
              <status>0</status>
              <msg>change color success</msg>
   </response>

Scene Control API

When a switch group is created in Manage, a virtual switch is added to the floor which controls the light and color intensity of the selected fixtures. Each set of light and color intensity settings for fixtures is called a scene.

Using this API, set the light and color intensity of the scene for the fixtures in the switch group to achieve the desired effect. Use the Scene ID and Switch ID returned by the Get Scene Light Levels for a Switch API call to set the light levels for each scene.  

Request

POST https://{em_ip_address_or_hostname}/ems/api/org/switch/op/dim/switch/switchid/scene/sceneid/percentage/time

Parameters

Request
em_ip_address or hostname The Manage IP address or hostname
switchid Switch Identifier. The Switch ID returned in the Get Scene Light Levels for a Switch API
sceneid Scene Identifier. The Scene ID returned in the Get Scene Light Levels for a Switch API
percentage

Percentage of light level

0% - Light levels set to off

100% - Light levels set to full-on.

101 - Auto: Sets the light level based on the lighting profile behavior

102 – Sets the scene light level configured for the fixtures when a switch is created on the floor plan in Manage.

time Duration in minutes
Response
Status 0 - Success, 1 - Failure

Sample Code 

Using the Scene ID and Switch ID returned by the Get Scene Light Levels for a Switch API, set the color intensity for the Scene with ID ‘157’  belonging to the switch with ID ‘1’ to 100% Full on for 10 mins. The response ‘0’ indicates that the scene is applied to the switch successfully.

POST https://10.8.1.90/ems/api/org/switch/op/dim/switch/1/scene/157/100/10
 {
  "status": "0"
}

 

Configure Recall the Lighting Scene Color API

This API is supported for Manage 4.4 and above and Sensor Firmware version 5.13.x and above.  

Use this API to configure recalling the lighting scene color for Tunable White fixtures before the lights were turned off. The current color temperature of the scene is stored, rather than recalling the max. color temperature, the lights will come back on with the last scene color temperature before the lights were turned off.

Each set of light level and color intensity settings for a fixture is called a Scene. When fixtures are configured for Tunable White, the color temperature describes how warm (yellow or orange) or cool (white or blue) the light appears. Pressing and holding the ERC Switch buttons three and four increase or decrease the color temperature of the fixtures correspondingly.

When the API parameter, onOffStickyColor, is set to 'True', the API configures the lights to come back with the last scene color temperature before the lights were turned off. 

For example, lights in a room are configured for 4000k color temperature for a presentation, and after 15 minutes, the lights are configured to dim to 2000k using the ERC switch. Due to no occupancy, the lights turn off. When the lights are turned on with the ERC, the lights will come back with the last scene color temperature of 2000k instead of the max color temperature.  

When the ovrStickyColor is set to 'True', the API configures the lights to come back with the last scene color temperature after the Override period is expired. The Override period is 60 minutes for any manual adjustments to a fixture's light or color profile settings. Refer to the Override Light Levels/Color Temporarily for a description of temporarily overriding the light profile settings. 

Request

POST https://{em_ip_address_or_hostname}/ems/api/org/switch/{switchId}/editAndApplyChanges

{
   "onOffStickyColor": true,
   "ovrStickyColor": true

}

Parameters

Request

em_ip_address or hostname

The Manage IP address or hostname

Switch ID

Switch Identifier. The Switch ID returned in the Get Switch Groups API

onOffStickyColor

Recall the last Scene color before the fixture was switched off. 
Set the value to True

ovrStickyColor

Recall the last scene color after the Override color duration. 
Set the value to True

Response

onOffStickyColor

True – Success; The fixtures will recall the last scene color when they are turned on using the ERC switch.

False – Failure; the lighting scene color is not recalled; the lights are turned to full maximum color when the lights are turned on.

ovrStickyColor

True – Success; the fixtures will recall the last scene color when they are turned on using the ERC switch after the Override period.

False – Failure; the lighting scene color is not recalled; the lights are turned to full maximum color level by default when the lights are turned on.

Sample Code 

To use this API call, you will need to know the Switch Group ID of the switch that controls the fixtures and the Floor ID.  Use the following two API calls to find the Floor ID and the Switch Group ID.

  • Get All Floors - Provides the list of all floors in a building. Identify the Floor ID of the floor on which the Switch is installed.
  • Get Switch Groups - Using the Floor ID, obtain the Switch Group ID for the switch that controls the fixture.

API Response:

POST https://10.8.1.90/ems/api/org/switch/2/editAndApplyChanges
{
   "onOffStickyColor": true,
   "ovrStickyColor": true

}

 {
      "id":   "3",
      "name":   "Sensor00c017",
      "floorid":   "2",
      "campusid":   "2",            
"xaxis":   "2895",

      "yaxis":   "2895",       
"modetype":   "0",

      "initialsceneactivetime":   "0",
      "extendsceneactivetime":   "0",
      "operationmode":   "0"
      "forceAutoMode":   "0"
      "onOffStickyColor": “true”,
      "ovrStickyColor": “true”
 },

Effect of Circadian Lighting when Enabled

When you use the Configure Recall Scene Lighting Scene Color API for fixtures with the Circadian option, the Circadian option takes precedence. Therefore, it will indefinitely override the Recall Last lighting Scene API for the fixtures.