Automatic Network Switching

Background information

The TuyaOS Gateway SDK supports multiple network access methods, such as Ethernet and Wi-Fi. When accessing the network, the TuyaOS Gateway SDK binds with a specified network interface rather than relying on the system’s default route. For devices supporting both Ethernet and Wi-Fi networks, applications notify the SDK of the current network status via TKL_WIRED_STATUS_CHANGE_CB (Ethernet) and WIFI_EVENT_CB (Wi-Fi). Ethernet takes precedence over the Wi-Fi network.

This topic describes typical network connectivity issues encountered in real-world usage. These issues might affect device stability and end-user experience.

Analytics of typical issues

False offline

When a device gets a valid IP address on its Ethernet interface but cannot actually access the internet, applications might still report Ethernet as UP to the SDK. In this case, the SDK prioritizes the Ethernet interface for network access, even if the Wi-Fi interface can connect to the internet properly. This incorrect interface selection prevents the SDK from connecting to the Tuya Developer Platform, resulting in the device appearing offline.

Access point (AP) pairing timeout

If a device’s Ethernet interface gets a valid IP address but cannot access the internet, and applications report Ethernet as UP to the SDK, the SDK will bind with the Ethernet interface. In this case, if the end user attempts AP pairing, the pairing process will time out.

Solutions

The SDK’s support for network switching is disabled by default. Applications must call maq_set_connection_switch(TRUE) to enable it.

Implementation mechanism

After the network switching feature is enabled, if the current network link becomes unreachable when the SDK attempts to access the Tuya Developer Platform, it will automatically switch to the next available link and cycle through available interfaces.

Procedure

1. Confirm product configuration. The device must support both wired (Ethernet) and wireless (Wi-Fi) networks.
2. Modify code. In user_main.c, add mqc_set_connection_switch(TRUE) to the __gw_active_stat_cb callback function. Make sure __gw_active_stat_cb is triggered only when stat == GW_ACTIVED || stat == GW_NORMAL.
3. Verify features.
   • When Ethernet is functional, the SDK prioritizes it.
   • If Ethernet loses internet access, the SDK automatically fails over to the Wi-Fi network.

Things to note

• This feature only applies to hybrid (Ethernet + Wi-Fi) devices.
• Make sure the Wi-Fi network is properly configured to avoid switch failures.