Calling and Leaving Messages

Calling and leaving messages are two basic features available on devices with a call button.

• Calling refers to a range of responses when the call button on the doorbell is pressed. The incoming call screen is displayed on the mobile app. The user can accept or decline the call.
• Leaving message enables the doorbell to automatically play a voice message to prompt the visitor to leave a message if a call is missed or declined.

Features

How calling and leaving messages work:

```mermaid graph TD a("An incoming call") --> b("Answered on the app?") -- --> c("Hang up") --> d("End") b -- --> f("Play recorded voice message") --> g("Whether to process") --> h("Leave a message") -- --> d("End") g -- --> d("End") ```

The incoming call screen on the mobile app:

How it works

Calling

• The Wi-Fi chip receives an interrupt of call button press and then wakes up the microcontroller chip.
• The microcontroller system and applications start.
• The Wi-Fi chip sends the button press message that will be processed and then forwarded across the applications on the microcontroller.
• The doorbell will play a chime, capture an image, run a lighting effect, and push the event.

The process of triggering the doorbell.

```mermaid sequenceDiagram participant Device participant Tuya Cloud participant Third-Party Cloud participant App Device ->> Device: Visitor presses the call button. Device ->> Tuya Cloud: MQTT43 Tuya Cloud ->> App: Forward App ->> App: Display incoming call screen. Device ->> Third-Party Cloud: Media information (image) Device ->> Tuya Cloud: DP 153=4 (212) Tuya Cloud ->> App: Forward App ->> App: Display incoming call and image. App ->> App: Display alert in message center. App ->> Third-Party Cloud: Get media information. ```

Accept the call

• After the user accepts the call, the mobile app sends a message to the doorbell over MQTT.
• On receiving the message, the doorbell controls the lighting effect, push events, and record flags in app_user_event. Meanwhile, a timer is started in app_user_doorbell to end the call when a timeout happens.

Leaving messages

• When the visitor presses the call button for the first time, a timer is started in app_user_doorbell. If a call is not answered or declined, the doorbell waits for a time period and then plays a voice message in the app_user_event component.
• The visitor should press the call button again within the specified period after hearing the prompt.
• A timer is started in app_user_doorbell. Video message recording is started in app_user_event.
• When the timer expires, app_user_doorbell starts a thread to monitor message upload, which will end after leaving messages times out.

Development guide

Components

• app_user_doorbell
• app_user_event
• app_main
• common_xxx

Time parameters for leaving messages

• If a call is not answered or declined within 25 seconds, the doorbell will play a voice message.

• After hearing the prompt, the visitor can leave a message by pressing the call button within 15 seconds. The time limited for leaving messages is 10 seconds. After the timeout has elapsed, the doorbell enters sleep mode.

  You can modify the time parameters in ability.config.

  TY_DOORBELL_ENABLE=1              // Enable doorbell.
  TY_DOORBELL_LEAVEMSG_ENABLE=1     // Enable leaving messages.
  TY_DOORBELL_CALL_TIMEOUT=25       // No answer timeout
  TY_DOORBELL_MSG_TIMEOUT=10        // Leaving message timeout
  

• The lighting effect and voice message can be modified in the configuration file.

  You can modify the actions, such as playing voice messages, in actions.config. For example, the configurations in the following snippet will be converted into macro definitions, mapped to ty_status_action_map.c.in, and compiled into the program.

  The configurable actions are listed in actions.config. The value on the right of the equal sign is editable. You can find its definition in the header file of each component.

  E_TY_DOORBELL_FIRST_PRESS_ACTION_1=TY_LED_RING_BLINK_BREATH_TWICE
  E_TY_DOORBELL_FIRST_PRESS_ACTION_2=ACTION_FILE_DOORBELL
  E_TY_DOORBELL_NOT_FIRST_PRESS_ACTION_1=TY_LED_RING_BLINK_BREATH_TWICE
  E_TY_DOORBELL_NOT_FIRST_PRESS_ACTION_2=ACTION_FILE_DOORBELL
  E_TY_DOORBELL_LEAVE_MSG_ACTION_1=TY_LED_RING_BLINK_BREATH_START
  E_TY_DOORBELL_NOT_LEAVE_MSG_ACTION_1=TY_LED_RING_BLINK_BREATH_STOP
  E_TY_DOORBELL_LEAVE_MSG_END_ACTION_1=TY_LED_RING_BLINK_BREATH_STOP
  E_TY_DOORBELL_CALL_ACCEPT_ACTION_1=TY_LED_RING_BLINK_BREATH_STOP
  E_TY_DOORBELL_CALL_NOT_ACCEPT_ACTION_2=ACTION_FILE_MSG
  E_TY_DOORBELL_CALL_END_ACTION_1=TY_LED_RING_BLINK_BREATH_STOP
  E_TY_DOORBELL_UNREGISTER_PRESS_ACTION_2=ACTION_FILE_DOORBELL
  

Data structure

This section describes the data structure in app_user_doorbell.

The data structure of initialization parameters.

typedef struct
{
    unsigned int CallTimeout;       //Call timeout
    unsigned int LeaveMsgTimeout;   //Time limited for leaving a message
    unsigned int NotifyMsgTimeout; //The wait time for leaving a message
    unsigned int isLeaveMsg;        //Whether to enable leaving messages.
}TY_DOORBELL_PARAM_S;

API description

This section describes the APIs in app_user_doorbell.

Initialize doorbell component

This API responds immediately. Responses to doorbell services are executed asynchronously.

/**
* @ Doorbell service initialization
*
* @param[in] TY_DOORBELL_PARAM_S
* @return OPERATE_RET 0 for success. Other values for errors. See tuya error code for details.
* @warning:
*/
int ty_user_doorbell_start(TY_DOORBELL_PARAM_S *param);

Deinitialize doorbell component

/**
* @ Doorbell service stop
*
* @return OPERATE_RET 0 for success. Other values for errors. See tuya error code for details.
* @warning:
*/
int ty_user_doorbell_stop();

Update doorbell service parameters

/**
* @ Update param
*
* @param[in] TY_DOORBELL_PARAM_S
* @return OPERATE_RET 0 for success. Other values for errors. See tuya error code for details.
* @warning:
*/
int ty_user_doorbell_update_param(TY_DOORBELL_PARAM_S *param);

Things to note

The audio file is stored in resource/audio. Take care of the audio format if you want to change the file.

FAQs

Why doesn’t the mobile app respond to doorbell press?

• Check if the doorbell is connected properly.
• Check if the DPs related to doorbell calling are configured, typically DP 154. You can log in to the Tuya Developer Platform to check DP configuration.