Get Switch Groups

Groups used for lighting control are called switch groups. 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 is used as the primary identifier 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

Using the Floor ID returned in the Get All Floors API, request for the list of all switch groups on the floor. The Switch Group ID and Switch name for all switch groups on Floor 1 is returned. For example, if Floor 1 has two switch groups, the Switch Group ID and Switch name are returned as shown below. The Switch name is used as the primary identifier in other API calls.

Get https://192.80.3.2/ems/api/org/switchgroups/list/floor/1

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
 
{
  "gemsGroups": {
    "gemsGroup": [
      {
        "id": "19", **switch group identifier**
"name": "SwitchGrp1" **switch name**

      },
      {
        "id": "29", **switch group identifier**
"name": "SwitchGrp2" **switch name**
          }
    ]
  }
}

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"
}