Security Features

Last Updated on : 2022-11-24 09:20:27download

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 /