Groups API

The groups API provides a means of interacting with groups in the Hue Bridge.

• getAll()
• getGroup()
• getGroupByName()
• get by type
  
• createGroup()
• updateGroupAttributes()
• deleteGroup()
• getGroupState()
• setGroupState()
  • Activating a Scene

getAll()

The getAll() function allows you to get all the groups that the Hue Bridge has defined.

api.groups.getAll()
  .then(allGroups => {
    // Display the groups from the bridge
    allGroups.forEach(group => {
      console.log(group.toStringDetailed());
    });
  });

This function call will resolve to an Array of Group instance objects (LightGroup, Zone, Room, Entertainment and Luminaire, see Group Objects for more details).

A complete code sample for this function is available here.

getGroup()

The getGroup(id) function will allow to to get the group specified by the id value.

• id: The integer id of the group you wish to retrieve, or a Group object that you want a refreshed copy of.

api.groups.getGroup(1)
  .then(group => {
    console.log(group.toStringDetailed());
  })
;

The call will resolve to a Group Object instance for the specified id.

A complete code sample for this function is available here.

getGroupByName()

The getGroupByName(name) function will retrieve the group(s) from the Hue Bridge that have the specified name. Group names are not guaranteed to be unique in the Hue Bridge.

api.groups.getGroupByName('myGroup')
  .then(matchedGroups => {
    // Display the groups from the bridge
    matchedGroups.forEach(group => {
      console.log(group.toStringDetailed());
    });
  });

The call will resolve to an Array of Group Objects](./group.md) that have a matching name.

A complete code sample for this function is available here.

get by type

You can retrieve a specific type of Group from the Hue Bridge using the following functions:

• getLightGroups()
• getLuminaires()
• getLightSources()
• getRooms()
• getZones()
• getEntertainment()

For example to get all the zone Groups from the Hue Bridge:

api.groups.getZones()
  .then(zones => {
    // Do something with the zone groups.
    console.log(`There are ${zones.length} defined zones in the bridge`); 
  })
;

All these functions will resolve to an Array of matching Group Objects that matches the type that was requested; e.g. a Zones if you call getZones().

A complete code samples for these functions is available here.

createGroup()

The createGroup(group) function allows you to create an instance of a specific Group Object in the Hue Bridge.

• group: The Group object that has been built that you wish to create, e.g. a LightGroup populated with a name and light ids

const group = v3.model.createLightGroup();
group.name = 'my new group';
group.lights = [2, 3];

api.groups.createGroup(group)
  .then(createdGroup => {
    console.log(`Created new group:\n${createdGroup.toStringDetailed()});
  })
;

The call will resolve to a Group Object that was created using the provided details.

Complete code samples creating various types of Groups are available:

• LightGroup
• Room
• Zone
• Entertainment

updateGroupAttributes()

The updateGroupAttributes(group) function allows you to update the attributes of an existing group. The attributes that can be modified are:

 * `name`
 * `lights`
 * `sensors`
 * `class`: The class for the Room/Zone or Entertainment Group

• group: The Group that has been modified with the updates you want to apply to the Bridge Group.

const group; // Obtained from some other call to retrieve this reference to a Group object from the bridge
// Update the name 
group.name = 'Updated Group Name';

api.groups.updateGroupAttributes(group)
  .then(result => {
    console.log(`Updated attributes: ${result}`)
  })
;

The call will resolve to a Boolean indicating the success status of the update to the specified attributes.

A complete code sample for this function is available here.

deleteGroup()

The deleteGroup(id) function allow you to delete a group from the Hue Bridge.

• id: The integer id of the group to delete, or a Group Object that you wish to remove

api.groups.deleteGroup(id)
  .then(result => {
    console.log(`Deleted group? ${result}`);
  })
;

The call will resolve to a Boolean indicating the success status of the deletion.

A complete code sample for this function is available here.

getGroupState()

The getGroupState(id) function allows you to get the current state that has been applied to the Group.

• id: The id of the group to get the state for, or Group Object.

api.groups.getGroupState(id)
  .then(state => {
    // Display the current state
    console.log(JSON.stringify(state, null, 2));
  })
;

The call will resolve to an Object that contains the current state values for the Group

setGroupState()

The setGroupState(id, state) function allows you to set a state on the lights in the specified Group.

• id: The id of the group to modify the state on, or a Group Object.
• state: A GroupLightState for the group to be applied to the lights in the group. This can be an Object with explicit key values or a GroupLightState Object.

Using an Object for the state, which must conform to the various state attributes that can be set for a Group:

api.groups.setGroupState(groupId, {on: true})
  .then(result => {
    console.log(`Updated Group State: ${result}`);
  })
;

Using a GroupLightState Object:

const GroupLightState = require('node-hue-api').v3.model.lightStates.GroupLightState;
const groupState = new GroupLightState().on();

api.groups.setGroupState(groupId, groupState)
  .then(result => {
    console.log(`Updated Group State: ${result}`);
  })
;

The call will resolve to a Boolean indicating success state of setting the desired group light state.

A complete code sample for this function is available here.

Activating a Scene

The setGroupState(id, state) function (as detailed above) is the function that needs to be used to activate/recall an existing Scene that is stored in the Hue Bridge / Lights.

The lights that are affected by the Scene activation is the intersection of the members of the Group and the lights that were Scene associated with it.

This means you can potentially target a single room/zone when recalling a Scene that might straddle multiple rooms or zones by limiting the target Group when recalling the Scene.

So to ensure that you target all the lights that you associated with a Scene, when activating it, you would need to utilize the special All Lights Group which has an id of 0.

Example for recalling a Scene using the All Lights Group, that is all lights saved in the scene will be activated:

const GroupLightState = require('node-hue-api').v3.lightStates.GroupLightState;
const mySceneLightState = new GroupLightState().scene('my-scene-id');

api.groups.setGroupState(0, mySceneLightState)
  .then(result => {
    console.log(`Activated Scene? ${result}`);
  })
;

Note: There is a convenience function on the Scenes API activateScene(id) that is a wrapper around the setGroupState() API call targeting the All Lights Group.