Event Alert

The camera sends alerts of events including motion, human shape, pet, and doorbell call to the cloud to get reflected in the message center on the mobile app. Event alerts support image or video message and incoming call prompt.

Development guide

Components

svc_api_ipc

API description

Solution 1

Report alerts using DP 212. If the event type is included in the NOTIFICATION_NAME_E enum (in the file: tuya_ipc_notify.h), use the following API to report the alert.

/**
 * @brief send an editable alarm to tuya cloud and APP
 *
 * @param[in] snap_buffer: address of current snapshot
 * @param[in] snap_size: size fo snapshot, in Byte
 * @param[in] name: editable event type, NOTIFICATION_NAME_E
 * @param[in] is_notify: send to message center if TRUE
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_notify_alarm(IN CONST CHAR_T *snap_buffer, IN CONST UINT_T snap_size, IN CONST NOTIFICATION_NAME_E name, IN BOOL_T is_notify);

Solution 2

If the event type is not included in the NOTIFICATION_NAME_E enum, check if it is included in the TUYA_ALARM_TYPE_E enum (in the file: tuya_ipc_event.h). If yes, you can use the following API to report the alert.

/**
 * @brief notify an alarm not base on event
 *
 * @param alarm: TUYA_ALARM_T
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_trigger_alarm_without_event(IN TUYA_ALARM_T *alarm);

Solution 3: Multi-image reporting

If an alarm event contains multiple images (the relevant advanced capability needs to be enabled on the PID), please use the following APIs in sequence to report the images.

Initialization

The initialization API only needs to be called once.

/**
 * @brief Initialization of multiple images reporting
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h 
 */
OPERATE_RET tuya_ipc_event_multi_info_alarm_init();

Report the first image

/** 
 * @brief Trigger multi-info alarm
 *
 * @param[in] alarm: TUYA_ALARM_T
 *
 * @param[out] max_info_count: Maximum supported number of uploaded info
 * 
 * @return User handle
 * - NULL: Trigger failed
 * - Other: Trigger success
*/
TUYA_IPC_MULTI_INFO_ALARM_USER_HANDLE_T tuya_ipc_event_trigger_multi_info_alarm(IN TUYA_ALARM_T *alarm, OUT UINT_T *max_info_count);

Report subsequent images

/** 
 * @brief Append new info into a multi-alarm
 *
 * @param[in] handle: User handle returned by tuya_ipc_event_trigger_multi_info_alarm
 *
 * @param[in] data: Info data
 *
 * @param[in] data_size: Data size
 *
 * @param[in] append_data_index: 1st data -> index 1
 *
 * @return Error code
 * - OPRT_OK      Success
 * - Others       Failed
*/
OPERATE_RET tuya_ipc_event_multi_info_alarm_append_data(TUYA_IPC_MULTI_INFO_ALARM_USER_HANDLE_T handle, CHAR_T *data, UINT_T data_size, UINT_T append_data_index);

Stop reporting

When all images have been uploaded, or if reporting needs to be ended in advance, the stop reporting API must be called.

/** 
 * @brief  Stop multi-info alarm
 *
 * @warning Trigger/stop should be called in pairs (similar to file operations)
 *
 * @param[in]   handle: User handle returned by tuya_ipc_event_trigger_multi_info_alarm
 * @return Error code
 * - OPRT_OK      Success
 * - Others       Failed
*/
OPERATE_RET tuya_ipc_event_stop_multi_info_alarm(TUYA_IPC_MULTI_INFO_ALARM_USER_HANDLE_T handle);

Data structure

The data struct for alert details:

