FAQs

This topic describes the common issues with TuyaOS gateway development and solutions to them. If this topic fails to solve your issue, you can seek help in the TuyaOS-Gateway & Central Control Device Development forum.

Common issues

What are the hardware requirements for the development kit?

Generally, the development kit can work on all Linux devices. Recommended resources: a minimum of 3 MB of flash memory and 4 MB of RAM.

Does the development kit support a dynamic library?

Currently, only static libraries are available. The code is compiled with the -fPIC option, allowing you to generate a dynamic library from the static one.

The command below packages all static libraries into a single dynamic library.

gcc -shared -o libtuyaos.so -L./libs -Wl,--whole-archive -lty_iot_sdk -lty_module_gw_base -lty_module_gw_app -lty_module_zigbee -ltuyaos_adapter -Wl,--no-whole-archive

What ports does the development kit listen on?

Port	Protocol	Feature
6667	UDP	Device discovery on LAN
6668	TCP	Control over LAN
6608	UDP	Multi-gateway RPC
6681	UDP	Multi-gateway leader election
6682	TCP	Multi-gateway key agreement
7000	UDP	Multi-gateway node search
12121	UDP	During the bidirectional communication between a Zigbee host and a Zigbee application, the Zigbee host listens on this port.
12122	UDP	During the bidirectional communication between a Zigbee host and a Zigbee application, the Zigbee application listens on this port.

Does the gateway support local linkage?

Yes, it does. If all the devices in the condition and action for the linkage are connected to the same gateway, the gateway will run the linkage as specified, even without internet access.

Is cross-gateway linkage supported?

Yes, it is supported.

• When the devices in the condition and action for the linkage are connected to different gateways on the same LAN, the main gateway will run the linkage, even without internet access.
• If the gateways are not on the same LAN, the cloud will run the linkage, which requires internet access.

Compilation issues

tkl_init.h: No such file or directory

The definition and examples of the TuyaOS Kernel Layer (TKL) APIs are included in the development environment. They are downloaded to the local device during the initial compilation.

The error message indicates that the TKL API file is missing. This could be because your compilation environment has no internet access to download the file or does not have a compression utility to unzip it. You can verify this by checking if the development environment content in the vendor directory is empty.

undefined reference to ‘tuya_iot_sdk_init’

The standard development kit supports both wired and wireless connections by default. tuya_iot_wr_wf_sdk_init should be called for initialization. Do not call tuya_iot_wf_sdk_init and tuya_iot_sdk_init unless you are using a custom development kit.

Troubleshooting

Logged errors

tuya_error_code.h includes the definitions of the common error codes.

Example: An error occurs when you report a DP that does not exist

[09-06 15:29:02:425 TUYA D][smart_frame.c:3437] dp compose null, ret:-3585

> #define OPRT_SVC_DP_ID_NOT_FOUND                         (-0x0e01) //-3585, DP ID not found.

Tools

After the device is activated, you can review the reported data of the device in Device Logs.

Initialization issues

Why does Zigbee module initialization throw errors and the SDK fail to get the version of the Zigbee module?

Description: After the SDK is run, the following error keeps appearing in the log.

[01-01 18:12:31 TUYA Warn][tuya_z3.c:19931] Zigbee COO ver is not get.[01-01 18:12:31 TUYA Warn][z3_wrapper.c:108] tuya_z3_getZigbeeVer, ret: -1

Reason: The serial communication between the gateway’s MCU and the Tuya Zigbee module failed.

Troubleshoot:

• Check the pin connection between the gateway’s MCU and the Tuya Zigbee module. The RTS/CTS pin must be connected.

• Check the configuration of the UART parameters tty_device and tty_baudrate in the code.

• Check the serial driver of the gateway’s MCU.

NCP error

Problem description

ASH_FLAG TUYA check, abnormal_data_num:0.
ASH disconnected: EZSP_ASH_ERROR_XON_XOFF
NCP status: EZSP_NO_ERROR

Reason: The module is restarted.

Troubleshoot: If the CRC checksum fails more than three times, the NCP will be restarted. When the accumulation of an error reaches a threshold, the system considers that some issues on the NCP occur and will restart the NCP.

If you get EZSP_ASH_ERROR_XON_XOFF, it indicates there might be a problem with the flow control of the microcontroller.

Pairing and activation issues

Error 4366 pairing failed

