Pegasus Pairing

Tuya Pegasus pairing is a one-device-one-key pairing solution built based on the beacon, probe request, and probe response frames specified in the IEEE 802.11 standard. The dynamic key and pairing data generated in the cloud ensure secure cloud connectivity. Pegasus pairing supports device pairing and seamless router replacement for paired devices.

Features

• Initial pairing: A paired device sends the Wi-Fi information to the device ready for pairing to achieve password-free pairing. The setup process is hassle-free for users who already have a Tuya-enabled device because pairing information input is not required.

• Auto-reconnect: If the router’s Wi-Fi password is changed, paired devices will disconnect. To get the device back online, the user usually needs to pair it again. With a router integrated with the Pegasus auto-reconnect feature, the offline device can automatically reconnect to the router without being paired again.

Terms

Pairing process

Initial pairing

Auto-reconnect

Development guide

Runtime environment

Open tuya_iot_config.h and check if the following macro is defined.

#define ENABLE_WIFI_PEGASUS 1

Development process

• Initial pairing: It has been integrated into the TuyaOS development framework, so custom development is not necessary. Check if the development framework in use supports the initial pairing feature. You can specify the parameter WF_START_SMART_AP_CONCURRENT during device initialization to trigger initial Pegasus pairing.

• Auto-reconnect: You need to implement this feature on the router device.

API description

This section describes the APIs used to implement the auto-reconnect feature.

Get the router’s Wi-Fi credentials

/**
* @brief get ssid and password
*
* @param[in] : slen   The length of the allocated memory to store the SSID.
* @param[in] : plen   The length of the allocated memory to store the password.
* @param[out] : ssid   The memory address of the SSID.
* @param[out] : passwd  The memory address of the password.
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_get_ssid_passwd(uint8_t *ssid, int32_t slen, uint8_t *passwd, int32_t plen);

Get the device’s MAC address

/* tuya sdk definition of MAC info */
typedef struct
{
    uint8_t mac[6]; /* mac address */
}NW_MAC_S;

/**
* @brief get mac address
*
* @param[out] : mac: mac address
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_get_mac(NW_MAC_S *mac);

Register Wi-Fi management frame callbacks

typedef void (*PEGASUS_REV_MGNT_CB)(uint8_t *vsie, uint32_t vsie_len, NW_MAC_S *src_mac, NW_MAC_S *dst_mac);

/**
* @brief register callback function for receive management frame
*
* @param[in] : enable   Specifies whether to enable the management frame callback. TRUE: Enable. FALSE: Disable.
* @param[in] : recv_cb   The management frame callback.
* @param[in] : tuya_oui   Tuya's OUI. This field is used to report VSIE that contains Tuya's OUI.
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_register_recv_mgnt_callback(bool enable, PEGASUS_REV_MGNT_CB recv_cb, uint8_t *tuya_oui);

Control VSIE beacons

/**
* @brief   config Beacon frame
*
* @param[in] : start     Specifies when to start sending the beacons that include the specified VSIE.
* @param[in] : vsie     The VSIE of the management frame.
* @param[in] : vsie_len   The length of the VSIE of the management frame.
* @param[in] : timeout   The timeout period of sending the specified beacon.
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_beacon_config(bool start, uint8_t *vsie, uint32_t vsie_len, uint32_t timeout);

Send VSIE probe response frames

/**
* @brief send probe response management frame
*
* @param[in] : vsie    The VSIE of the management frame.
* @param[in] : vsie_len   The length of the VSIE of the management frame.
* @param[in] : ssid     The SSID of the management frame.
* @param[in] : srcmac   The source MAC address of the management frame.
* @param[in] : srcmac   The destination MAC address of the management frame.
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
int tuya_hal_pegasus_send_probe_response_mgnt(const uint8_t *vsie, const uint32_t vsie_len, const uint8_t* ssid, NW_MAC_S *srcmac, NW_MAC_S *dstmac);

Limitations

• A client must be capable of sending IEEE 802.11-defined probe requests, receiving probe response and beacon frames, and processing VSIE organizationally unique identifier (OUI).

• A server must be capable of receiving IEEE 802.11-defined probe requests, sending probe response and beacon frames, and processing VSIE OUI.

FAQs

How do I know if the initial Pegasus pairing succeeds?

If the user can successfully add a device with a mobile app (such as the Smart Life app) without entering Wi-Fi credentials, it means the initial Pegasus pairing succeeds.

Is it possible to incorporate the auto-reconnect feature into devices other than a router?

No, it is not possible.

Changing the SSID and password of the router’s Wi-Fi will cause a device to disconnect from the router, which in turn triggers the auto-reconnect feature. This is why auto-reconnect can only be built into the router.