Heartbeat Mechanism

A heartbeat is a type of communication packets that are sent between nodes to monitor the health of the nodes and network interfaces. This topic describes how to implement heartbeat checks for sub-devices.

Description

Heartbeat mechanism enables the SDK to check if connections with a sub-device are down or alive. There are two options to implement heartbeat checks:

• Option 1: The gateway regularly sends a ping packet to sub-devices in a manner such as reading the version number of the sub-device.
• Option 2: The sub-device proactively reports data to the gateway regularly, such as its version number.

How to

The SDK has implemented the heartbeat mechanism with option 1. When the heartbeat timeout expires, the SDK notifies the application of checking connections with the sub-device. The application calls tuya_iot_fresh_dev_hb to refresh the heartbeat status on receiving any messages from the sub-device.

Data structure

/**
 * @brief sub-device management callback
 */
typedef struct __ty_gw_subdev_mgr_cbs_s {
    GW_PERMIT_ADD_DEV_CB                dev_add;            // permit joining callback, see GW_PERMIT_ADD_DEV_CB
    GW_DEV_DEL_CB                       dev_del;            // remove callback, see GW_DEV_DEL_CB
    DEV_RESET_IFM_CB                    dev_reset;          // reset callback, see DEV_RESET_IFM_CB
    GW_BIND_DEV_INFORM_CB               dev_bind;           // bind result callback, see GW_BIND_DEV_INFORM_CB

    DEV_OBJ_DP_CMD_CB                   dp_cmd_obj;         // obj DP command, see DEV_OBJ_DP_CMD_CB
    DEV_RAW_DP_CMD_CB                   dp_cmd_raw;         // raw DP command, see DEV_RAW_DP_CMD_CB
    DEV_DP_QUERY_CB                     dp_query;           // DP query, see DEV_DP_QUERY_CB

    DEV_HEARTBEAT_SEND_CB               dev_hb;             // heartbeat query callback, see DEV_HEARTBEAT_SEND_CB
    DEV_UG_INFORM_CB                    dev_upgrade;        // upgrade callback, see DEV_UG_INFORM_CB
    GW_DEV_WAKEUP_CB                    dev_wakeup;         // low power device wakeup callback, see GW_DEV_WAKEUP_CB
    GW_DEV_GRP_INFM_CB                  dev_grp_info;       // group control callback, see GW_DEV_GRP_INFM_CB
    GW_DEV_SCENE_INFM_CB                dev_sce_info;       // scene control callback, see GW_DEV_SCENE_INFM_CB

    GW_DEV_SIGMESH_TOPO_UPDAET_CB       bt_topo_update;     // Bluetooth LE device added callback, see GW_DEV_SIGMESH_TOPO_UPDAET_CB
    GW_DEV_SIGMESH_DEV_CACHE_DEL_CB     bt_cache_del;       // Bluetooth LE device removed callback, see GW_DEV_SIGMESH_DEV_CACHE_DEL_CB
    GW_DEV_SIGMESH_CONN_CB              bt_conn;            // Bluetooth LE device event callback, see GW_DEV_SIGMESH_CONN_CB

    DEV_ONLINE_STAT_SEND_CB             dev_online;         // online state changed callback, see DEV_ONLINE_STAT_SEND_CB
}TY_GW_SUBDEV_MGR_CBS_S;

API description

Refresh the heartbeat

/**
 * @brief gateway receives a sub-device heartbeat info
 *
 * @param dev_id sub-device id
 * @return OPERATE_RET OPRT_OK is success
 */
OPERATE_RET tuya_iot_fresh_dev_hb(IN CONST CHAR_T *dev_id);

The application calls this function to refresh the heartbeat interval after receiving a response from the sub-device.

Set the heartbeat

/**
 * @brief set sub-device heartbeat timeout parameters.
 *
 * @param dev_id sub-device id
 * @param hb_timeout_time heartbeat timeout, hb_timeout_time==0xffffffff,always online;if is_sleep==false, the hb_timeout_time is invalid.
 * @param max_resend_times max resend times, the default setting is 2. Don't modify, if you don't know.
 * @param is_lowpower TRUE: this sub-device will skip the heartbeat check.
 * @return OPERATE_RET OPRT_OK is success
 */
OPERATE_RET tuya_iot_set_dev_hb_cfg(IN CONST CHAR_T *dev_id,IN CONST TIME_S hb_timeout_time, IN CONST UINT_T max_resend_times, BOOL_T is_lowpower);

The application calls this function to set the heartbeat timeout period for the sub-device.

Example

Register the notification callback to invoke when a heartbeat timeout occurs.

/**
 * @brief device heartbeat callback
 * @param[in]     dev_id      : device's id
 * @param[in]     type        : delete type
 */
STATIC VOID __dev_hb_cb(CONST CHAR_T *dev_id)
{
    /**
     * TODO:
     * a) ping sub-device for checking online
     * b) if online, call tuya_iot_fresh_dev_hb to fresh this device's heartbeat
     */

    /* < demo : make this device always online  > */
    tuya_iot_fresh_dev_hb(dev_id);
}

TY_GW_SUBDEV_MGR_CBS_S  dev_mgr_cbs = {
    .dev_hb        = __dev_hb_cb,
};

tuya_subdev_user_sigle_type_reg( &dev_mgr_cbs , DEV_ATTACH_MOD_1 );

The default timeout period is 10 seconds. To change the timeout, traverse all the sub-devices on program startup and then set the heartbeat timeout.

Example:

DEV_DESC_IF_S *dev_if = NULL;
VOID *iter = NULL;

dev_if = tuya_iot_dev_traversal(&iter);
while (dev_if) {
    if (dev_if->tp == DEV_ATTACH_MOD_1) {
        // read sub-device's states & report
        // call tuya_iot_set_dev_hb_cfg to set heartbeat

       /**
        * Here we show how to set sub-device heartbeat.
        *   all sub-devices will be set 6 mins( 2 mins * 3 ) timeout when SDK starts.
        */
        tuya_iot_set_dev_hb_cfg(dev_if->id, 120, 3, FALSE);
    }
}