Zigbee 本地管理

功能介绍

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

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

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

接口描述

允许子设备入网

/**
 * @brief 控制Zigbee子设备入网许可
 * @param[in] enable: TRUE-开启入网许可，FALSE-关闭入网许可
 * @param[in] timeout: 入网许可持续时间(秒)，0表示使用默认值
 * @return OPERATE_RET: 操作结果，OPRT_OK表示成功
 */
OPERATE_RET user_zigbee_permit_join(BOOL_T enable, UINT_T timeout);

使用说明：

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

注册 Zigbee 本地管理回调

/**
 * @brief 初始化 Zigbee 本地管理模块并注册回调函数
 * @return OPERATE_RET: 初始化结果，OPRT_OK 表示成功
 */
OPERATE_RET user_zigbee_local_init(void);

回调功能：

• 设备加入网络通知
• 设备离开网络通知
• 设备离线通知
• 设备心跳查询
• 设备升级状态通知
• 设备数据点上报（状态变化）

下发控制指令

/**
 * @brief 向指定 Zigbee 设备发送控制命令
 * @param[in] dev_id: 目标设备 ID
 * @param[in] dps: 数据点数组
 * @param[in] dp_cnt: 数据点数量
 * @return OPERATE_RET: 发送结果，OPRT_OK 表示成功
 */
OPERATE_RET user_zigbee_send_command(const CHAR_T* dev_id, 
                                   const TY_OBJ_DP_S* dps, 
                                   UINT_T dp_cnt);

参数说明：

• dev_id: 目标设备的唯一标识符。
• dps: 数据点数组，包含要控制的数据点信息。
• dp_cnt: 要控制的数据点数量。

获取设备列表

/**
 * @brief 遍历当前所有 Zigbee 子设备
 * @param[in] cb: 回调函数，用于处理每个设备信息
 * @return OPERATE_RET: 操作结果，OPRT_OK 表示成功
 */
OPERATE_RET user_zigbee_traverse_devices(zigbee_dev_callback cb);

/**
 * @brief 设备信息回调函数类型
 * @param[in] dev_info: 设备信息结构体指针
 */
typedef void (*zigbee_dev_callback)(const zigbee_dev_info_t* dev_info);

/**
 * @brief Zigbee 设备信息结构体
 */
typedef struct {
    CHAR_T dev_id[DEV_ID_LEN + 1]; // 设备 ID
    BOOL_T online;                // 在线状态
} zigbee_dev_info_t;

使用示例

基本使用流程

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

代码示例

#include "user_zigbee_local.h"

// 设备状态变化回调示例
STATIC VOID __z3_lc_dev_join_cb(CONST CHAR_T *dev_id, CONST CHAR_T *pid, CONST CHAR_T *ver)
{
    PR_DEBUG("New device joined: %s, product ID: %s", dev_id, pid);
}

// 初始化 Zigbee 本地管理
void zigbee_init()
{
    // 初始化本地管理模块
    user_zigbee_local_init();
    
    // 开启入网许可 60 秒
    user_zigbee_permit_join(TRUE, 60);
}

// 列出所有设备
void list_devices()
{
    PR_DEBUG("Current Zigbee devices:");
    user_zigbee_traverse_devices([](const zigbee_dev_info_t* dev_info) {
        PR_DEBUG("Device ID: %s, Status: %s", 
                dev_info->dev_id, 
                dev_info->online ? "Online" : "Offline");
    });
}

// 控制设备示例
void control_device(const CHAR_T* dev_id)
{
    TY_OBJ_DP_S dp = {
        .dpid = 1,          // 数据点 ID
        .type = PROP_BOOL,   // 数据类型
        .value.dp_bool = TRUE // 设置值为 TRUE
    };
    
    OPERATE_RET ret = user_zigbee_send_command(dev_id, &dp, 1);
    if (ret == OPRT_OK) {
        PR_DEBUG("Control command sent successfully");
    } else {
        PR_ERR("Failed to send control command: %d", ret);
    }
}

菜单驱动示例

// 打印菜单
void print_menu()
{
    PR_DEBUG("\n===== Zigbee Management Menu =====");
    PR_DEBUG("1. List devices (l)");
    PR_DEBUG("2. Send command (s)");
    PR_DEBUG("3. Permit join (p)");
    PR_DEBUG("4. Close permit join (c)");
    PR_DEBUG("5. Exit (q)");
    PR_DEBUG("Enter your choice: ");
}

// 主循环
void main_loop()
{
    while (1) {
        print_menu();
        
        CHAR_T input[256];
        fgets(input, sizeof(input), stdin);
        
        switch (input[0]) {
            case 'l': // 列出设备
                list_devices();
                break;
                
            case 's': // 发送命令
                PR_DEBUG("Enter device ID: ");
                fgets(input, sizeof(input), stdin);
                input[strcspn(input, "\n")] = 0; // 去除换行符
                control_device(input);
                break;
                
            case 'p': // 开启入网许可
                user_zigbee_permit_join(TRUE, 60);
                PR_DEBUG("Permit join enabled for 60 seconds");
                break;
                
            case 'c': // 关闭入网许可
                user_zigbee_permit_join(FALSE, 0);
                PR_DEBUG("Permit join disabled");
                break;
                
            case 'q': // 退出
                return;
                
            default:
                PR_DEBUG("Invalid choice");
        }
        
        tuya_hal_system_sleep(1000); // 1 秒延迟
    }
}

注意事项

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