Zigbee 本地管理

功能介绍

Zigbee 本地管理功能为开发者提供了在本地网络中直接管理和控制 Zigbee 子设备的能力，无需完全依赖云端交互。该功能主要应用于智能家居网关设备中，可以实现以下功能：

• 允许或禁止新的 Zigbee 子设备加入网络（配网管理）
• 实时监控子设备的加入、离开和离线状态
• 直接向子设备发送控制指令（下行控制）
• 获取当前网络中所有已连接子设备的信息列表
• 接收子设备上报的状态数据（上行报告）

这种本地化管理机制提高了设备控制的实时性，降低了云端依赖，在网络不稳定时仍能保证基本的设备控制功能。

接口描述

允许子设备入网

/** 
 * @brief setup permit joining
 *
 * @param[in] tp      protocol type, 0xFF means ignore the type
 * @param[in] permit  TRUE: enable joining, FALSE: disable joining
 * @param[in] timeout timeout of permit joining (sec)
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h   
 */
OPERATE_RET tuya_iot_dev_join_permit(GW_PERMIT_DEV_TP_T tp, BOOL_T permit, UINT_T timeout);

• 开启入网许可后，新设备可以加入 Zigbee 网络。
• 配网完成后应及时关闭入网许可，避免未经授权的设备加入。
• 超时时间设置为 0 时，使用系统默认值（通常为 180 秒）。

下发控制指令

/** 
 * @brief execute obj DP command
 *
 * @param[in] cmd obj DP data, see TY_RECV_OBJ_DP_S
 * @param[in] retrans TRUE: retransmit, FALSE: not retransmit
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h   
 */
OPERATE_RET tuya_iot_dev_obj_cmd_send(CONST TY_RECV_OBJ_DP_S *cmd, BOOL_T retrans);

• 功能：该函数用于执行对象型数据点（DP）命令。开发者可以通过此函数向设备发送特定的命令，以实现对设备功能的控制或数据的交互。
• 参数：
  • cmd：指向 TY_RECV_OBJ_DP_S 结构体的指针，该结构体包含了要发送的命令的详细信息，如命令类型、传输类型、目标设备 CID、组播 ID、数据点数量及数据点数组等。
  • retrans：布尔值，用于指示是否需要重传。当设置为 TRUE 时，表示如果命令发送失败，则需要进行重传；当设置为 FALSE 时，则不会进行重传。
• 返回值：返回 OPERATE_RET 类型的值。如果命令发送成功，则返回 OPRT_OK；如果发送失败，则返回错误码，具体错误码的含义可以参考 tuya_error_code.h 文件中的定义。

本函数中的结构体参数

typedef struct {
    /** see DP_CMD_TYPE_E */
    DP_CMD_TYPE_E cmd_tp;
    /** see DP_TRANS_TYPE_T */
    DP_TRANS_TYPE_T dtt_tp;
    /** if(NULL == cid) then then the cid represents gwid */
    CHAR_T *cid;
    /** mb id */
    CHAR_T *mb_id;
    /** count of dp */
    UINT_T dps_cnt;
    /** the dp data */
    TY_OBJ_DP_S dps[0];
} TY_RECV_OBJ_DP_S;

• 功能：该结构体用于封装对象型数据点命令的相关信息，是 tuya_iot_dev_obj_cmd_send 函数中用于传递命令数据的重要结构体。
• 成员变量：
  • cmd_tp：命令类型，其取值范围见 DP_CMD_TYPE_E
  • dtt_tp：传输类型，其取值范围见 DP_TRANS_TYPE_T
  • cid：目标设备 CID，即设备的唯一标识。如果该值为 NULL，则表示命令是发送给网关自身的。
  • mb_id：组播 ID，用于群组控制。
  • dps_cnt：数据点数量，表示该命令中包含的数据点的个数。
  • dps：数据点数组，是一个柔性数组，用于存储具体的数据点信息。数组的大小由 dps_cnt 决定，每个数据点的具体结构由 TY_OBJ_DP_S 定义。

typedef struct {
    /** dp id */
    BYTE_T dpid;
    /** dp type, see DP_PROP_TP_E */
    DP_PROP_TP_E type;
    /** dp value, see TY_OBJ_DP_VALUE_U */
    TY_OBJ_DP_VALUE_U value;
    /** dp happen time. if 0, mean now */
    UINT_T time_stamp;
} TY_OBJ_DP_S;

