Zigbee Services

This topic describes the APIs used to implement Zigbee services.

Structs

TY_Z3_DEV_S

typedef struct {
    CHAR_T *manu_name;
    CHAR_T *model_id;
} TY_Z3_DEV_S;

Functional specification

The product information.

Member description

Parameter name	Description
manu_name	The manufacturer name of the device.
model_id	The model ID of the device.

TY_Z3_DEVLIST_S

typedef struct {
    TY_Z3_DEV_S  *devs;
    UINT16_T      dev_num;
} TY_Z3_DEVLIST_S;

Functional specification

The list of allowlisted devices.

Member description

Parameter name	Description
devs	The array of device information. For more information, see TY_Z3_DEV_S.
dev_num	The length of the array of device information.

TY_Z3_DEV_CBS_S

typedef struct {
    VOID (*join)(TY_Z3_DESC_S *dev);
    VOID (*leave)(CONST CHAR_T *dev_id);
    VOID (*report)(TY_Z3_APS_FRAME_S *frame);
    VOID (*notify)(VOID);
    VOID (*upgrade_end)(CONST CHAR_T *dev_id, INT_T rc, UCHAR_T version);
    VOID (*version)(CONST CHAR_T *dev_id, UCHAR_T version);
} TY_Z3_DEV_CBS_S;

Functional specification

The Zigbee device management callbacks.

Member description

Parameter name	Description
join	The callback to invoke when an allowlisted Zigbee sub-device joins the network. For more information, see join.
leave	The callback to invoke when an allowlisted Zigbee sub-device leaves the network. For more information, see leave.
report	The callback to invoke when an allowlisted Zigbee sub-device reports data. For more information, see report.
notify	The callback to invoke when an allowlisted Zigbee sub-device syncs status. For more information, see notify.
upgrade_end	The callback to invoke when an allowlisted Zigbee sub-device completes a firmware update. For more information, see upgrade_end.
version	The callback to invoke when an allowlisted Zigbee sub-device reports its new firmware version number. For more information, see version.

TY_Z3_APS_FRAME_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   node_id;
    UINT16_T   profile_id;
    UINT16_T   cluster_id;
    UCHAR_T    src_endpoint;
    UCHAR_T    dst_endpoint;
    UINT16_T   group_id;
    UCHAR_T    cmd_type;
    UCHAR_T    cmd_id;
    UCHAR_T    frame_type;
    UINT16_T   manufacturer_code;
    CHAR_T     disable_ack;
    UINT16_T   msg_length;
    UCHAR_T   *message;
} TY_Z3_APS_FRAME_S;

Functional specification

The Zigbee Cluster Library (ZCL) data frame.

Member description

Member	Description
id	The MAC address of the sub-device.
node_id	The network address of the sub-device.
profile_id	The Zigbee profile ID.
cluster_id	The Zigbee cluster ID.
src_endpoint	The source endpoint.
dst_endpoint	The destination endpoint.
group_id	The group ID, used for multicast.
cmd_type	The types of ZCL: 0: Global command. 1: Cluster specific command.
cmd_id	The ZCL command ID.
frame_type	The types of data transmission: 0: Unicast. 1: Multicast. 2: Broadcast.
disable_ack	Specifies whether to disable the response acknowledgment (ACK): 1: Disable. 0: Enable.
msg_length	The length of ZCL payload.
message	The ZCL payload.

TY_Z3_DESC_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   profile_id[MAX_EP_NUM];
    UINT16_T   device_id[MAX_EP_NUM];
    UINT16_T   cluster_id[MAX_EP_NUM][MAX_CLUSTER_NUM];
    UINT16_T   endpoint[MAX_EP_NUM];
    UCHAR_T    ep_num;
    UCHAR_T    uc_num;
    UINT16_T   node_id;
    CHAR_T     manu_name[MANU_NAME_LEN+1];
    CHAR_T     model_id[MODEL_ID_LEN+1];
    CHAR_T     rejoin_flag;
    CHAR_T     power_source;
    UCHAR_T    version;
} TY_Z3_DESC_S;

Functional description

The Zigbee device information.

Member description

Member	Description
id	The MAC address of the sub-device.
profile_id	The Zigbee profile ID.
device_id	The device ID of the Zigbee device.
cluster_id	The Zigbee cluster ID.
endpoint	The Zigbee endpoint.
ep_num	The number of endpoints.
uc_num	The number of clusters.
node_id	The network address of the sub-device.
manu_name	The manufacturer name.
model_id	The model ID of the Zigbee device.
rejoin_flag	The rejoin flag.
power_source	The types of power source: 0x03: Battery powered. 0x04: Mains powered.
version	The application version.

API reference

tuya_zigbee_svc_init

OPERATE_RET tuya_zigbee_svc_init(ty_cJSON *cfg)

Functional description

Initializes Tuya-specific Zigbee services.

Parameter description

Parameter name	Description
cfg	JSON configuration

Description of JSON configuration

