Event Alarm

The camera reports alarm events such as motion detection, human detection, pet detection, and doorbell calls to the cloud, where they are displayed in the app message center. Event alarms support image and video messages, as well as incoming call pop-up notifications.

Development guide

Components

svc_api_ipc

API description

Solution 1: Single-image reporting

Report alarms using Data point (DP) 212. If the event type is listed in the NOTIFICATION_NAME_E enum (in the file: tuya_ipc_notify.h), use the following interface to report the alarm.

/**
 * @brief Send an editable alarm to Tuya cloud and app.
 *
 * @param[in] snap_buffer: Address of the current snapshot buffer.
 * @param[in] snap_size: Size of the snapshot in bytes.
 * @param[in] name: Editable event type. NOTIFICATION_NAME_E.
 * @param[in] is_notify: Whether to send to message center. TRUE: Send; False: Not send.
 *
 * @return OPRT_OK on success. For other errors, 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);

If the event type is not listed in NOTIFICATION_NAME_E, check if it is in the TUYA_ALARM_TYPE_E enum (in the file: tuya_ipc_event.h). If so, you can report them using the following interface.

/**
 * @brief  Notify an alarm not based on event.
 *
 * @param alarm: TUYA_ALARM_T
 *
 * @return  OPRT_OK on success. For other errors, please refer to tuya_error_code.h.
 */
OPERATE_RET tuya_ipc_trigger_alarm_without_event(IN TUYA_ALARM_T *alarm);

Data structure

The data structure for alarm details:

typedef struct {
    INT_T type;                         ///< Alarm type
    TUYA_ALARM_BITMAP_T wait_for;       ///< Depends on other alarms.
    INT_T is_notify;                    ///< Notify the cloud.
    TIME_T trigger_time;
    TIME_T upload_time;                 ///< 0 means upload immediately; -1 means wait until the event ends.
    BOOL_T valid;                       ///< 1 means it needs to be handled; 0 means it has been handled. User should set 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 appended to the upload payload in JSON format (e.g., "aaa": 3). Set to NULL if not needed.
    CHAR_T *pic_buf;
    INT_T pic_size;
    TUYA_ALARM_TEXT_T *context;        ///< Text alarm information, can be NULL.
    INT_T context_cnt;                  ///< TUYA_ALARM_TEXT_T count, can be 0.
    NOTIFICATION_UNIT_T *media;         ///< Media information, 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 alarm.

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 non-image reporting:

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.pic_buf = ; // The address of the image buffer. Set to NULL if not required.
alarm_info.context_cnt = ; // The address of the image buffer. Set to 0 if not required.
alarm_info.media = NULL;
alarm_info.media_cnt = 0;

Solution 2: Multimodal message reporting

If an alarm event contains multiple images and audio (the relevant advanced capabilities must be enabled on the PID), please use the following interfaces to report the data sequentially.

Initialization

The initialization interface only needs to be called once.

/**
 * @brief  Initialization of multiple images/audio's reporting.
 *
 * @return   OPRT_OK on success. For other errors, please refer to tuya_error_code.h.
 */
OPERATE_RET tuya_ipc_event_multi_info_alarm_init(VOID);

Report the first image/audio

This interface supports reporting images or audio separately or simultaneously.

/**
 * @brief  Start a multi-info alarm.
 *
 * @param[in] alarm: Refer to TUYA_ALARM_MUTI_INFO_T.
 *
 * @param[out] max_pic_count: Maximum number of pictures supported for upload.
 *
 * @param[out] max_audio_count: Maximum number of audio files supported for upload.
 *
 * @param[out] status: Upload status. Refer to TUYA_MULTI_INFO_ALARM_MEDIA_STATUS_E for more information.
 *
 * @return  User handle.
 * - NULL: Failed to trigger the alarm.
 * - Other: Success. Users can use handle to upload more images or audio.
 */
TUYA_IPC_MULTI_INFO_ALARM_USER_HANDLE_T tuya_ipc_event_start_multi_info_alarm(IN TUYA_MULTI_INFO_ALARM_T *alarm, OUT UINT_T *max_pic_count, OUT UINT_T *max_audio_count, OUT TUYA_MULTI_INFO_ALARM_MEDIA_STATUS_E *status);

Report subsequent images/audio

/**
 * @brief  Append new information into a multi-info alarm .
 *
 * @param[in] handle: User handle returned by tuya_ipc_event_start_multi_info_alarm.
 *
 * @param[in] append_data: Append data. Refer to MULTI_INFO_ALARM_APPEND for more information.
 *
 * @return Upload status. Refer to TUYA_MULTI_INFO_ALARM_MEDIA_STATUS_E.
*/
TUYA_MULTI_INFO_ALARM_MEDIA_STATUS_E tuya_ipc_event_multi_info_alarm_append_data(TUYA_IPC_MULTI_INFO_ALARM_USER_HANDLE_T handle, MULTI_INFO_ALARM_APPEND *append_data);

Stop reporting

When all images have been uploaded, or if you need to end the reporting in advance, call the stop reporting interface.

/**
 * @brief  Stop a multi-info alarm.
 *
 * @warning   Start/Stop should be called in pair.
 *
 * @param[in]   handle: User handle returned by tuya_ipc_event_start_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);

FAQs

Is there a limit on the frequency of alarm reporting?

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

How do you handle this interface after disabling motion detection on the 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.

Why do you get an error when adding a new event type?

If an error is reported when adding event type XXX: [tuya_ipc_event.c] unsupport type: XXX.

If this occurs, please verify the following two items:

• Whether this event type has been successfully added to your PID.
• After adding the new event type, pair and activate the device again for the changes 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 you know if an alarm is reported successfully?

• In the log, check https for the result of delivering the image and DP 212 message.
• Go to the Tuya IoT Development Platform. Choose AI Product > Device Details, 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.