• 功能：该结构体用于封装 Zigbee 设备的数据点（DP，Data Point）信息。数据点是设备状态或属性的表示，例如温度、湿度、开关状态等。通过该结构体，可以清晰地定义每个数据点的 ID、类型、值以及发生时间。
• 成员变量：
  • dpid：数据点 ID
  • type: 数据点类型，见 DP_PROP_TP_E 枚举
  • value: 数据点值，见 TY_OBJ_DP_VALUE_U 联合体
  • time_stamp: 数据点发生时间，0 表示当前时间

注册本地管理回调

本地管理回调函数

/**
 * @brief    register local management callback.
 * 
 * @param[in] cbs      callback function.
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_zigbee_reg_lc_mgr(CONST TY_Z3_DEV_LC_MGR_S *cbs);

• 功能：该函数用于注册 Zigbee 设备的本地管理回调函数。在 Zigbee 设备的开发过程中，本地管理回调函数是一些由开发者定义的、用于处理特定事件的函数。通过调用此函数，可以将这些回调函数注册到系统中，以便在相应事件发生时，系统能够自动调用这些函数进行处理。
• 参数：
  • cbs：指向 TY_Z3_DEV_LC_MGR_S（上文提及）结构体的指针。该结构体包含了各种本地管理回调函数的指针，这些回调函数涵盖了设备加入、离开、离线、心跳查询、升级状态、升级进度、数据点上报和原始数据上报等多个方面。开发者需要根据实际需求，在结构体中提供相应的回调函数实现。
• 返回值：返回 OPERATE_RET 类型的值。如果注册成功，则返回 OPRT_OK；如果注册失败，则返回错误码，具体错误码的含义可以参考 tuya_error_code.h 文件中的定义。

本函数中的结构体参数

typedef struct {
    TY_Z3_DEV_JOIN_CB              dev_join_cb;
    TY_Z3_DEV_LEAVE_CB             dev_leave_cb;
    TY_Z3_DEV_OFFLINE_CB           dev_offline_cb;
    TY_Z3_DEV_HEARTBEAT_QUERY_CB   dev_heartbeat_query_cb;
    TY_Z3_DEV_UPGRADE_STATUS_CB    dev_upgrade_status_cb;
    TY_Z3_DEV_UPGRADE_PROGRESS_CB  dev_upgrade_progress_cb;
    TY_Z3_DEV_OBJ_DP_REPT_CB       dev_obj_dp_rept_cb; 
    TY_Z3_DEV_RAW_DP_REPT_CB       dev_raw_dp_rept_cb;
} TY_Z3_DEV_LC_MGR_S;

• 功能：该结构体用于封装 Zigbee 设备的本地管理回调函数。它提供了一种机制，使得开发者能够将自定义的函数与 Zigbee 设备的各种事件关联起来，从而实现对设备行为的灵活控制和管理。

• 成员变量：

  • dev_join_cb：设备加入回调函数指针。当有新设备加入 Zigbee 网络时，系统会调用此函数，开发者可以在其中实现设备加入时的处理逻辑。

  • dev_leave_cb：设备离开回调函数指针。当有设备离开 Zigbee 网络时，系统会调用此函数，开发者可以在其中实现设备离开时的处理逻辑。

  • dev_offline_cb：设备离线回调函数指针。当设备离线时，系统会调用此函数，开发者可以在其中实现设备离线时的处理逻辑。

  • dev_heartbeat_query_cb：心跳查询回调函数指针。当系统需要查询设备的心跳状态时，会调用此函数，开发者可以在其中实现心跳查询的处理逻辑。

  • dev_upgrade_status_cb：升级状态回调函数指针。当设备升级状态发生变化时，系统会调用此函数，开发者可以在其中实现升级状态变化时的处理逻辑。

  • dev_upgrade_progress_cb：升级进度回调函数指针。当设备升级进度发生变化时，系统会调用此函数，开发者可以在其中实现升级进度变化时的处理逻辑。

  • dev_obj_dp_rept_cb：数据点上报回调函数指针。当设备上报数据点时，系统会调用此函数，开发者可以在其中实现数据点上报的处理逻辑。

  • dev_raw_dp_rept_cb：原始数据上报回调函数指针。当设备上报原始数据时，系统会调用此函数，开发者可以在其中实现原始数据上报的处理逻辑。

基本使用流程

1. 初始化 Zigbee 本地管理模块。
2. 注册回调函数，接收设备状态变化。
3. 开启入网许可，添加新设备。
4. 使用设备列表功能获取已连接设备。
5. 通过控制接口管理设备。

代码示例

初始化 Zigbee 本地管理

// 初始化 Zigbee 本地管理
OPERATE_RET user_zigbee_local_init(VOID)
{
    
    TY_Z3_DEV_LC_MGR_S __z3_dev_lc_mgr = {
        .dev_join_cb             = __z3_lc_dev_join_cb,
        .dev_leave_cb            = __z3_lc_dev_leave_cb,
        .dev_offline_cb          = __z3_lc_dev_offline_cb,
        .dev_heartbeat_query_cb  = __z3_lc_dev_hb_query_cb,
        .dev_upgrade_status_cb   = __z3_lc_dev_upgrade_status_cb,
        .dev_upgrade_progress_cb = __z3_lc_dev_upgrade_progress_cb,
        .dev_obj_dp_rept_cb      = __z3_lc_dev_obj_dp_report_cb,
        .dev_raw_dp_rept_cb      = __z3_lc_dev_raw_dp_report_cb,
    };

    return tuya_zigbee_reg_lc_mgr(&__z3_dev_lc_mgr);
}

遍历设备

VOID test_subdev_list(VOID)
{
    DEV_DESC_IF_S *dev_if = NULL;
    VOID *iterator = NULL;

    do {
        dev_if = tuya_iot_dev_traversal(&iterator);
        if (dev_if) {
            PR_DEBUG("id: %s, type: %d", dev_if->id, dev_if->tp);
        }
    } while(dev_if);
}

子设备配网

/*子设备配网*/
OPERATE_RET user_zigbee_permit_join(IN BOOL_T enable, IN UINT_T timeout)
{
    OPERATE_RET ret = OPRT_OK;
    
    if (enable) {
        // 开启 Permit Join 模式
        PR_DEBUG("Enable Zigbee permit join for %d seconds", timeout);
        ret = tuya_iot_dev_join_permit(timeout);
        if (ret != OPRT_OK) {
            PR_ERR("Enable permit join failed, ret=%d", ret);
            return ret;
        }
    } else {
        // 关闭 Permit Join 模式
        PR_DEBUG("Disable Zigbee permit join");
        ret = tuya_iot_dev_join_permit(0);
        if (ret != OPRT_OK) {
            PR_ERR("Disable permit join failed, ret=%d", ret);
            return ret;
        }
    }
    
    return ret;
}

