Filter results by

Scenes

Scenes are groups of Actions that are sent to one or more devices. Scenes enable multiple devices to quickly work in contexts where complex Rules are unnecessary. This article summarizes how Scenes are programmatically created and managed.

You can also create and manage Scenes using the web UI.

Your application can use Scenes to control multiple devices in various use cases:

  • Home Scene: Turn on the entrance and hallway lights, unlock the door, set the thermostat to 22°C.
  • Away Scene: Turn off all lights, lock the door, set the thermostat to 18°C.
  • Cooking Scene: Turn on the kitchen light, turn on the kitchen radio.

Devices in a Scene can belong to different device types.

How Scenes work

When a Scene is activated, it sends the specified Actions to their corresponding devices.

Activating a Scene does not result in a state change on the Scene. Scenes do not have states on ARTIK cloud services, unlike devices.

The Scenes API allows you to list, create, and manage Scenes for an application.

To use the API calls below, your application must have the required permissions on the device types and/or devices used in the Scene. Refer to the corresponding sections of the API reference for details.

Creating a Scene

POST /scenes

A Scene must be created with a name, description, and list of Actions to be sent to specified devices.

If authenticating with an application token, also pass a uid (user ID).

1
2
3
4
5
6
7
8
{
  “uid”: “637f11a303c94dd2bc953586dd2f0ac8”,
  “name”: “My Scene”, 
  “description”: “Scene description”,
  “actions”: [
      ...
  ]
}

The Actions are formatted as in the Rule Body.

To send an Action to a specific device, pass its ddid (destination device ID) along with the Action and any relevant Action parameters.

1
2
3
4
5
6
7
8
9
{
  “ddid”: “3333cccc”,
  “action”: “setTemperature”,
  “parameters”: { 
    “targetTemperature”: { 
      “value”: 24 
    } 
  }
}

You can also send Actions to every device belonging to a specified device type. Instead of the ddid, pass selector with the value every and the dtid (device type ID).

1
2
3
4
5
6
7
{
  “ddid”: {
    “selector”: “every”,
    “dtid”: “bbbb2222”
   },
  “action”: “setOn”,
}

The call returns a Scene ID that you will use to manage and activate your Scene.

1
2
3
4
5
{
  “data”: {
    “id”: “s0a3059230384215acf8ba25c2fbfcb7”,
  ...
}

See the API here.

Updating a Scene

PUT /scenes/<sceneID>

You can modify the name, description, Actions, and devices of a Scene. Use the Scene ID obtained when you created the Scene. Any of the parameters included in the request for creating the Scene can be changed, except for the uid. See the API here.

Deleting a Scene

DELETE /scenes/<sceneID>

A Scene can be deleted with the above call. Use the Scene ID obtained when you created the Scene. See the API here.

Listing Scenes

`GET /scenes/

A Scene and its parameters can be retrieved using the Scene ID. See the API here.

GET /users/<userID>/scenes

Scenes can also be listed per user. In the above call, the user ID is passed along with an application or user token. See the API here.

GET /scenes

This call has the same effect but does not accept a user ID. Instead, it infers the user from a user token. See the API here.

Activating a Scene

POST /scenes/<sceneID>

This API call sends the Actions specified in a Scene to their corresponding devices. In addition to the scene ID in the path, you must send an empty JSON body in the request. You may receive a success or error JSON in response. See the API here.

Invalid Scenes

A Scene can become invalid if one of its destination devices is deleted. A call to get a scene will then return additional fields that include the timestamp the Scene was invalidated and the corresponding error code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  ...
  “invalidatedOn”:1507202001722,
    “error”:{  
      “code”:4001,
      “message”:”Validation Error”,
      “errors”:[  
        [  
          {  
             “field”:”actions.0.ddid”,
             “messages”:[  
               “Device \”402fb463227f447da3ec5cbd118958de\” does not exist”
              ]
           }
        ]
      ]
    }
  }

If creating or activating a Scene results in an error, the error will be returned in the following generic format:

1
2
3
4
5
6
7
8
{
...
  “error”: {
    “errorType”: “Type of error”,
    “errorMessage”: “...”
  }
...
}

Rate limits on Scenes

Actions of a Scene must conform to the following rate limits:

  • 5 emails per minute and 50 emails per day
  • 5 HTTP calls per minute and 50 HTTP calls per day