scene.md

Scene

The Hue Bridge can support two variations of a Scene, LightScene and GroupScene.

A Scene is represented as an id a name and a list of Lights stored inside the Hue Bridge. These are separate from what a scene is in the iOS and Android applications.

• Common Scene Properties
• LightScene
  • Creating a LightScene
  • Properties
    • lights
    • lightstates
• GroupScene
  • Creating a GroupScene
  • Properties
    • group
    • lights
    • lightstates

Common Scene Properties and Functions

Depending upon the properties that you chose to set on the Scene the type attribute will be implicitly set for you by the API. This type dictates what attributes are modifiable in the Hue Bridge.

• id
• name
• type
• owner
• recycle
• locked
• appdata
• picture
• lastupdated
• version
• toString()
• toStringDetailed()

id

Get the id for the Scene.

• get

name

Get/Set a name for the Scene.

• get
• set

type

Get/Set the type of the scene, which is one of GroupScene or LightScene. Users should not need to set this value, instead using the set on the group or lights properties instead.

• get
• set

owner

Gets the owner of the Scene.

• get

recycle

Get/Set the recyle attribute of the Scene. This is used to flag scenes that can be automatically deleted by the bridge. If the recycle state is set to false the Hue bridge will keep the scene until an application removes it.

• get
• set

locked

Gets the locked state of the Scene. A locked scene means that the scene is in use by the rule or schedule.

• get

appdata

Get/Set the associated application data for the scene. This is an Object payload that the application is responsible for any format/encoding/meaning of this data.

• get
• set

When setting this value, you need to create an Object with tow keys:

• version: A version for specifying the version on the data object that you are storing.
• data: Any data that you wish to store specific to your application, this can be between 0 and 16 characters.

For example we could store the location and application_name in the appdata using a payload of the form:

{
  version: 1,
  data: 'my-custom-app-data'
}

picture

Get/Set the picture data for the scene. The Hue Bridge does not support setting this via a PUT call which means it is not possible to update this data field, only at the time of creation.

• get
• set

lastupdated

Gets the last updated time for the Scene.

• get

version

Gets the version of the Scene

• get

toString()

The toString() function will obtain a simple String representation of the Scene.

toStringDetailed()

The toStringDetailed() function will obtain a more detailed representation of the Scene object.

LightScene

This is the default type of Scene in the Hue Bridge. It maintains a list of lights that the are associated with the Scene, which can be updated.

Creating a LightScene

You can create a new LightScene object using the v3.model.createLightScene() function.

LightScene Properties

The following are the LightScene specific properties above those already defined in the Common Scene Properties and functions.

lights

The associated light ids for the LightScene.

• get: Obtains the Array of light ids
• set: Set the Array of light ids associated with the LightScene

lightstates

Gets/Sets the desired LightState for the lights in the scene. This is primarily used to provide some backwards compatibility in the API with v2, not for normal user usage.

• get
• set

Note: lightStates are only present on scenes that have explicitly been retrieved from the Hue Bridge, that is, scenes that you have obtained from the v3.api.scenes.get(id) API call.

GroupScene

A GroupScene is a Scene with a type of GroupScene. These scenes are linked to an specified Group in the Hue Bridge.

The associated lights for the GroupScene is controlled via the Group. When the Group becomes empty or is removed from the Bridge, the associated GroupScenes are also removed.

The lights for a GroupScene are not modifiable as they belong to the Group object.

Creating a GroupScene

You can create a new GroupScene object using the v3.model.createGroupScene() function.

GroupScene Properties

The following are the LightScene specific properties above those already defined in the Common Scene Properties and functions.

group

The group ID for the GroupScene if associated with a group.

• get
• set

lights

The associated light ids for the GroupScene. This is controlled via the membership of the lights in the Group that the GroupScene is associated with.

• get: Obtains the Array of light ids in the target Group

lightstates

Gets the LightStates for the lights in the GroupScene. This is primarily used to provide some backwards compatibility in the API with v2, not for normal user usage.

• get

Note: lightStates are only present on scenes that have explicitly been retrieved from the Hue Bridge, that is, scenes that you have obtained from the v3.api.scenes.get(id) API call.