Zigbee Sub-device Failover

Overview

On the Tuya Developer Platform, the Zigbee sub-device failover feature allows users to quickly replace faulty Zigbee sub-devices without the need for complex re-pairing or reconfiguration processes. This feature is enabled via the tuya_zigbee_user_fault_replace_init API, which significantly improves the user experience and facilitates device maintenance.

Features

• Seamless failover: Automatically restores original configurations and functionalities after replacing a faulty device.
• Simplified operation: Users do not need to re-pair devices or perform complicated app settings.
• Version compatibility: Supports specifying the minimum network co-processor (NCP) firmware version.
• Stability and reliability: Standardized failover process verified by the Tuya platform.

API description

tuya_zigbee_user_fault_replace_init

/**
 * @brief Tuya Zigbee sub-devices failover service
 *
 * @param[in] zb_ncp_ver Gateway NCP firmware version. Example:"1.0.9"
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_zigbee_user_fault_replace_init(CHAR_T *zb_ncp_ver);

• zb_ncp_ver: Zigbee NCP firmware version number, in string format. It specifies the minimum required NCP version for the gateway, such as “1.3.0”.
• Return value: OPERATE_RET type. OPRT_OK indicates success, while other values indicate errors. For more information, see tuya_error_code.h.

Example

Enable macro definition

Enable the failover feature in the compilation configuration.

#define DEV_FAULT_REPLACE 1

Invoke initialization function

Invoke the failover initialization function during the gateway main program initialization.

#if defined(DEV_FAULT_REPLACE) && (DEV_FAULT_REPLACE == 1)
    TUYA_CALL_ERR_RETURN(tuya_zigbee_user_fault_replace_init("1.3.0"));
#endif

Handle initialization return value

Properly handle the return value to avoid functional exceptions due to initialization failure.

OPERATE_RET ret = tuya_zigbee_user_fault_replace_init("1.3.0");
if (OPRT_OK != ret) {    PR_ERR("Zigbee fault replace init failed: %d", ret);
    // Handle error cases
}

FAQs

Is the failover feature compatible with all Zigbee devices?

No, it only supports Tuya Zigbee sub-devices specifically designed for this feature. For detailed compatibility, refer to the device specifications.

What should I do if the failover fails?

Verify that the new device is the same model and in an unpaired state. Also, make sure the gateway maintains a stable network connection.

How can I check the NCP firmware version?

On the Tuya or SmartLife app, tap Me > Settings > Device Update to view the current NCP firmware version.

What should I do if a missing library error occurs during compilation?

The most common cause is the absence of Bluetooth library files containing the implementation of the tuya_gw_mesh_dev_grp_notify function. Missing libraries typically include:

-l:libty_module_bluetooth.a \
-l:libty_module_bluetooth_host.a

Solution: Check the compilation configuration and ensure the correct libraries are linked. Add the corresponding libraries in the software/TuyaOS/apps/tuyaos_demo_zigbee/Makefile.