Security Features

This topic describes the APIs used to implement the security features.

Structs

TY_HOME_SECURITY_OPS_CB_S

typedef struct {
    VOID (*alarm_cb)(INT_T volume, UINT_T time);
    VOID (*alarm_mute_cb)(INT_T mute_on);
    VOID (*alarm_cancel_cb)(VOID);
    VOID (*disarmed_cb)(INT_T volume);
    VOID (*away_and_armed_cb)(INT_T volume);
    VOID (*home_and_armed_cb)(INT_T volume);
    VOID (*arm_ignore_cb)(INT_T volume);
    VOID (*arm_countdown_cb)(INT_T volume, UINT_T countdown_time);
    VOID (*alarm_countdown_cb)(INT_T volume, UINT_T countdown_time);
    VOID (*alarm_door_cb)(INT_T volume);
    VOID (*alarm_devname_cb)(INT_T volume, CHAR_T *name);
} TY_HOME_SECURITY_OPS_CB_S;

Functional specification

The security operations callbacks.

Member description

Member	Description
alarm_cb	The callback to invoke when an alarm is triggered. For more information, see alarm_cb.
alarm_mute_cb	The callback to invoke when the alarm sound is muted. For more information, see alarm_mute_cb.
alarm_cancel_cb	The callback to invoke when an alarm is canceled. For more information, see alarm_cancel_cb.
disarmed_cb	The callback to invoke when the system is disarmed. For more information, see disarmed_cb.
away_and_armed_cb	The callback to invoke when the arm away mode is set. For more information, see away_and_armed_cb.
home_and_armed_cb	The callback to invoke when the arm stay mode is set. For more information, see home_and_armed_cb.
arm_ignore_cb	The callback to invoke when an alarm is ignored as users are arming the system. For more information, see arm_ignore_cb.
arm_countdown_cb	The callback to invoke when the arm delay is started. For more information, see arm_countdown_cb.
alarm_countdown_cb	The callback to invoke when the alarm delay is started. For more information, see alarm_countdown_cb.
alarm_door_cb	The callback to invoke when the door sensor is triggered. For more information, see alarm_door_cb.
alarm_devname_cb	The callback for the name of the device that issues an alarm message. For more information, see alarm_devname_cb.

TY_GW_HOME_SECURITY_APP_CBS_S

typedef struct {
    GW_OFFLINE_DP_SAVE gw_offline_dp_save_cb;
    GW_HOME_SECURITY_IF_CB gw_home_security_if_cb;
    GW_HOME_SECURITY_ALARM_DEV_CB gw_home_security_alarm_dev_cb;
    GW_HOME_SECURITY_ALARM_DEV_CB gw_home_security_alarm_env_dev_cb;
    GW_HOME_SECURITY_ALARM_DELAY_STATUS_CB gw_home_security_alarm_delay_status_cb;
    GW_HOME_SECURITY_EVENT_CB gw_home_security_event_cb;
    GW_HOME_SECURITY_CANCEL_ALARM_CB gw_home_security_cancel_alarm;
    GW_HOME_SECURITY_ALARM_DEV_NEW_CB gw_home_security_alarm_dev_new_cb;
	GW_HOME_SECURITY_ENTER_ALARM_CB gw_home_security_enter_alarm_cb;
} TY_GW_HOME_SECURITY_APP_CBS_S;

Functional specification

The security service callbacks.

Member description

Member	Description
gw_offline_dp_save_cb	The callback to invoke when data point (DP) information is saved offline. For more information, see gw_offline_dp_save_cb.
gw_home_security_if_cb	The callback to invoke when the security mode is changed. For more information, see gw_home_security_if_cb.
gw_home_security_alarm_dev_cb	Deprecated. The replacement is gw_home_security_alarm_dev_new_cb.
gw_home_security_alarm_env_dev_cb	Deprecated. The replacement is gw_home_security_alarm_dev_new_cb.
gw_home_security_alarm_delay_status_cb	The callback to invoke when the status of the alarm delay changes. For more information, see gw_home_security_alarm_delay_status_cb.
gw_home_security_event_cb	A callback to invoke when a security event occurs. For more information, see gw_home_security_event_cb.
gw_home_security_cancel_alarm	The callback to invoke when an alarm is canceled. For more information, see gw_home_security_cancel_alarm.
gw_home_security_alarm_dev_new_cb	The callback for processing the DP data of a security device. For more information, see gw_home_security_alarm_dev_new_cb.
gw_home_security_enter_alarm_cb	A callback to invoke when an alarm is triggered. For more information, see gw_home_security_enter_alarm_cb.