typedef struct {
    INT_T type;                         ///< alarm type
    TUYA_ALARM_BITMAP_T wait_for;       ///< depends on other alarms
    INT_T is_notify;                    ///< notify to cloud
    TIME_T trigger_time;
    TIME_T upload_time;                 ///< 0 means immediately and -1 means wait until event ends
    BOOL_T valid;                       ///< 1 means needs to handle and 0 means had handled. You should set it to 1
    BOOL_T force;                       ///< force upload or not, independent with event like E_ALARM_COVER
    INT_T resource_type;                ///< refer to macro RESOURCE_XXX
    CHAR_T *extra_data;                 ///< extra data append to upload info, json format: "aaa":3. NULL if not need
    CHAR_T *pic_buf;
    INT_T pic_size;
    TUYA_ALARM_TEXT_T *context;        ///< text alarm info, can be NULL
    INT_T context_cnt;                  ///< TUYA_ALARM_TEXT_T count, can be 0
    NOTIFICATION_UNIT_T *media;         ///< media info, can be NULL
    INT_T media_cnt;                    ///< NOTIFICATION_UNIT_T count, can be 0
    CHAR_T dev_id[DEV_ID_LEN+1];        ///< device id
    INT_T dev_chan_index;              ///< device channel
} TUYA_ALARM_T;

The following sample code shows the initial values for reporting an image alert.

TUYA_ALARM_T alarm_info = {0};
alarm_info.type = ; // The event type.
alarm_info.is_notify = ; // Message center on/off state.
alarm_info.trigger_time = tal_time_get_posix(); // The current time.
alarm_info.upload_time = 0;
alarm_info.valid = 1;
alarm_info.force = 1;
alarm_info.resource_type = RESOURCE_PIC;
alarm_info.pic_buf = ; // The address of the image buffer.
alarm_info.pic_size = ; // The size of the image buffer.
alarm_info.extra_data = NULL;
alarm_info.context = NULL;
alarm_info.context_cnt = 0;
alarm_info.media = NULL;
alarm_info.media_cnt = 0;

The following sample code shows the initial values for not reporting image alert.

TUYA_ALARM_T alarm_info = {0};
alarm_info.type = ; // The event type.
alarm_info.is_notify = ; // Message center on/off state.
alarm_info.trigger_time = tal_time_get_posix(); // The current time.
alarm_info.upload_time = 0;
alarm_info.valid = 1;
alarm_info.force = 1;
alarm_info.resource_type = RESOURCE_TEXT;
alarm_info.pic_buf = NULL; 
alarm_info.pic_size = 0; 
alarm_info.extra_data = NULL; 
alarm_info.context = ; // The address of the text buffer. If not needed, set to NULL
alarm_info.context_cnt = ; // The size of the text buffer. If not needed, set to 0
alarm_info.media = NULL;
alarm_info.media_cnt = 0;

FAQs

Is there a limit on the frequency of alert reporting?

• It is recommended to report an alert for every motion event.
• Take the debounce time into consideration based on motion detection.

How do I deal with the API if motion detection is turned off on the mobile app?

• If you use tuya_ipc_notify_alarm, set is_notify to FALSE.
• If you use tuya_ipc_trigger_alarm_without_event, set is_notify in TUYA_ALARM_T to FALSE.

What event types do you support?

• Events included in NOTIFICATION_NAME_E.
• Events included in TUYA_ALARM_TYPE_E.
• To add an event type, submit a service ticket.

Added a new event type but an error message was reported.

For example, a new event type XXX was added, and an error message was reported: [tuya_ipc_event.c] unsupport type: XXX .

Please confirm the followings when such error occurs:

• Confirm whether the new event type has been successfully added to the PID.
• After adding a new event type, the device needs to be paired and activated again to take effect.

How do you secure image transfer?

• Images are encrypted and transmitted in an encrypted channel.
• Messages are transmitted in an encrypted channel.

What image file format is supported?

JPEG format.

What is the image size limit?

An image must be less than 307,120 bytes.

How do I know if an alert is reported successfully?

• In the log, check https for the result of delivering the image and DP 212 message.
• Go to the Tuya Developer Platform. Choose Product > Device Management, and enter the device ID to check if DP 212 is reported successfully.

Why doesn’t the message center display a successfully reported event?

Submit a service ticket to request a check for the configuration of the respective event type in DP 212.