Zigbee Local Management

Functional introduction

Zigbee local management provides the capability to directly manage and control Zigbee sub-devices within the local network, eliminating complete reliance on cloud interactions. This feature is primarily implemented in smart home gateway devices and enables the following functionalities:

• Allow or deny new Zigbee sub-devices from joining the network (Pairing management).
• Monitor sub-device joining, leaving, and offline status in real time.
• Send control commands to sub-devices directly (Downlink control).
• Get information on all currently connected sub-devices in the network.
• Receive status data reported by sub-devices (Uplink reporting).

This localized management mechanism enhances real-time device control responsiveness while reducing cloud dependency, ensuring core device control remains functional even during network instability.

API description

Allow sub-devices to join network

/**
 * @brief Control the permission for Zigbee sub-devices to join the network.
 * @param[in] enable: TRUE: Allows new sub-devices to join, and FALSE: Rejects all new joining attempts.
 * @param[in] timeout: Timeout duration in seconds for the operation. 0 indicates the default value.
 * @return OPERATE_RET: The operation result. OPRT_OK indicates success.
 */
OPERATE_RET user_zigbee_permit_join(BOOL_T enable, UINT_T timeout);

Description:

• After the permission is enabled, new devices can join the Zigbee network.
• The permission must be disabled promptly after pairing to prevent unauthorized joins.
• When the timeout is set to 0, the system default value is used (usually 180 seconds).

Register Zigbee local management callback

/**
 * @brief Initialize the Zigbee local management module and register a callback function.
 * @return OPERATE_RET: The initialization result. OPRT_OK indicates success.
 */
OPERATE_RET user_zigbee_local_init(void);

Callback:

• Notification of device joining the network
• Notification of device leaving the network
• Notification of device going offline
• Device heartbeat query
• Notification of device update status
• Device data point (DP) reporting (status change)

Send control commands

/**
 * @brief Send control commands to the specified Zigbee device.
 * @param[in] dev_id: The ID of the specified device.
 * @param[in] dps: The array of DPs.
 * @param[in] dp_cnt: The number of DPs.
 * @return OPERATE_RET: The sending result. OPRT_OK indicates success.
 */
OPERATE_RET user_zigbee_send_command(const CHAR_T* dev_id,
                                   const TY_OBJ_DP_S* dps,
                                   UINT_T dp_cnt);

Parameter description:

• dev_id: The unique identifier of the specified device.
• dps: The array of DPs, containing information about the DPs to be controlled.
• dp_cnt: The number of DPs to be controlled.

Get device list

/**
 * @brief Traverse all current Zigbee sub-devices.
 * @param[in] cb: The callback function used to process each device information.
 * @return OPERATE_RET: The operation result. OPRT_OK indicates success.
 */
OPERATE_RET user_zigbee_traverse_devices(zigbee_dev_callback cb);

/**
 * @brief The type of device information callback.
 * @param[in] dev_info: The pointer to the device information struct.
 */
typedef void (*zigbee_dev_callback)(const zigbee_dev_info_t* dev_info);

/**
 * @brief Zigbee device information struct.
 */
typedef struct {
    CHAR_T dev_id[DEV_ID_LEN + 1]; // The device ID.
    BOOL_T online;                // The online status.
} zigbee_dev_info_t;

Example

Procedure

1. Initialize the Zigbee local management module.
2. Register a callback function to receive device status changes.
3. Enable network joining permission and add new devices.
4. Call the device list API to get the list of connected devices.
5. Manage devices through the control API.

Example

#include "user_zigbee_local.h"

// Device status change callback example.
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);
}

// Initialize Zigbee local management.
void zigbee_init()
{
    // Initialize the local management module.
    user_zigbee_local_init();

    // Enable network joining permission for 60 seconds.
    user_zigbee_permit_join(TRUE, 60);
}

// List all the devices.
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");
    });
}

// Example of how to control the devices.
void control_device(const CHAR_T* dev_id)
{
    TY_OBJ_DP_S dp = {
        .dpid = 1,          // The ID of a DP.
        .type = PROP_BOOL,   // The data type.
        .value.dp_bool = TRUE // Set to 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);
    }
}

Menu driver example

// Print the menu
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: ");
}

// Main loop
void main_loop()
{
    while (1) {
        print_menu();

        CHAR_T input[256];
        fgets(input, sizeof(input), stdin);

        switch (input[0]) {
            case 'l': // List the devices
                list_devices();
                break;

            case 's': // Send commands
                PR_DEBUG("Enter device ID: ");
                fgets(input, sizeof(input), stdin);
                input[strcspn(input, "\n")] = 0; // Remove line breaks
                control_device(input);
                break;

            case 'p': // Enable network joining permission
                user_zigbee_permit_join(TRUE, 60);
                PR_DEBUG("Permit join enabled for 60 seconds");
                break;

            case 'c': // Disable network joining permission
                user_zigbee_permit_join(FALSE, 0);
                PR_DEBUG("Permit join disabled");
                break;

            case 'q': // Exit
                return;

            default:
                PR_DEBUG("Invalid choice");
        }

        tuya_hal_system_sleep(1000); // 1-second delay
    }
}

Things to note

• After the pairing is completed, the network joining permission should be disabled in time to avoid security risks.
• Device lists are stored in volatile memory and will be lost after reboot, so rediscovery is required.
• Verify device online status before sending control commands.
• Avoid time-consuming operations in callback functions to maintain system stability.
• Device IDs are unique identifiers and should never be hardcoded in programs.