Doorbell Service

Compared with other IP camera products, the doorbell has several additional features. For example, push notifications when the doorbell button is pressed, call the app, and make a video call in the app dialog.

Functional description

Push notifications

After a doorbell button press is detected, APIs in the SDK are invoked to push and show a notification in the app’s message center.

Call

After a doorbell button press is detected, APIs in the SDK are invoked to enable the doorbell device to call the app, preview the live videos on the app, and have a talk.

Leave a message

Typically, the device calls the app. If the app does not answer, the device can record and upload a message by invoking APIs, and the message can be viewed on the app.

Header file

• tuya_ipc_notify.h
• tuya_ipc_video_msg.h
• tuya_ipc_doorbell.h

API description

Initialize doorbell

During initialization, you need to set the event reception callback to receive the answer, stop, and heartbeat messages sent by the app. The application can design services and functionalities based on the messages.

/**
 * @brief init ac doorbell
 *
 * @param[in] p_var: if you want to handle app's event such as answer/hangup eg., you need to set 'doorbell_event_cb'
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_ipc_doorbell_init(IN TUYA_IPC_DOORBELL_ENV_T* p_var);

Push doorbell events

Doorbell event push is generated and invoked like other events such as motion detection. For more information, see Event Alert.

Doorbell event types:

• When tuya_ipc_notify_alarm is used, the event type can use NOTIFICATION_NAME_DOORBELL in NOTIFICATION_NAME_E.
• When tuya_ipc_trigger_alarm_without_event is used, the event type can use E_ALARM_DOORBELL in TUYA_ALARM_TYPE_E.

Call

/**
 * @brief send a doorbell pressing message to tuya cloud and app
 *
 * @param[in] doorbell_type: DOORBELL_NORMAL or DOORBELL_AC
 * @param[in] snap_buffer: address of current snapshot
 * @param[in] snap_size: size of snapshot, in bytes
 * @param[in] type: snapshot file type, jpeg or png
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_door_bell_press(IN CONST DOORBELL_TYPE_E doorbell_type, IN CONST CHAR_T *snap_buffer, IN CONST UINT_T snap_size, IN CONST NOTIFICATION_CONTENT_TYPE_E type);

• doorbell_type:
  • Typically, DOORBELL_AC is selected. A specific protocol is sent to the cloud. The cloud will then forward this protocol to the app, and the app will show the call interface and live videos of the device.
  • If DOORBELL_NORMAL is selected, only captured images can be displayed on the app’s call interface.
• snap_buffer: the first address of the captured image.
• snap_size: the size of the captured image.
• type: select NOTIFICATION_CONTENT_JPEG.

Stop calling

After this API is invoked, the device proactively stops calling the app.

/**
 * @brief send a doorbell pressing stop message to tuya cloud and app (only for ac doorbell)
 *
 * @param VOID
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
OPERATE_RET tuya_ipc_door_bell_press_stop(VOID);

Leave a message

The message feature is relatively independent and requires separate initialization operations.

• Message initialization: Initialize internal variables, working threads, and message duration.

  /**
  * @brief initialize video msg leaving, which will malloc all needed memory after this
  *
  * @param[in] type: msg type(audio or video)
  * @param[in] msg_duration: duration of msg(the video longgest duration is 10 seconds, audio:15 seconds)
  *
  * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
  */
  OPERATE_RET tuya_ipc_video_msg_init(IN MESSAGE_E type, IN INT_T msg_duration);
  

• Start leaving a message

  After this API is invoked, the audio and video recordings within the specified duration are recorded, and the video clips are automatically uploaded after the termination condition (message duration) is met. Video data in the message comes from the global audio and video ring buffer.

  • extra_data: the cover image of the specified message.
  • data_len: the data length of the specified cover image.

  /**
  * @brief leave a video msg from now.
  *
  * @param[in] extra_data: extra data
  * @param[in] data_len: extra data length
  *
  * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
  */
  OPERATE_RET tuya_ipc_leave_video_msg(IN CHAR_T *extra_data, IN INT_T data_len);
  

• Generation status of message data

  Invoke this API to get the generation status of the current message. Return values:

  • TRUE: the message is being generated.
  • FALSE: the message has been generated and uploaded or is in an idle state.

  /**
  * @brief get video msg status
  *
  * @param VOID
  *
  * @return TRUE/FALSE
  */
  BOOL_T tuya_ipc_video_msg_status_is_busy(VOID);ta_len);
  

How it works

Initialization

The following figure shows the recommended initialization sequence when developing a doorbell product.

Device calls the app

Referring to the above API description, the following figure shows the recommended invocation sequence to make the doorbell device call the app after the doorbell button is pressed.

After this API is called, a live preview screen will appear on the app, with the Answer and Hang Up buttons at the bottom.

Generate and upload messages

After a call is made, the device responds based on app operations.
The recommended process is like this: When a call interface appears on the app, if the user taps the Hang Up button or does not select any button after the timeout (the timeout logic depends on product requirements), the device will prompt the caller to leave a message.

The following figure shows the interaction logic.

The hang-up signal can be received through the callback registered by tuya_ipc_doorbell_init.
The principle of the message feature is to retrieve audio and video frame data from the global ring buffer and then cache it in memory. Once the upload conditions are met, the cached content is uploaded to the cloud. The upload conditions are passed through tuya_ipc_video_msg_init.