Conference Room APIs – Enlighted Inc

Get Switch Groups

Switch Groups control turning on or off a group of fixtures . This API returns all Switch Groups on a floor in the building. The response includes the Switch Group ID and Switch Name for each Switch Group. The Switch Name and ID are used as the primary identifiers in other API calls.

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/switchgroups/list/{facility}/{fid}

Parameters

Request
em_ip_address or hostname	The Enlighted Manage (EM) IP address or hostname.
facility	The facility type can be either a floor or a company.
fid	Company or Floor ID. By default, the Company ID is always ‘1’. For Floor ID, use the Floor ID returned in the Get All Floors API or in EM, select Facility > Floor > in the left panel, and click the Settings tab to obtain the Floor ID.
Response
id	Switch Group identifier in EM
name	Switch name (**used as the primary identifier in other API calls)

Sample Code

A user can request for the list of all Switch Groups on a floor using the Floor ID. For obtaining a list of all Floor IDs in a building, use the Get All Floors API. The Switch Group ID and Switch name for all switch groups, on a floor is returned. For example, if Floor 1 has two switch groups, the Switch Group ID and Switch Name are returned. The Switch name is used as the primary identifier in other API calls.

Get https://191.18.0.1/ems/api/org/switchgroups/list/floor/1
"gemsGroup":[
   {
      "id": 7,
      "name": "594_SWG"
   },
   {
      "id": 8,
      "name": "595_SWG"
   }
 ]

Get Switch Scenes

The API returns the virtual switch details and scene information. A virtual switch is added to the floor plan in the Enlighted Manage (EM) when a Switch Group is created. A virtual switch controls the light levels of selected fixtures. Each set of light level settings for fixtures is called a scene.

For example, in a conference room, typical scenes would include

using a projector when the lights should be off (all off), or
during a meeting when the lights should be on (all on).

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/switch/v1/getSwitchScenes/{floor_id}/{switch_name}

Parameters

Request
em_ip_address or hostname	The EM’s IP address or hostname.
floor_id	Floor identifier. Returned in Get All Floors API, or in EM, select Facility > Floor > in the left panel, and click the Settings tab to obtain the floor_id.
switch_name	Switch name. Returned in Get Switch Groups API, or in EM, select Facility > Floor in the left panel, click Floor Plan tab, and hover the cursor over the switch icon to see the switch name.
Response
id	Switch Identifier to which the scene belongs.
name	Switch name.
scenes	List of scenes. A maximum of six scenes can be created for a switch. For each scene, the following parameters are displayed. id - Scene identifier (used as the primary identifier in other API calls). switchid - Switch identifier to which the scene belongs. name - Scene name. sceneOrder - Order of scenes on the associated Enlighted Room Control (ERC) switch.

Sample Code

Using the switch name (SwitchGrp2) returned in the Get Switch Groups and Floor ID returned in Get All Floors, request the Manage to provide the virtual switch and scene details. For example, if the switch, SwitchGrp2, is configured for two scenes All on, All off, the following virtual switch details are returned as shown below. The scene identifiers (for example, 157, 158) returned for the scenes are used as the primary identifiers in other API calls.

Get https://192.80.3.2/ems/api/org/switch/v1/getSwitchScenes/1/SwitchGrp2

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT


{
  "id":"7",             **switch identifier**
  "name":"SwitchGrp2",   **switch name**
  "scenes":[
    {
      "id":"157",        **scene identifier (Primary id used in other API calls)**
      "switchid":"7",    **switch identifier (Primary id used in other API calls)**
      "name":"All On",   **scene name**
      "sceneOrder":"1"   **scene order**
    },
    {
      "id":"158",        **scene identifier**
      "switchid":"7",    **switch identifier**
      "name":"All Off",  **scene name**
      "sceneOrder":"2"   **scene order**
    }
  ]
}

Get Scene Light Levels for a Switch

When a switch is created, a virtual switch is added to the floor plan, which controls the light levels of the selected fixtures. Each set of light level settings for fixtures is called a scene. A maximum of six scenes can be created. Each fixture in a scene can have different light levels to achieve the desired effect.

The API returns the scene light levels for the group of fixtures controlled by the scene.

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/scene/v1/list/getSceneLevels/{sceneid}

Parameters

