跳到主要内容
Documentation Hub

Scenes

about

In the context of IoT in general and ESP RainMaker in particular, a "scene" refers to a group of parameters set to specific values, where one or more devices may span across multiple nodes.

Note that the scene is a static entity, and some operation is required to activate a scene, be it via phone apps, voice assistants, or a predefined schedule.

In line with the rest of the ESP RainMaker features, scenes are implemented completely on the node side in the form of a "service". The cloud backend just acts as a gateway between the node and the clients, like phone apps.

The entire complexity of the scenes feature is hidden beneath a simple C API and also abstracted out by the phone apps.

Use Case​

Scenes in ESP RainMaker enable seamless control of multiple devices with a single command, enhancing convenience and efficiency in smart homes and industrial setups. Users can personalize scenes like "Movie Night" or "Work Mode" without manual adjustments, automating actions via Alexa or Google Assistant.

For example, an "Evening" scene can turn on lights with a warm hue, while a "Night" scene can dim the bedside lamp and activate the fan or AC. By optimizing power usage, scenes also promote energy savings, making them a practical and cost-effective IoT solution.

Before proceeding

If you are already familiar with the Scenes in ESP RainMaker, please proceed to the usage guides.

  • For the usage of scenes on firmware, click here.
  • On what to note for Scenes Across Nodes for phone apps, click here.
  • On what to note for Scenes with voice assistant integrations, click here

Else, please read on.

Specifications​

The scenes service consists of a single parameter which is an array of objects. It shows up in the node configuration as this:

JSON Payload (Click to view)
"services": [{
  "name": "Scenes",
  "params": [{
      "bounds": {
          "max": 10
      },
      "data_type": "array",
      "name": "Scenes",
      "properties": [
          "read",
          "write"
      ],
      "type": "esp.param.scenes"
  }],
  "type": "esp.service.scenes",
  "attributes": [{
      "name": "deactivation_support",
      "value": "no"
  }]
}]
  • The scenes parameter is an empty array by default.
  • The "max" bound indicates the maxmum number of scenes a node can have.
  • Deactivation support will be disabled by default, but can be enabled using:
    CONFIG_ESP_RMAKER_SCENES_DEACTIVATE_SUPPORT.

Add a New Scene​

A new scene can be added by passing a value like this in setparam: This is usually sent from the client side to the cloud or directly to the node via local control.

JSON Payload (Click to view)
{
    "Scenes": {
        "Scenes": [{
            "name": "Evening",
            "id": "8D36",
            "info": "My Test Scene",
            "operation": "add",
            "action": {
                "Light": {
                    "Power": true
                }
            }
        }]
    }
}
  • name: A user friendly name for the scene.
  • id: A unique ID for the scene. The ID needs to be unique only for the given user, not universally unique. This should be generated by the client while adding a scene, and then used for any further operations. A shorter ID is desirable.
  • info (optional): Additional info or description as per the clients' requirements.
  • flags (optional): General purpose flags which can be used as per the clients' requirements.
  • operation: The operation to be performed. Possible values are add, remove, edit, activate, or deactivate.
  • action: The actual action to be performed when the scene is activated. The value of this object will be same as what you pass while setting the params. For example, for turning on the light, it will be "Light": {"power": true}.

Once the scene is added successfully, a get on params will report a similar value like below:

  • This is an acknowledgment response sent from the node to the cloud or to the phone app.
JSON Payload (Click to view)
{
    "Scenes": {
        "Scenes": [{
            "name": "Evening",
            "id": "8D36",
            "info": "My Test Scene",
            "action": {
                "Light": {
                    "Power": true
                }
            }
        }]
    }
}
To note

When you add or update scenes, a single entry is sent in the scenes array. However, when you query scenes, the node will return information of all the scenes in the array.

Other Operations​

Edit​

  • Value passed for editing the scene will be similar to that passed for adding a new scene.

  • he ID should match an existing scene and the operation value should be edit.

  • You can either send the entire object or only the elements that have changed (name or action). However, objects in these keys cannot be partial.

    For Example
    • If current action is "action":{"Light": {"Power": true, "Brightness":90}}
    • And you need to change brightness to 100.
    • You should pass...
      ✓ "action":{"Light": {"Power": true, "Brightness":100}} not
      ✗ "action":{"Light": {"Brightness":100}}

Remove​

  • To remove an existing scene, you just need to pass its ID and "operation": "remove".
    See the example below.
JSON Payload (Click to view)
{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "remove"
        }]
    }
}

Activate​

  • To activate a scene, you just need to pass its ID and "operation": "activate".
    See the example below.
JSON Payload (Click to view)
{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "activate"
        }]
    }
}

Deactivate​

  • As the name suggests, this is opposite operation of activation, but the payload will be similar, just with "operation": "deactivate".
    See the example below.
JSON Payload (Click to view)
{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "activate"
        }]
    }
}
to note

Note that deactivation won't be supported by default in the firmware. Please see Usage Guide section for additional information.

Usage Guide​

Firmware​

This usage guide would mainly cover the firmware side of setup and configuration for scenes.
On the usage of scenes on firmware, click here.

Phone Apps​

The phone applications provide a very simple user interface for various scenes operations. Please update your phone apps, enable scheduling in the firmware, and get started.

Scenes Across Nodes
For scenes across multiple nodes, the client will assign a common scene ID across nodes so that the client can query and group them as a unified scene.
Click here to view more information and an example.

Voice Assistant Integration​

Even though the ESP RainMaker backend acts like a conduit between devices and clients, scenes are treated differently. The backend parses the scene information so that it can be reported to Alexa and Google Voice Assistant (GVA) in a format they can understand. So, any scenes created in RainMaker get exported to Alexa and GVA with RainMaker Alexa Skill or Google Actions enabled.

On this page