门铃业务

门铃与其他 IPC 产品相比，增加了若干功能，如门铃按键按下后推送提醒、同时呼叫 App 并在 App 端弹窗进行视频通话等功能。

功能描述

按键消息推送

检测到门铃按键按下后，调用 SDK 中相关 API 实现推送门铃按键消息，并在 App 的消息中心展示。

呼叫

检测到门铃按键按下后，调用 SDK 中相关 API 可实现门铃设备呼叫 App，在 App 的弹窗中进行预览实时画面并可进行对话。

留言

一般是在设备端呼叫 App。如 App 未应答，设备可通过调用相关 API，进行留言的录制并上传，同时可在 App 端查看该留言。

头文件

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

API 说明

门铃初始化

初始化时需要设置事件接收回调，用于接收 App 端发送的 接听、停止 和 心跳 消息。上层应用可根据此消息进行业务和功能设计。

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

门铃事件推送

门铃事件推送与其他事件（如移动侦测等）生成和调用流程相同，可参考 事件告警。
门铃事件类型：

• 使用 tuya_ipc_notify_alarm，则事件类型可使用 NOTIFICATION_NAME_E 中的 NOTIFICATION_NAME_DOORBELL。
• 使用 tuya_ipc_trigger_alarm_without_event，则事件类型可使用 TUYA_ALARM_TYPE_E 中的 E_ALARM_DOORBELL。

呼叫

/**
 * @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 Byte
 * @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 ：
  • 通常选择 DOORBELL_AC ，会向云端发送特定协议，之后云端会向 App 端转发此协议，App 出现弹窗呼叫界面且会展示设备的实时画面。
  • 如选 DOORBELL_NORMAL，则 App 弹窗呼叫界面中只能展示抓拍的图片。
• snap_buffer：抓拍图片的首地址。
• snap_size：图片长度。
• type：可选 NOTIFICATION_CONTENT_JPEG 。

停止呼叫

调用此接口后设备主动停止呼叫 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);

留言

留言功能较为独立，需要单独初始化操作。

• 留言初始化：用于初始化内部变量、工作线程以及传递留言时长。

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

• 开始留言

  调用后会记录指定时长内的录音、录像，在满足终止条件（留言时长）后，自动上传录像片段。其中留言视频数据源自全局的音视频 ringbuf。

  • extra_data：留言封面图。
  • data_len：封面图长度。

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

• 留言数据生成状态

  调用此接口可以获取当前留言的生成状态。返回 TRUE 表示留言正在生成，返回 FALSE 表示留言已生成并上传或处于空闲状态。

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

使用方法

初始化

开发门铃产品时，推荐的初始化顺序如下所示：

设备呼叫 App

参照上述 API 说明，要实现门铃设备按键后呼叫 App 的功能，推荐的调用顺序如下：

调用接口后，会在 App 中弹出实时预览画面，并在下方展示 接听 与 挂断 两个按钮。

留言生成与上传

呼叫产生后，设备需要依据 App 端的操作进行响应。
推荐的处理流程是，在 App 呼叫界面出现时直接点击 挂断 按钮或超时未选择(超时逻辑取决于产品需求)，设备端会提示进行留言操作。

逻辑顺序如下所示：

挂断 信号的接收可通过 tuya_ipc_doorbell_init 注册的回调接收。
留言的原理是，从全局的 ringbuf 中取得音视频帧数据，之后在内存中缓存。达到上传条件后，将缓存内容上传至云端。上传条件由 tuya_ipc_video_msg_init 传入。