场景功能

在物联网的大背景下，尤其是在 ESP RainMaker 的语境中，“场景”指设置为特定值的一组参数，让一个或多个设备可以跨越多个节点。例如，“傍晚”场景能够打开所有灯源并将其设置为暖光。“夜晚”场景能够关闭所有灯源，将床头灯设置为最低亮度，并打开风扇/空调。

请注意，场景是一个静态实体，需要通过手机应用程序、语音助手或预先设置的定时服务来启用场景。

与 ESP RainMaker 的其余功能类似，场景功能全部在节点端以“服务”的形式实现。云后端只充当节点和手机应用等客户端之间的通道。

场景功能所有复杂的实现细节都封装在一个简单的 C 语言 API 中，并由手机应用抽象出来。即便如此，我们也需要先了解场景功能的参数说明。

也可直接跳转至使用方法。

参数说明

场景服务由单个参数组成，参数为对象数组。场景服务在节点配置中的参数如下：

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

场景参数默认为空数组，"max" 阈值表示节点可以拥有的最大场景数量。停用功能默认禁用，但是可以通过 CONFIG_ESP_RMAKER_SCENES_DEACTIVATE_SUPPORT 启用。

添加场景

可以通过在 setparams 中传递以下类似值来添加场景：

{
    "Scenes": {
        "Scenes": [{
            "name": "Evening",
            "id": "8D36",
            "info": "My Test Scene",
            "operation": "add",
            "action": {
                "Light": {
                    "Power": true
                }
            }
        }]
    }
}

name：场景名称，建议使用用户友好的名称。
id：场景的唯一 ID，只需对某一用户唯一，无需全局唯一。在添加场景时，ID 应由客户端生成，然后再用于后续操作，建议使用简短的 ID。
info（可选）：根据客户端要求提供的额外信息或描述。
flags（可选）：根据客户端要求使用的通用标志。
operation：执行的操作，对应值可以为 add、remove、edit、activate 或 deactivate。
action：启用场景执行的具体行动。该对象的值与设置参数时传递的值相同。例如，开灯的对应值为 "Light": {"power": true}。

成功添加场景后，对于参数的 get 请求将获取以下类似值：

{
    "Scenes": {
        "Scenes": [{
            "name": "Evening",
            "id": "8D36",
            "info": "My Test Scene",
            "action": {
                "Light": {
                    "Power": true
                }
            }
        }]
    }
}

注意：在添加或更新场景时，仅发送场景数组中的单个条目。但是在查询场景时，节点会返回数组中所有场景的信息。

其他操作

编辑

编辑场景传递的值与添加场景类似，ID 应与现有场景匹配，operation 的值应为 edit。可以发送整个对象，也可以只发送更改的元素（如场景名称或具体行动），但是这些键中的对象必须保持完整。

例如，如果当前行动为 "action":{"Light": {"Power": true, "Brightness":90}}，要将亮度更改为 100，则应传递 "action":{"Light": {"Power": true, "Brightness":100}}，而非 "action":{"Light": {"Brightness":100}}。

删除

删除现有场景，只需传递场景 ID 和 "operation": "remove"。请参考下例。

{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "remove"
        }]
    }
}

启用

启用场景只需传递场景 ID 和 "operation": "activate"。请参考下例。

{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "activate"
        }]
    }
}

注意：这也可以用作添加定时服务的行动。

停用

顾名思义，该操作与启用相反，但是有效载荷类似，只需将 operation 值设置为 deactivate。请参考下例。

{
    "Scenes": {
        "Scenes": [{
            "id": "8D36",
            "operation": "deactivate"
        }]
    }
}

请注意，固件默认不支持停用场景。了解更多信息，请查看使用方法。

使用方法

固件

ESP RainMaker 提供了单个 API 来启用场景功能：

esp_err_t esp_rmaker_scenes_enable(void);

此 API 应在 esp_rmaker_node_init() 之后以及 esp_rmaker_start() 之前调用。

可以使用 CONFIG_ESP_RMAKER_SCENES_MAX_SCENES 配置选项配置支持的最大场景数量 (idf.py menuconfig > ESP RainMaker Config > ESP RainMaker Scenes > Maximum scenes)。

设置 CONFIG_ESP_RMAKER_SCENES_DEACTIVATE_SUPPORT=y 可以启用停用功能。这一功能默认禁用，因为停用场景需要先保存停用前的参数值，操作完成后将参数恢复为之前的值，这一过程较为复杂，可能引起不一致的行为。即使启用了停用功能，RainMaker 内核也不会直接执行此操作。当收到场景停用请求时，内核只会调用相应的服务写入回调函数，应用程序注册的回调函数将管理保存/恢复参数值。

当收到场景启用请求时，内核将调用相应的服务写入回调函数，并将 esp_rmaker_req_src_t 设置为 ESP_RMAKER_REQ_SRC_SCENE_ACTIVATE。停用场景时，内核将调用相应的回调函数，并将 esp_rmaker_req_src_t 设置为 ESP_RMAKER_REQ_SRC_SCENE_DEACTIVATE。

手机应用程序

最新的安卓和 iOS 应用程序支持场景功能，可以直接在应用中查看。

跨节点场景

如上所述，场景信息由节点而非云后端维护。然而，多个节点共享单个场景的需求也比较常见。就此类场景而言，客户端可以在多个节点上使用相同的场景 ID。在查询场景时，也会在所有节点中查找并显示共享的场景 ID。创建跨节点场景的示例载荷如下：

在 {{base_url}}/v1/user/nodes/params 上发出 POST 请求，有效载荷如下：

[{
    "node_id": "<nodeid_1>",
    "payload": {
        "Scenes": {
            "Scenes": [{
                "name": "Night1",
                "operation": "add",
                "id": "1112",
                "action": {
                    "Light": {
                        "Power": true,
                        "Hue": 280
                    }
                }
            }]
        }
    }
}, {
    "node_id": "<nodeid_2>",
    "payload": {
        "Scenes": {
            "Scenes": [{
                "name": "Night1",
                "operation": "add",
                "id": "1112",
                "action": {
                    "Switch": {
                        "Power": true
                    }
                }
            }]
        }
    }
}]

第三方集成场景

虽然 ESP RainMaker 后端是设备和客户端之间的通道，但是不同场景的处理方式不尽相同。后端解析场景信息，随后以 Alexa 和 Google Voice Assistant (GVA) 可以理解的格式报告信息。因此，如果启用 RainMaker Alexa Skill 或 Google Actions，RainMaker 创建的所有场景都会导出至 Alexa 和 GVA。

场景功能

参数说明​

添加场景​

其他操作​

编辑​

删除​

启用​

停用​

使用方法​

固件​

手机应用程序​

跨节点场景​

第三方集成场景​