AP Pairing

The device broadcasts an access point (AP). The mobile app connects to the device’s AP and sends the Wi-Fi credentials and pairing token to the device for activation.

TuyaOS SDK comes with the implementation of the business logic of the AP pairing process. It defines a set of TuyaOS Kernel Layer (TKL) that shields differences in hardware and system. The underlying hardware is controlled by the TKL interfaces that need to be implemented by you. This topic guides you through developing the Wi-Fi TKL interfaces.

Procedure

Development guide

Prerequisites

• You have a Tuya-enabled app, router, and device ready.
• The device supports two Wi-Fi modes: AP mode and station mode.

How to use

During the pairing process, the SDK should get and switch between wireless operation modes, turn on/off the Wi-Fi AP, connect to the router, get the wireless connection status, and get the IP address of the wireless network interface. You need to adapt the following TKL interfaces.

• tkl_wifi_init

  OPERATE_RET tkl_wifi_init(WIFI_EVENT_CB cb);
  

  The SDK calls this interface during initialization. The parameter of this interface is the pointer to the notification callback invoked when the wireless connection status changes. The application should monitor the wireless connection status in real time. Changes in wireless connection status can be passed to the SDK using the pointer to the notification callback.

  For example, when the device is connected to the router’s Wi-Fi network and assigned an IP address, cb(WFE_CONNECTED, NULL) is invoked. When the device failed to connect to the router’s Wi-Fi network, cb(WFE_CONNECT_FAILED, NULL) is invoked. When the device disconnects from the router’s Wi-Fi network, cb(WFE_DISCONNECTED, NULL) is invoked.

• tkl_wifi_scan_ap

  OPERATE_RET tkl_wifi_scan_ap(CONST SCHAR_T *ssid, AP_IF_S **ap_ary, UINT_T *num)
  

  The SDK proactively call this interface when Bluetooth starts broadcasting. This interface is used to scan the current environment and obtain all APs, and pass them to the app. Your application needs to implement the function in this interface.

• tkl_wifi_start_ap

  OPERATE_RET tkl_wifi_start_ap(CONST WF_AP_CFG_IF_S *cfg);
  

  If the device is unpaired on initialization, the SDK calls this interface to turn on the Wi-Fi AP on the device. This way, the mobile phone can connect to this AP and send the token for pairing to the device over LAN. Your application should be able to start the AP in this interface.

• tkl_wifi_stop_ap

  OPERATE_RET tkl_wifi_stop_ap(VOID_T);
  

  The SDK calls this interface to turn off the AP when the pairing is finished. Your application should be able to turn off the AP in this interface.

• tkl_wifi_get_mac

  OPERATE_RET tkl_wifi_get_mac(CONST WF_IF_E wf, NW_MAC_S *mac)
  

  This interface is called when the SDK is started. The AP name sent by the device is suffixed with the last four digits of the MAC address.

• tkl_wifi_set_work_mode

  OPERATE_RET tkl_wifi_set_work_mode(CONST WF_WK_MD_E mode);
  

  The SDK calls this interface to switch between wireless operation modes. Typically, the SDK calls this interface before tkl_wifi_stop_ap to set the AP mode or before tkl_wifi_station_connect to set the station mode. Your application should be able to switch to the wireless operation mode based on the parameter mode.

• tkl_wifi_get_work_mode

  OPERATE_RET tkl_wifi_get_work_mode(WF_WK_MD_E *mode);
  

  The SDK calls this interface to get the wireless operation mode. The returned operation mode must be consistent with that set by tkl_wifi_set_work_mode. Otherwise, this might affect the pairing process.

• tkl_wifi_station_connect

  OPERATE_RET tkl_wifi_station_connect(CONST SCHAR_T *ssid,  CONST SCHAR_T *passwd);
  

  The SDK calls this interface when it receives the token for pairing from the mobile app. Your application should be able to connect to the router in this interface.

• tkl_wifi_station_disconnect

  OPERATE_RET tkl_wifi_station_disconnect(VOID_T);
  

  The SDK calls this interface to disconnect from the router. Your application should be able to disconnect from the router in this interface.

• tkl_wifi_station_get_status

  OPERATE_RET tkl_wifi_station_get_status(WF_STATION_STAT_E *stat);
  

  The SDK calls this interface to get the wireless connection status. The SDK triggers the pairing process only when it receives the status WSS_GOT_IP. When the device is connected to the router’s Wi-Fi network and assigned an IP address, WSS_GOT_IP should be returned.

• tkl_wifi_get_ip

  OPERATE_RET tkl_wifi_get_ip(CONST WF_IF_E wf, NW_IP_S *ip);
  

  The SDK calls this interface to get the IP address of the current wireless network interface. In this interface, your application should get the IP address of the AP mode or station mode based on the parameter wf.

  The above are the interfaces that must be implemented for AP pairing. For more information about how to implement other TKL interfaces, see Port TuyaOS to Linux Platforms.

Device development

Set the pairing mode to AP pairing.

GW_WF_START_MODE mode = WF_START_AP_ONLY;

Things to note

• When starting AP pairing, the SDK gets the IP address in the Wi-Fi driver to confirm whether the Wi-Fi driver is working properly. The tkl_wifi_get_ip interface of the Wi-Fi adaptation layer needs to reply with a default IP address to the SDK. If the Wi-Fi driver does not have a default IP address, the return value is 0. Otherwise, the SDK will consider an anomaly occurs in the Wi-Fi driver and thus terminate the pairing process. The following errors will be output in the logs:

  

• When the tkl_wifi_start_ap interface is adapted, all members of the struct pointer parameter sent by the TuyaOS SDK must be set to the Wi-Fi driver. The adaptation layer cannot be modified at will. If the IP address in the struct pointer parameter sent by TuyaOS SDK is 192.168.176.1, then the IP address sent by the AP must be 192.168.176.1. Otherwise, the AP pairing protocol sent by the mobile app will be inconsistent with the TuyaOS SDK, leading to pairing failure. The following errors will be output in the logs:

  

• The Wi-Fi driver might have its default IP address before switching to the station mode. After the device is connected to the router’s Wi-Fi network, replace the IP address in the tkl_wifi_get_ip interface of the Wi-Fi adaptation layer with the IP address assigned by the router. Otherwise, issues such as pairing timeout might occur.

• Do not block any of the interfaces you have adapted. It is recommended to process time-consuming tasks asynchronously. Otherwise, issues such as pairing timeout might occur.

• Return value of the interface: Except for the interface used to get the IP address, when the adapted interfaces return values other than 0, the pairing operation will be terminated. In the Wi-Fi adaptation layer interface, if no actual error is reported by the Wi-Fi driver, the return value must be 0.

• Moreover, the SDK regularly calls tkl_wifi_station_get_status to check for wireless connection status. This interface should return a response within one second.