{
	"storage_path": "./",       //  The data storage path.
	"cache_path": "/tmp/",      //  The firmware storage path.
	"dev_name": "/dev/ttyUSB0", //  The serial port of the Zigbee device.
	"cts": 0,                   //  Specifies whether to support hardware flow control.
	"thread_mode": 1,           //  Specifies whether to use a thread to run the Zigbee host service.
	"sw_ver": "1.0.8"           // This field is deprecated.
}

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_svc_start

OPERATE_RET tuya_zigbee_svc_start(ty_cJSON *cfg)

Functional description

Starts Tuya-specific Zigbee services.

Parameter description

Parameter name	Description
cfg	JSON configuration, same as the parameters defined in tuya_zigbee_svc_init.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_reg_permit_join_cb

OPERATE_RET tuya_zigbee_reg_permit_join_cb(TY_Z3_PERMIT_JOIN_CB cb)

Functional description

Registers a notification callback to invoke when the Zigbee network co-processor (NCP) allows a sub-device to join the network. This API must be called before tuya_zigbee_svc_init.

Parameter description

Parameter name	Description
cb	A Zigbee NCP allows or disallows a sub-device to join a network. For more information, see TY_Z3_PERMIT_JOIN_CB.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_reg_ncp_got_ver_cb

OPERATE_RET tuya_zigbee_reg_ncp_got_ver_cb(TY_Z3_NCP_GOT_VER_CB cb)

Functional description

Registers a notification callback to invoke when the version number of a Zigbee NCP is returned. This API must be called before tuya_zigbee_svc_init.

Parameter description

Parameter name	Description
cb	The notification callback to invoke when the version number of the Zigbee NCP is returned. For more information, see TY_Z3_NCP_GOT_VER_CB.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_reg_ncp_hard_reset_cb

OPERATE_RET tuya_zigbee_reg_ncp_hard_reset_cb(TY_Z3_NCP_HARD_RESET_CB cb)

Functional description

Registers a notification callback to invoke when the Zigbee NCP performs a hard reboot. This API must be called before tuya_zigbee_svc_init.

Parameter description

Parameter name	Description
cb	The notification callback to invoke when the Zigbee NCP performs a hard reboot. For more information, see TY_Z3_NCP_HARD_RESET_CB.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_print_debug_info

OPERATE_RET tuya_zigbee_print_debug_info(VOID)

Functional description

Prints debug logs for the Zigbee NCP.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_set_tx_radio_power

OPERATE_RET tuya_zigbee_set_tx_radio_power(INT_T tx_power)

Functional description

Sets the transmission power of the Zigbee NCP.

Parameter description

Parameter name	Description
tx_power	The transmitter power, ranging from 0 to 19.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_rftest

OPERATE_RET tuya_zigbee_rftest(TY_Z3_RFTEST_RESULT_CB cb,
                               UCHAR_T channel,
                               CHAR_T power,
                               UCHAR_T msg_len,
                               UCHAR_T *msg,
                               USHORT_T npacket)

Functional description

Transmits data over Zigbee to perform a production test.

Parameter description

Parameter name	Description
cb	The callback to invoke when data transmission is finished.
channel	The transmission channel, ranging from 11 to 26.
power	The transmitter power, ranging from 0 to 19.
msg_len	The length of data transmitted.
msg	The data to be transmitted for a test. If you use Tuya’s Zigbee dongle, the data to be transmitted must be {0x55, 0xaa, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39}.
npacket	The number of packets transmitted.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_upgrade_ncp

OPERATE_RET tuya_zigbee_upgrade_ncp(CONST CHAR_T *fw_file,
                                    TY_Z3_NCP_UPGRADE_STATUS_CB cb)

Functional description

Updates the firmware on the Zigbee NCP locally.

Parameter description

Parameter name	Description
fw_file	The path of the firmware.
cb	The update result callback. For more information, see TY_Z3_NCP_UPGRADE_STATUS_CB.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_set_ncp_mac

OPERATE_RET tuya_zigbee_set_ncp_mac(CONST CHAR_T *mac)

Functional description

Sets the MAC address of the Zigbee NCP. Typically, this API is used for failover debugging. To avoid a conflict with the replacement gateway, the failed gateway must be written with a new MAC address.

Parameter description

Parameter name	Description
mac	The MAC addresses.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_reset_ncp

OPERATE_RET tuya_zigbee_reset_ncp(VOID)

Functional description

Resets the Zigbee NCP.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_get_ncp_ver

OPERATE_RET tuya_zigbee_get_ncp_ver(CHAR_T *ver)

Functional description

Reads the firmware version number of the Zigbee NCP.

Parameter description

Parameter name	Description
ver	The version number.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_custom_dev_mgr_init

OPERATE_RET tuya_zigbee_custom_dev_mgr_init(TY_Z3_DEVLIST_S *devlist,
                                            TY_Z3_DEV_CBS_S *cbs)

Functional description

Initializes a third-party Zigbee device. This API must be called before tuya_zigbee_svc_init.

Connecting to third-party Zigbee sub-devices is implemented by you. You can register an allowlist to notify the SDK that the listed device is processed by a third party so that the SDK will transmit the raw data to the specified application.