tuya_error_code.h includes the definitions of the common error codes, where you can search for the error code.

Check error code: #define OPRT_SVC_HTTP_API_TOKEN_EXPIRE (-0x110e) // -4366, token expired.

Reason: The description of the error code indicates that the activation token has expired. Try activating the device again and check if the UUID has already been used for another device.

Error -4378 sub-device binding failed

tuya_error_code.h includes the definitions of the common error codes, where you can search for the error code.

Check error code: #define OPRT_SVC_HTTP_SERV_VRFY_FAIL (-0x111a) // -4378, Server verification failed.

Reason: The sub-device is not assigned a license.

Blank app page during device activation

Description: The app has discovered the gateway but failed to pair with it. However, no error messages appear on the app but a blank page.

Troubleshoot: Check if errorCode:PRODUCT_OTA_CHANNEL_CONFIG appears in the log. If so, review the Hardware Development on the Tuya IoT Development Platform and add the firmware, as shown below.

Smart Life app failed to find the device

If wired pairing is used, check whether the mobile phone and the gateway connect to the same local area network (LAN). You can ping the IP address of the mobile phone by using the gateway to verify network connectivity.

Device offline issues

Cycling between online and offline

• Network jitter can cause MQTT to close and reconnect immediately. Check the network performance in Device Logs.
• Throttling limits the number of requests the cloud server accepts within a given time period. Verify if the device is continuously sending data.

Sub-device offline

• If a third-party sub-device goes offline, check the status of the heartbeat packets between the gateway and the sub-device. For more information, see Heartbeat Mechanism.
• A default heartbeat mechanism is applied between the gateway and Tuya-enabled sub-devices. Check the network signal and power status of the sub-device, as these issues can prevent the gateway from receiving a heartbeat packet.

Device reset

Difference between two reset APIs: tuya_iot_gw_unactive and tuya_iot_gw_reset

• tuya_iot_gw_unactive: Only unbinds a device while retaining its data. When the device is reactivated, it returns to the same state as before being unbound.
• tuya_iot_gw_reset: Unbinds a device and clears all of its data.

Log management

Invoke remote log callback

When you request the log on the Tuya IoT Development Platform, the SDK will invoke the log callback.

Sub-device management

Error tx66 keeps appearing in the Zigbee gateway log

Troubleshoot:

• Check if the sub-device is powered off.

• Check if the sub-device is too far away from the gateway.

• Check for the walls and metal objects between the sub-device and the gateway.

• Check for significant interference from the 2.4 GHz Wi-Fi network near the sub-device or gateway.

• Check for interference caused by channel overlap between the Zigbee network and the 2.4 GHz router.

  How to identify channel overlap: Use a Wi-Fi analyzer app to view nearby 2.4 GHz Wi-Fi networks and their channels. Then, compare them with the Zigbee channels shown on the Smart Life app gateway for overlap.

How to get the Zigbee channel

Method 1: Open the gateway panel on the mobile app and tap Device Information to find the channel.

Method 2: After the SDK is started, it will generate a ZigbeeNetInfo.txt file in the directory specified by the .storage_path variable, which stores Zigbee network information such as Zigbee channel and PanID, as shown below:

$ cat zigbeeNetInfo.txt
Node ID:0
Pan ID:0x0044            # Zigbee network PanID
Radio Channel:15        # Zigbee channel
Radio Power:13
Extended Pan Id: 158F733C2F2325A6
EUI64: F1F2D3FEFFD76B08
Global Key: A2 42 0D D6 50 DD 3B C3 1E CD BD 82 8A 19 E4 92
Global FC:0xFFFFFFFF
Network Key: A5 DA 43 DE 24 A3 7D 54 7A 6B 32 F1 EF 01 E3 A6
Network FC:0x00005001
Network Sequence Number:0x00

Method 3: Find the channel information in the startup log.

[01-01 18:12:20:242 TUYA N][z3_slabs.c:147] nodeEuiStr = 588e81fffec70507.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:148] nodeId = 0x0000.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:149] panId = 0xbc4b.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:150] channel = 0x0f.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:151] ver = 1.0.8.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:152] netStatus = 0x02.
[01-01 18:12:20:242 TUYA N][z3_slabs.c:153] extendedPanId: 5eaf522991cdd2e9
[01-01 18:12:20:242 TUYA N][z3_slabs.c:154] manufacturerId: 0x0001
[01-01 18:12:20:243 TUYA N][z3_slabs.c:160] netWorkKey: d7 1d 0f 07 ab 00 46 05 00 46 0b 01 00 30 fe ff