发送命令到子设备

VOID test_subdev_cmd(VOID)
{
    UINT_T dp_cnt = 3;
    TY_RECV_OBJ_DP_S *obj_cmd = NULL;

    obj_cmd = Malloc(SIZEOF(TY_RECV_OBJ_DP_S) + dp_cnt * SIZEOF(TY_OBJ_DP_S));
    if (obj_cmd == NULL) {
        PR_ERR("Malloc error");
        return;
    }

    obj_cmd->cid = "112233aabbcc";
    obj_cmd->cmd_tp = DP_CMD_LAN;
    obj_cmd->dtt_tp = DTT_SCT_UNC;
    obj_cmd->dps_cnt = dp_cnt;

    for (INT_T i = 0; i < dp_cnt; i++) {
        obj_cmd->dps[i].dpid = (i + 1);
        obj_cmd->dps[i].type = PROP_BOOL;
        obj_cmd->dps[i].value.dp_bool = TRUE;
    }

    tuya_iot_dev_obj_cmd_send(obj_cmd);

    Free(obj_cmd);
}

注意事项

• 配网完成后，应及时关闭入网许可，避免安全风险。
• 设备列表信息保存在内存中，重启后会丢失，需要重新发现。
• 控制命令发送前，应检查设备在线状态。
• 回调函数中不宜执行耗时操作，以免影响系统稳定性。
• 设备 ID 是唯一标识符，不应硬编码在程序中。