If the allowlist is empty, it indicates all the devices are processed by a third party.

Parameter description

Parameter name	Description
devlist	The allowlist. For more information, see TY_Z3_DEVLIST_S.
cbs	The Zigbee device management callbacks. For more information, see TY_Z3_DEV_CBS_S.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_send_data

OPERATE_RET tuya_zigbee_send_data(TY_Z3_APS_FRAME_S *frame)

Functional description

Sends Zigbee ZCL data to the Zigbee sub-device. This API is used for third-party Zigbee devices.

Parameter description

Parameter name	Description
frame	The Zigbee ZCL data frame. For more information, see TY_Z3_APS_FRAME_S.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_del_dev

OPERATE_RET tuya_zigbee_del_dev(CONST CHAR_T *dev_id)

Functional description

Removes a sub-device from the Zigbee network. This API is used for third-party Zigbee devices.

Parameter description

Parameter name	Description
dev_id	The MAC address of the sub-device.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

tuya_zigbee_upgrade_dev

OPERATE_RET tuya_zigbee_upgrade_dev(CONST CHAR_T *dev_id,
                                    CONST FW_UG_S *fw)

Functional description

Updates a Zigbee sub-device. This API is used for third-party Zigbee devices.

Parameter description

Parameter name	Description
dev_id	The MAC address of the sub-device.

Return value

Return value	Description
OPRT_OK	Success
Error code	For more information about the error code, see tuya_error_code.h.

Callback functions

join

VOID (*join)(TY_Z3_DESC_S *dev)

Functional description

The callback to invoke when an allowlisted Zigbee sub-device joins the network.

Parameter description

Parameter name	Description
dev	The device information. For more information, see TY_Z3_DESC_S.

Return value

Return value	Description
VOID	/

leave

VOID (*leave)(CONST CHAR_T *dev_id)

Functional description

The callback to invoke when an allowlisted Zigbee sub-device leaves the network.

Parameter description

Parameter name	Description
dev_id	The MAC address of the sub-device.

Return value

Return value	Description
VOID	/

report

VOID (*report)(TY_Z3_APS_FRAME_S *frame)

Functional description

The callback to invoke when an allowlisted Zigbee sub-device reports data.

Parameter description

Parameter name	Description
frame	The Zigbee ZCL data frame. For more information, see TY_Z3_APS_FRAME_S.

Return value

Return value	Description
VOID	/

notify

VOID (*notify)(VOID);

Functional description

The callback to invoke when an allowlisted Zigbee sub-device completes a firmware update. You need to traverse all the sub-devices and read their current status.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
VOID	/

upgrade_end

VOID (*upgrade_end)(CONST CHAR_T *dev_id,
                    INT_T rc,
                    UCHAR_T version);

Functional description

The update result callback.

Parameter description

Parameter name	Description
dev_id	The MAC address of the sub-device.
rc	The update result.
version	The firmware version number of the sub-device.

Return value

Return value	Description
VOID	/

version

VOID (*version)(CONST CHAR_T *dev_id,
                UCHAR_T version)

Functional description

The callback to invoke when an allowlisted Zigbee sub-device reports its new firmware version number.

Parameter description

Parameter name	Description
dev_id	The MAC address of the sub-device.
version	The firmware version number of the sub-device.

Return value

Return value	Description
VOID	/

TY_Z3_PERMIT_JOIN_CB

typedef VOID (*TY_Z3_PERMIT_JOIN_CB)(BOOL_T permit,
                                     UINT_T timeout)

Functional description

The notification callback to invoke when the Zigbee NCP allows a sub-device to join the network.

Parameter description

Parameter name	Description
permit	The pairing status: TRUE: Allow a Zigbee sub-device to join the network. FALSE: Disallow a Zigbee sub-device to join the network.
timeout	When permit is TRUE, this parameter is valid, indicating the pairing timeout period, in seconds.

Return value

Return value	Description
VOID	/

TY_Z3_NCP_GOT_VER_CB

typedef VOID (*TY_Z3_NCP_GOT_VER_CB)(CHAR_T *ver)

Functional description

Registers a notification callback to invoke when the version number of a Zigbee NCP is returned.

Parameter description

Parameter name	Description
ver	The firmware version number of the Zigbee NCP.

Return value

Return value	Description
VOID	/

TY_Z3_NCP_HARD_RESET_CB

typedef VOID (*TY_Z3_NCP_HARD_RESET_CB)(VOID)

Functional description

The notification callback to invoke when the Zigbee NCP performs a hard reboot. In this callback, you need to control the nRST pin on the Zigbee module by GPIO signals to achieve a hard reboot.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
VOID	/

TY_Z3_NCP_UPGRADE_STATUS_CB

typedef VOID (*TY_Z3_NCP_UPGRADE_STATUS_CB)(BOOL_T status)

Functional description

The Zigbee NCP update result callback.

Parameter description

Parameter name	Description
status	The update result. TRUE: Success. FALSE: Failure.

Return value

Return value	Description
VOID	/