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

• 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).

Send control commands

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

• Feature: This function is used to execute object-type data point (DP) commands. You can utilize this function to send specific commands to devices, enabling control of device functionalities or data interaction.
• Parameters:
  • cmd: A pointer to the TY_RECV_OBJ_DP_S struct. The struct encapsulates all necessary command details, including the command type, transmission type, target device CID, multicast ID, DP count, and DP array.
  • retrans: A boolean value indicating whether retransmission is required. When this parameter is set to TRUE, the system will attempt retransmission if command delivery fails. When it is set to FALSE, no retransmission will occur.
• Return value: The function returns an OPERATE_RET type value. OPRT_OK indicates successful command transmission, while any failure returns an error code. Refer to tuya_error_code.h for specific error code definitions.

Struct parameters in this function

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;

• Feature: This struct encapsulates object-type DP commands and serves as the primary command data carrier for the tuya_iot_dev_obj_cmd_send function.
• Member variables:
  • cmd_tp: The command type. For its value range, see DP_CMD_TYPE_E.
  • dtt_tp: The transmission type. For its value range, see DP_TRANS_TYPE_T.
  • cid: The CID of the target device, which is the unique identifier of the device. If the value is NULL, commands are sent to the gateway itself.
  • mb_id: The multicast ID for group control.
  • dps_cnt: The number of data points (DPs) in the command.
  • dps: The flexible array storing DP data, with size determined by dps_cnt. Each DP’s structure follows TY_OBJ_DP_S definition.

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;

• Feature: This struct encapsulates DPs of Zigbee devices. DPs represent device states or attributes, such as temperature, humidity, and on/off status. This struct explicitly defines each DP’s ID, type, value, and timestamp.
• Member variables:
  • dpid: The ID of a DP.
  • type: The type of a DP. See the DP_PROP_TP_E enumeration.
  • value: The value of a DP. See the TY_OBJ_DP_VALUE_U union.
  • time_stamp: The time when a DP occurs. 0 represents the current time.

Register local management callbacks

Local management callbacks

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

• Feature: This function registers local management callbacks for Zigbee devices. During Zigbee device development, these callbacks are developer-defined functions that handle specific events. By invoking this function, the callbacks are registered in the system, enabling automatic execution when corresponding events occur.
• Parameters:
  • cbs: A pointer to the TY_Z3_DEV_LC_MGR_S struct (referenced above). This struct contains pointers to local management callbacks, covering device join/leave/offline events, heartbeat queries, update status/progress, DP reporting, and raw data reporting. You must provide callback implementations in the struct based on actual requirements.
• Return value: The function returns an OPERATE_RET type value. OPRT_OK indicates successful registration, while any failure returns an error code. Refer to tuya_error_code.h for specific error code definitions.

Struct parameters in this function

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;

• Feature: This struct encapsulates local management callbacks for Zigbee devices. This struct provides a mechanism that enables you to associate custom functions with various Zigbee device events, thereby achieving flexible control and management of device behaviors.

• Member variables:

  • dev_join_cb: A pointer to the device joining callback function. The system invokes this function when a new device joins the Zigbee network, allowing you to implement custom join-handling logic.

  • dev_leave_cb: A pointer to the device leaving callback function. The system invokes this function when a device leaves the Zigbee network, allowing you to implement custom leave-handling logic.

  • dev_offline_cb: A pointer to the device offline callback function. The system invokes this function when a device goes offline, allowing you to implement custom offline-handling logic.

  • dev_heartbeat_query_cb: A pointer to the heartbeat query callback function. The system invokes this function to check a device’s liveliness status, allowing you to implement custom heartbeat query logic.

  • dev_upgrade_status_cb: A pointer to the update state callback function. The system invokes this function when a device’s update state changes, allowing you to implement custom management logic for update states.

  • dev_upgrade_progress_cb: A pointer to the update progress callback function. The system invokes this function when a device’s update progress changes, allowing you to implement custom management logic for update progress.

  • dev_obj_dp_rept_cb: A pointer to the DP reporting callback function. The system invokes this function when a device reports DP updates, allowing you to implement custom processing logic for DP reporting.

  • dev_raw_dp_rept_cb: A pointer to the raw data reporting callback function. The system invokes this function when a device reports raw data, allowing you to implement custom processing logic for raw data reporting.

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

Initialize Zigbee local management

// Initialize Zigbee local management
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);
}

Traverse devices

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

Pair sub-devices

/*Sub-device pairing*/
OPERATE_RET user_zigbee_permit_join(IN BOOL_T enable, IN UINT_T timeout)
{
    OPERATE_RET ret = OPRT_OK;

    if (enable) {
        // Enable Permit Join mode
        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 {
        // Disable Permit Join mode
        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;
}

Send commands to sub-devices

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

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.