Scene Control

Last Updated on : 2024-02-28 03:03:58download

This topic describes how scene control works on Bluetooth devices.

Overview

Concepts

Scene control refers to predefined operations created in the Tuya Smart app, that is, tap-to-run scenes. These operations can be applied to the devices, thereby the specified scenes are triggered and controlled.

This design allows users to trigger and control scene features directly through the devices in a more convenient, smart, and simple way, without opening the mobile app.

API description

Synchronize the created tap-to-run scenes to the devices, and then control, trigger, and run the specified scenes directly in the connected devices. Use a watch device to demonstrate specific processes.

Set up a tap-to-run scene on the app.
After the device is connected to the app, the device triggers a request for scene data. The app gets the data from the cloud and synchronizes it to the device.
After getting the data, the watch device shows the scene name and scene.
Tap a scene in the watch to send scene control commands to the app.
The app calls APIs to trigger the scenes in the cloud, thus achieving scene control.

Data structure

tuya_ble_request_scene_t

Request the scene data, including scene data and control.

/**@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

In response to the request for scene data, send a callback to the application. The specific callback event is 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

Get the result of the request for scene list, and send a callback to the application. The specific callback event is 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

Get the result of the request for scene control, and send a callback to the application. The specific callback event is 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;

API description

Macro configuration dependencies

#define TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE 1

#define TUYA_BLE_FEATURE_SCENE_ENABLE 1

Request scene data/control

API description

tuya_ble_status_t tuya_ble_feature_scene_request(tuya_ble_request_scene_t *req_data)

Parameters

Parameters	Description
req_data	Request scene control data. Request the list data and implement scene control. For more information, see the definition of the data structure tuya_ble_request_scene_t.

Callback event — response to the request

TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE

Callback event	TUYA_BLE_CB_EVT_SCENE_REQ_RESPONSE
Data structure	The response data of the request for scenes returned by the mobile app. For more information, see the definition of the data structure tuya_ble_scene_req_response_t.
Description	After the device calls the scene request API, the mobile app responds to the request.

Callback event — scene data

TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED

Callback event	TUYA_BLE_CB_EVT_SCENE_DATA_RECEIVED
Data structure	The list data returned by requesting the scene. For more information, see the definition of the data structure tuya_ble_scene_data_received_data_t. p_data stores all returned scene data. The following table shows the format of each scene data:
Description	The mobile app requests tap-to-run scene data from the cloud and returns it to the SDK, and the SDK sends the events and data to the application layer through a callback.

Definition of scene data format:

Length of scene ID	Scene ID	Length of scene name	Scene name	…	Length of scene ID	Scene ID	Length of scene name	Scene name
1 byte	n byte(s)	2 bytes	m byte(s)	…	1 byte	n byte(s)	2 bytes	m byte(s)

Callback event — scene control

TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED

Callback event	TUYA_BLE_CB_EVT_SCENE_CTRL_RESULT_RECEIVED
Data structure	The response data of the request for scene control. For more information, see the definition of the data structure tuya_ble_scene_ctrl_received_data_t.
Description	The result of scene control. The SDK sends the events and data to the application layer through a callback.

How to use

Communication process

Code development

Enable the scene control component in app_config.h and enable the corresponding macro configuration. Scene control depends on the common capabilities of the IoT channel, which also needs to be enabled.

#define TUYA_BLE_FEATURE_IOT_CHANNEL_ENABLE 1

#define TUYA_BLE_FEATURE_SCENE_ENABLE 1

Add code to request the scene data/control. This is just an example.

/**
* 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);

Add the following snippet in the callback event handler function of tuya_ble_protocol_callback.c to implement the basic functionality. If the test function TUYA_SDK_TEST is enabled, this code is active. Each API used in the code is described in the API documentation.

#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.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)

        //...
    }
}

Functional testing

Prerequisites

You have installed the Tuya Smart app on your phone.
Your device has been paired.
Set up a tap-to-run scene on the mobile app. For more information, see Create a tap-to-run scene.

Create a tap-to-run scene

Open the Tuya Smart app.
Tap Scene at the bottom, and choose Create Scene > Launch Tap-to-Run.
Set the trigger conditions and save.
View the results of creating a tap-to-run scene.

Procedure

Communicate with the mobile app using a host that simulates a real device.

Request the scene data

Request scene control

If you have any problems with host usage, see Logic Host User Guide.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.

Prev DocPower Management

Next DocLocal Schedule