API reference

tuya_iot_gw_home_security_reg_ops_cb

OPERATE_RET tuya_iot_gw_home_security_reg_ops_cb(TY_HOME_SECURITY_OPS_CB_S *cbs)

Functional description

Registers the security operations callbacks.

Parameter description

Parameter name	Description
cbs	The operation callbacks. For more information, see TY_HOME_SECURITY_OPS_CB_S.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_gw_home_security_start

OPERATE_RET tuya_iot_gw_home_security_start(TY_GW_HOME_SECURITY_APP_CBS_S *iot_alarm_cbs);

Functional description

Initializes the security services.

Parameter description

Parameter name	Description
cbs	The security services callbacks. For more information, see TY_GW_HOME_SECURITY_APP_CBS_S. If cbs is NULL, it indicates the SDK processes the events. If cbs is not NULL, it indicates you implement the event handler.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

Callback functions

alarm_cb

VOID (*alarm_cb)(INT_T volume,
                 UINT_T time)

Functional description

The callback to invoke when an alarm is triggered.

Parameter description

Parameter name	Description
volume	The volume of the alarm sound.
time	The alarm delay time.

Return value

Return value	Description
VOID	/

alarm_mute_cb

VOID (*alarm_mute_cb)(INT_T mute_on)

Functional description

The callback to invoke when the alarm sound is muted.

Parameter description

Parameter name	Description
mute_on	0: Unmute. Other values: Mute.

Return value

Return value	Description
VOID	/

alarm_cancel_cb

VOID (*alarm_cancel_cb)(VOID)

Functional description

The callback to invoke when an alarm is canceled.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
VOID	/

disarmed_cb

VOID (*disarmed_cb)(INT_T volume)

Functional description

The callback to invoke when the system is disarmed.

Parameter description

Parameter name	Description
volume	The volume of audio play.

Return value

Return value	Description
VOID	/

away_and_armed_cb

VOID (*away_and_armed_cb)(INT_T volume)

Functional description

The callback to invoke when the arm away mode is set.

Parameter description

Parameter name	Description
volume	The volume of audio play.

Return value

Return value	Description
VOID	/

home_and_armed_cb

VOID (*home_and_armed_cb)(INT_T volume)

Functional description

The callback to invoke when the arm stay mode is set.

Parameter description

Parameter name	Description
volume	The volume of audio play.

Return value

Return value	Description
VOID	/

arm_ignore_cb

VOID (*arm_ignore_cb)(INT_T volume)

Functional description

The callback to invoke when an alarm is ignored as users are arming the system.

Parameter description

Parameter name	Description
volume	The volume of audio play.

Return value

Return value	Description
VOID	/

arm_countdown_cb

VOID (*arm_countdown_cb)(INT_T volume,
                         UINT_T countdown_time)

Functional description

The callback to invoke when the arm delay is started.

Parameter description

Parameter name	Description
volume	The volume of audio play.
countdown_time	The countdown time, in seconds.

Return value

Return value	Description
VOID	/

alarm_countdown_cb

VOID (*alarm_countdown_cb)(INT_T volume,
                           UINT_T countdown_time)

Functional description

The callback to invoke when the alarm delay is started.

Parameter description

Parameter name	Description
volume	The volume of audio play.
countdown_time	The countdown time, in seconds.

Return value

Return value	Description
VOID	/

alarm_door_cb

VOID (*alarm_door_cb)(INT_T volume)

Functional description

The callback to invoke when the door sensor is triggered.

Parameter description

Parameter name	Description
volume	The volume of audio play.

Return value

Return value	Description
VOID	/

alarm_devname_cb

VOID (*alarm_devname_cb)(INT_T volume,
                         CHAR_T *name)

Functional description

The callback for the name of the device that issues an alarm message. The device must have the DP 103.

Parameter description

Parameter name	Description
volume	The volume of audio play.
name	The device name.

Return value

Return value	Description
VOID	/