Analyze the signal strength of Zigbee sub-devices

Method 1: Open the gateway panel on the mobile app, as shown below. Tap the three-dot icon and then select Device Signal Detection to get the signal strength of the sub-device.

Method 2: Search for LastHopLqi in the log and determine the signal strength based on its value.

• Excellent: >200.
• Good: 150 to 200.
• Fair: 100 to 150.
• Poor: <100

[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-39, LastHopLqi:244
[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-38, LastHopLqi:248
[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-39, LastHopLqi:244
[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-39, LastHopLqi:244
[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-37, LastHopLqi:252
[callback-stub.c:2861] NodeId:0xab3b, LastHopRssi:-39, LastHopLqi:244
[callback-stub.c:2861] NodeId:0x17ea, LastHopRssi:-68, LastHopLqi:128
[callback-stub.c:2861] NodeId:0x17ea, LastHopRssi:-61, LastHopLqi:156
[callback-stub.c:2861] NodeId:0x17ea, LastHopRssi:-58, LastHopLqi:168
[callback-stub.c:2861] NodeId:0x17ea, LastHopRssi:-60, LastHopLqi:160

Linkage issues

Local linkage does not work

Search for the keyword scene in the log, find the logs before and after the linkage is triggered, and follow the troubleshooting steps below:

1. Check if the DP has detected the linkage. For example, DP 25 reports cond stat: 2, indicating the conditions for executing the linkage are met.

   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:1402] cond->trig_tp: 1.
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:1411] dp:25 set new bool-val:1
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:2759] == 1 1`
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:2792] cond:1 strategy:1 curr_stat:1
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:2805] calc cond.and stat:2
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:1430] trig_tp : 1 [dp_exp is 1] , is_cond_only_judge : 0
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:1597] cond stat: 2.
   

2. Result of the linkage condition detection: true

   [09-17 18:17:53 TUYA D][condition.c:1660] conditions check begin
   [09-17 18:17:53 TUYA D][condition.c:1711] time_cond is disabled. skip
   [09-17 18:17:53 TUYA D][condition.c:1886] conditions check finish. result:true
   

3. action<0> indicates the first action in the linkage. Check if the action is sent to the sub-device. If so, it means the gateway has executed the scene.

   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:3522] in work-queue. execute scene:oxyOkOAYPolhVwhi begin
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:3543] rule oxyOkOAYPolhVwhi exe st:0
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:2535] action<0> is rule:EeOpIHKwYTSCZRPQ . begin to execute scene
   [09-17 18:17:53 TUYA D][scene_linkage_rule_exe.c:2475] action<0> is dp cmd:{"cid":"e0798dfffe6ed1f7","dps":{"26":true}}
   

   If the linkage is a Tap-to-Run task, you can skip step 1 and directly check if the action has been sent to the sub-device.

Common issues with failed LAN linkage

• The LAN’s instability causes frequent changes in its topology, leading to control failure.

  Search for lan_cluster_master_core.
  For example, node [%s] ip[%x] leave, where the content enclosed in [] is the node and IP address of the gateway. If this message appears in the log of the main gateway, it indicates the node leaves the LAN.

• When the gateway and the central control are in the same home, the central control serves as the main gateway for LAN linkage. However, if the central control is not using the latest firmware, it cannot deliver LAN messages to the gateway. Contact the central control manufacturer to update the central control.

Frequently triggering the scene switch causes the scene to be executed incorrectly

• Triggering scenes frequently within a short period of time results in throttling, causing only the last triggered scene to be executed.

• If a Zigbee sub-device is in the local scene, check the signal strength of the Zigbee network. A weak signal can cause Zigbee packets to be resent multiple times, resulting in a network storm. If there are multiple actions performed by Zigbee sub-devices in a scene, it is recommended to use the Zigbee standard scene.

Gateway failover

Gateway failover failed

Common issues with gateway failover

• The code for gateway failover is not implemented as described in the developer documentation. For more information, see Gateway Failover.
• The faulty gateway failed to upload the backup information to the cloud and remained online for less than 15 minutes before the fault occurred.
• During the replacement, the fault gateway did not go offline.
• The firmware version of the replaced gateway does not match the new gateway, or the Zigbee firmware is outdated.