Request
em_ip_address or hostname	The Enlighted Manage (EM) IP address or hostname.
sceneid	Scene identifier. Returned in Get Switch Scenes API.
Response
id	For internal use.
switchid	Switch identifier.
sceneid	Scene identifier. Up to a maximum of six scenes can be defined.
fixtureid	Fixture identifier of the fixture for which the scene applies.
lightlevel	Returns the light level (0-100%) for each fixture for the scene. 0% - Light level is set to off. 100% - Light level is set to full-on.
scenecolor	Current color temperature value in Kelvin degrees

Sample Code

Using the Scene ID '157' returned by the Get Switch Scenes API, request the scene light levels for the fixtures. The API returns the light levels for the scene controlled by the scene with ID ‘157’.

Get https://192.80.3.2/ems/api/org/scene/v1/list/getSceneLevels/157

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT

{
  "sceneLevel": [
  {
    "id": "6",                   **scene level identifier**
    "switchid": "7",             **switch identifier**
    "sceneid": "157",            **scene identifier**
    "fixtureid": "885",          **fixture identifier**
    "lightlevel": "100"          **light level**
    "sceneColor": "3200"         **color temp value**
  },
  {
    "id": "9",                  **scene level identifier**
    "switchid": "7",            **switch identifier**
    "sceneid": "157",           **scene identifier**
    "fixtureid": "886",         **fixture identifier**
    "lightlevel": "60"          **light level**  
    "sceneColor": "3600"        **color temp value**
  }
 ]
}

Apply Scene

Applies a scene to a group of fixtures controlled by the switch. Each set of light level settings for fixtures is called a scene. For example, in a conference room, typical scenes would include using a projector when the lights should be off (all off) or during a meeting when the lights should be on (all on).

Request

POST https://{em_ip_address_or_hostname}/ems/api/org/switch/v1/op/applyScene/{switch_id}/{scene_id}

Parameters

Request
em_ip_address or hostname	The Enlighted Manage (EM) IP address or host name
switch_id	Switch identifier (returned in Get Switch Scenes API)
scene_id	Scene identifier (returned in Get Switch Scenes API)
Response
id	Scene identifier
status	0 – Success; Other than ‘0’: Failure Failure codes: 1 – Switch not available 2 – Switch group not available 3 – Fixtures and plugloads not available in the switch group 4 – List of associated fixtures and plugloads in the switch group empty -1 – Failure condition

Sample Code

Apply the scene 'All off' with the Scene ID ‘158’ to the Switch which has ID '7'. You can use the Get Switch Scenes API to get the Scene ID and Switch ID. The response ‘0’ indicates that the 'All off' scene was applied to the switch successfully.

POST https://192.80.3.2/ems/api/org/switch/v1/op/applyScene/1/158

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT
{
  "status": "0"
}

Manual Override for Switch Group

This API allows you to manually override fixture profile settings associated with a switch and dim the fixtures for a period of time on the floor.

Request

POST https://{em_ip_address_or_hostname}/ems/api/org/switch/v1/op/dimGroup/{floor_id}/{switch_name}/ {dimLevel}?time=60

Parameters

Request
em_ip_address or hostname	The Enlighted Manage (EM) IP address or hostname.
floor_id	Floor identifier. Returned in Get All Floors API ,or in EM, select Facility > Floor > in the left panel, and click the Settings tab to obtain the Floor ID.
switch_name	Switch name. Returned in Get Switch Groups API. However, note that all switches on the floor are returned. The recommended path to determine a specific switch name in EM is select Facility > Floor in the left panel, click Floor Plan tab, and hover the cursor over the switch icon to see the switch name.
dimLevel	Specifies the dim level to which the fixtures in the group should be set to (0-100%, must be a whole number).
time	The manual override duration time (must be a whole number). The default time is set to 60 minutes.
Response
status	0 – Override success. 1 – Override failed.

Sample Code

Manually override fixture profile settings on floor 1 associated with switch ‘SwitchGrp1’ (returned in the Get Switch Groups API) to dim the fixtures for 60 minutes using the EM IP address. In the example below, all fixtures controlled by 'SwitchGrp1' switch on Floor 1 will be dimmed for 60 minutes.

Post https://192.80.3.2/ems/api/org/switch/v1/op/dimGroup/1/SwitchGrp1/50?time=60

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT
{
  "status": "0"
}