子设备心跳

心跳 是节点之间发送的一种通信数据包，用于监控节点，网络接口的健康状态。本文将介绍 子设备心跳 的实现方式。

功能描述

子设备心跳 是 SDK 确保子设备在线的手段，实现方式通常有两种：

• 方式一：网关定期 ping 子设备。可以通过定期读取版本号等方式实现 ping。
• 方式二：子设备定时主动上报数据。可以通过定时上报版本号信息等。

使用方法

SDK 实现了心跳管理，采用的是上文提到的 方式一。当心跳超时时，SDK 通知应用查询子设备是否在线。应用收到子设备上报的任何信息，都调用 SDK 的 tuya_iot_fresh_dev_hb 接口刷新心跳。

数据结构

/**
 * @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 说明

刷新心跳

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

应用收到子设备心跳包后调用该 API 即可刷新心跳周期。

设置心跳相关配置

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

调用该 API 可以设置子设备心跳超时时间。

使用示例

注册心跳超时通知回调：

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

SDK 默认的心跳超时是 10 秒，如需要调整心跳超时时间，需要在程序启动的时候遍历所有子设备，然后配置心跳超时时间。示例如下：

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);
    }
}