gw_offline_dp_save_cb

typedef OPERATE_RET (*GW_OFFLINE_DP_SAVE)(IN CONST CHAR_T *dev_id,
                                          IN CONST TY_OBJ_DP_S *dp_data,
                                          IN CONST UINT_T cnt)

Functional description

The callback to invoke when data point (DP) information is saved offline. This callback is to invoke when the gateway is offline. In this callback, you need to implement DP data storage so that this cached DP data can be reported after the gateway is online.

Parameter description

Parameter name	Description
dev_id	The device ID.
dp_data	The array of DPs of object type.
cnt	The length of the array of DPs of the object type.

Return value

Return value	Description
VOID	/

gw_home_security_if_cb

typedef VOID (*GW_HOME_SECURITY_IF_CB)(IN CONST CHAR_T *mode_str,
                                       IN CONST UINT_T time,
                                       BOOL_T is_sound)

Functional description

The callback to invoke when the security mode is changed.

Parameter description

Parameter name	Description
mode_str	The security modes: 0: Disarm. 1: Arm stay. 2: Arm away.
time	The countdown time, in seconds.
is_sound	TRUE: Unmute. FALSE: Mute.

Return value

Return value	Description
VOID	/

gw_home_security_alarm_delay_status_cb

typedef VOID (*GW_HOME_SECURITY_ALARM_DELAY_STATUS_CB)(IN ALARM_DELAY_STATE alarm_status)

Functional description

The callback to invoke when the status of the alarm delay changes.

Parameter description

Parameter name	Description
alarm_status	The status of alarm delay: ALARM_DELAY_DONOT_CREATE: An alarm delay is not created. ALARM_DELAY_COUNTDOWN: An alarm delay is ongoing. ALARM_DELAY_END: An alarm delay is finished.

Return value

Return value	Description
VOID	/

gw_home_security_event_cb

typedef VOID (*GW_HOME_SECURITY_EVENT_CB)(IN SECURITY_EVENT_E security_event_status,
                                          PVOID_T data);

Functional description

A callback to invoke when a security event occurs.

Parameter description

Parameter name	Description
security_event_status	DISARMED_EVENT: The system is disarmed. ARMED_EVENT: The system is armed away or stay. BYPASS_EVNET: An alarm is ignored. WARING_COUNTDOWN: An alarm delay is ongoing.
data	When security_event_status is WARING_COUNTDOWN, the type of data is UINT_T, indicating the countdown time. When security_event_status is not WARING_COUNTDOWN, the data is NULL.

Return value

Return value	Description
VOID	/

gw_home_security_cancel_alarm

typedef VOID (*GW_HOME_SECURITY_CANCEL_ALARM_CB)(VOID);

Functional description

The callback to invoke when an alarm is canceled.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
VOID	/

gw_home_security_alarm_dev_new_cb

typedef VOID (*GW_HOME_SECURITY_ALARM_DEV_NEW_CB)(IN CONST CHAR_T *cid,  
                                                  IN ty_cJSON *dp_inf,
                                                  SECURITY_DEV_TYPE_E dev_type);

Functional description

The callback for processing the DP data of a security device.

Parameter description

Parameter name	Description
cid	The device ID.
dp_inf	The DP information, in JSON format. If dp_inf is string, it indicates the DP ID. The DP value can vary depending on type, which follows the rules below: When the type of dp_inf is cJSON_True, the value of dp_inf is type. When the type of dp_inf is cJSON_Number, the value of dp_inf is valueint. When the type of dp_inf is cJSON_True, the value of dp_inf is valuestring.
dev_type	The types of device: NO_ENV_DEV: Represents non-environmental sensing devices, such as door sensors and PIR sensors. ENV_DEV: Represents environmental sensing devices, such as gas detectors and smoke detectors.

Return value

Return value	Description
VOID	/

gw_home_security_enter_alarm_cb

typedef VOID (*GW_HOME_SECURITY_ENTER_ALARM_CB)(IN BOOL_T alarm_status,
                                                IN CHAR_T *alarm_info);

Functional description

A callback to invoke when an alarm is triggered.

Parameter description

Parameter name	Description
alarm_status	The alarm status.
alarm_info	The content of the alarm message.

Return value

Return value	Description
VOID	/