场景控制

更新时间：2024-04-17 06:15:00下载pdf

本文介绍场景控制功能。

概述

概念介绍

指在涂鸦智能 App 内创建的预定义操作，即一键执行场景，这些操作可以通过一种方式下沉至设备端，从而通过设备端触发和控制相应的场景。

该设计使得用户不需要打开手机 App 来触发操作控制，而是直接通过设备端触发和控制相应场景的功能，为用户提供更便捷、智能和简单的方式。

功能描述

将通过涂鸦智能 App 创建的一键执行场景同步至设备，而后在连接的状态下可直接在设备内控制，触发对应场景执行。以下用手表设备来演示具体流程。

在 App 端完成场景设置，一键执行。
设备与 App 连接，设备触发请求场景数据，App 从云端拉取数据，同步给设备。
手表设备获取数据后，显示场景名称和场景。
单击手表内某一场景，发送场景控制指令给 App。
App 调用相应接口触发云端执行场景，从而实现场景控制。

数据结构

tuya_ble_request_scene_t

请求场景（含场景数据与控制）相关结构体。

/**@brief    Request scene type. */
typedef enum {
    REQUEST_SCENE_DATA = 1, /**< request scene list data. */
    REQUEST_SCENE_CONTROL,  /**< request scene control. */

    REQUEST_SCENE_CMD_MAX,
} request_scene_cmd;

/**@brief    Request scene list data structure. */
typedef struct {
    UINT8_T nums;                   /**< request scene numbers, ranging from [1-SUPPORT_REQUEST_SCENE_MAX_NUMS]. */
    UINT16_T name_unicode_length;   /**< request scene name length. The encoding format is unicode, and it must be a multiple of 2. */
    UINT32_T check_code;            /**< scene check code, algorithm-crc32. */
} request_scene_list_data_t;

/**@brief    Request scene control structure. */
typedef struct {
    UINT8_T scene_id_length;                /**< scene id length. */
    UINT8_T scene_id[SCENE_ID_MAX_LENGTH];  /**< scene id. Max length equal to SCENE_ID_MAX_LENGTH. */
} request_scene_control_t;

/**@brief    Request scene cmd structure. */
typedef struct {
    request_scene_cmd scene_cmd;                    /**< request scene cmd. */

    union {
        request_scene_list_data_t   scene_data;     /**< request scene list data info. */
        request_scene_control_t     scene_control;  /**< request scene ctrl info. */
    };
} tuya_ble_request_scene_t;

tuya_ble_scene_req_response_t

请求场景响应，回调给应用的数据结构，对应回调事件为 TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE。

typedef struct {
    uint16_t scene_cmd; /**< scene cmd. 1-scene data, 2-scene control */
    uint8_t status;     /**< response status, 0-success, 1-failed. */
    uint32_t err_code;  /**< err code, 0-success, others-failed */
} tuya_ble_scene_req_response_t;

tuya_ble_scene_data_received_data_t

请求场景列表数据结果，回调给应用的数据结构，对应回调事件为 TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED。

typedef struct {
    uint8_t status;         /**< status, 0-success, 1-failed. */
    uint32_t err_code;      /**< err code, 0-success, others-failed */
    bool need_update;       /**< need update, true-need update */
    uint32_t check_code;    /**< scene data check code, used crc32. */

    uint8_t *p_data;        /**< scene data. */
    uint16_t data_len;      /**< scene data length. */
} tuya_ble_scene_data_received_data_t;

tuya_ble_scene_ctrl_received_data_t

请求场景控制结果，回调给应用的数据结构，对应回调事件为 TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED。

typedef struct {
    uint8_t status;       /**< status, 0-success, 1-failed. */
    uint32_t err_code;    /**< err code. */
    uint8_t scene_id_len; /**< scene id length. */
    uint8_t *p_scene_id;  /**< scene id. */
} tuya_ble_scene_ctrl_received_data_t;

接口说明

宏配置依赖

#define TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE 1

#define TUYA_BLE_FEATURE_SCENE_ENABLE 1

请求场景数据/控制

接口说明

tuya_ble_status_t tuya_ble_feature_scene_request(tuya_ble_request_scene_t *req_data)

参数说明

参数	说明
req_data	请求场控数据，支持请求列表数据与控制。详见数据结构 tuya_ble_request_scene_t 定义。

回调事件-请求响应

TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE

回调事件	TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE
数据结构	请求场景 App 返回的响应数据，详见数据结构 tuya_ble_scene_req_response_t 定义
描述	设备调用请求场景 API 接口后，App 回复的请求响应

回调事件-场景数据

TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED

回调事件	TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED
数据结构	请求场景返回的列表数据，详见数据结构 tuya_ble_scene_data_received_data_t 定义其中 p_data 存放的是返回的所有场景数据，每条场景数据格式如下表定义：
描述	App 从云端请求到的一键执行场景数据返回给 SDK，SDK 回调给应用层事件与数据

场景数据格式 定义：

场景 ID 长度	场景 ID	场景名称长度	场景名称	……	场景 ID 长度	场景 ID	场景名称长度	场景名称
1 字节	n 字节	2 字节	m 字节	……	1 字节	n 字节	2 字节	m 字节

回调事件-场景控制

TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED

回调事件	TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED
数据结构	请求场景控制返回的结果，详见数据结构 tuya_ble_scene_ctrl_received_data_t 定义
描述	场景控制结果，SDK 回调给应用层事件与数据

使用方法

通信流程

代码开发

在 app_config.h 中启用场景控制组件，使能对应的宏配置。场景控制依赖 IoT 通道通用能力，也需一同使能。

#define TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE 1

#define TUYA_BLE_FEATURE_SCENE_ENABLE 1

添加请求场景数据/控制代码，以下仅作为示例。

/**
* Example 1: req scene data with the following details:
*         Number of scenes: 1
*         Scene name Unicode length: 10
*        Local scene verification code: 0
*/
tuya_ble_request_scene_t req_scene_data;

req_scene_data.cmd_type = REQUEST_SCENE_DATA;
req_scene_data.scene_data.nums = 1;
req_scene_data.scene_data.name_unicode_length = 10;
req_scene_data.scene_data.check_code = 0;
tuya_ble_feature_scene_request(&req_scene_data);

/**
* Example 2: req scene control with the following details:
*         Scene id: "nRAfyPBArgTAPgUq"
*/
tuya_ble_request_scene_t req_scene_data;
static const char test_scene_id[] = "nRAfyPBArgTAPgUq";

req_scene_data.cmd_type = REQUEST_SCENE_CONTROL;
req_scene_data.scene_control.scene_id_length = strlen(test_scene_id);
memcpy(req_scene_data.scene_control.scene_id, test_scene_id, req_scene_data.scene_control.scene_id_length);
tuya_ble_feature_scene_request(&req_scene_data);

在 tuya_ble_protocol_callback.c 中 回调事件处理函数 下添加如下代码，即可实现基本功能。如果测试功能 TUYA_SDK_TEST 是开启的，这些代码已经启用了。代码中涉及到的每个 API 在接口说明中都有涉及。

#include "tuya_ble_scene.h"

STATIC VOID_T tuya_ble_protocol_callback(tuya_ble_cb_evt_param_t* event)
{
    switch(event->evt) {
        //...

#if (TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE != 0) && (TUYA_BLE_FEATURE_SCENE_ENABLE != 0)
        case TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE: {
            TAL_PR_INFO("received scene request response result code=[%d], err_code=[%d] sub_cmd=[%d]", \
                                event->scene_req_response_data.status, \
                                event->scene_req_response_data.err_code, \
                                event->scene_req_response_data.scene_cmd);
        } break;

        case TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED: {
            // scene_data
            TAL_PR_INFO("received scene data result, status=[%d] err_code=[%d] need_update=[%d] check_code=[0x%X]", \
                                event->scene_data_received_data.status, \
                                event->scene_data_received_data.err_code, \
                                event->scene_data_received_data.need_update, \
                                event->scene_data_received_data.check_code);

            if (event->scene_data_received_data.status == 0 && event->scene_data_received_data.need_update) {
                // Todo ... update scene check code.
                if (event->scene_data_received_data.data_len != 0) {
                    UINT8_T *iot_scene_object;
                    UINT16_T scene_id_len, scene_name_len;
                    UINT8_T object_len = 0;

                    for (;;) {
                        iot_scene_object = (UINT8_T *)(event->scene_data_received_data.p_data + object_len);

                        scene_id_len = iot_scene_object[0];
                        scene_name_len = (iot_scene_object[1+scene_id_len] << 8) + iot_scene_object[2+scene_id_len];

                        TAL_PR_HEXDUMP_INFO("scene id :", &iot_scene_object[1], scene_id_len);
                        TAL_PR_HEXDUMP_INFO("scene name unicode :", &iot_scene_object[3+scene_id_len], scene_name_len);

                        object_len += (3 + scene_id_len + scene_name_len);
                        if (object_len >= event->scene_data_received_data.data_len)
                            break;
                    }
                }
            }
        } break;

        case TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED: {
            TAL_PR_INFO("received scene ctrl result, status=[%d] err_code=[%d]", \
                                event->scene_ctrl_received_data.status, \
                                event->scene_ctrl_received_data.err_code);
            TAL_PR_HEXDUMP_INFO("scene ctrl id:", event->scene_ctrl_received_data.p_scene_id, \
                                event->scene_ctrl_received_data.scene_id_len);
        } break;
#endif // (TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE != 0) && (TUYA_BLE_FEATURE_SCENE_ENABLE != 0)

        //...
    }
}

功能测试

前置条件

您已经下载了涂鸦智能 App。
确认您的设备已完成配网。
在 App 上已创建好一键执行场景，操作详见创建一键执行。

创建场景-一键执行

打开涂鸦智能 App。
单击底部的场景，选择 创建智能场景 > 一键执行。
选择执行条件，并保存。
查看创建一键执行的结果。

操作步骤

通过上位机（模拟实际产品）和手机 App 进行数据交互，如下图所示：

请求场景数据

请求场景控制

上位机使用的相关问题，请访问 Logic 上位机使用指南。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-蓝牙设备开发版块进行沟通咨询。

咨询前建议首先查阅官方资料或参考已有帖子，并认真阅读发帖规范。

上一篇功耗管理

下一篇本地定时