TuyaOSNetworked Product FrameworkCapability MapPairing Mode

Pairing Mode

Last Updated on : 2023-12-19 08:36:57download

Multiple device pairing solutions are available on TuyaOS development frameworks, such as AP pairing, Bluetooth pairing, and Pegasus pairing. How a device starts, stops, or sets up the pairing solution varies by scenario. TuyaOS development frameworks define multiple pairing modes to fit different use cases.

Feature description

The configuration of the device pairing mode allows you to set the pairing mode and pairing startup mode.

In pairing mode, low power refers to turning off the radio module rather than putting the chip into sleep mode.

Power-on pairing

Device status	Description
Unpaired	The device enters the pairing mode when it is powered on.
Ready for pairing or being paired	The device stays in pairing mode.
Removed after activation	The device enters the pairing mode.

Power-on low power

Device status	Description
Unpaired	The device enters the low power mode when it is powered on. You can call the reset API to put the device into the pairing mode.
Ready for pairing or being paired	If the device is not paired within the specified time (3 minutes by default), it enters the low power mode automatically. In this case, if the device is restarted, the state it enters depends on the pairing time. If the pairing time is less than 10 seconds, the device restores to the last pairing state. If the pairing time exceeds 10 seconds, the device enters the low power mode.
Removed after activation	The device enters the pairing mode.

Power-on pairing and low power

Device status	Description
Unpaired	The device enters the pairing mode when it is powered on.
Ready for pairing or being paired	If the device is not paired within the specified time (3 minutes by default), it enters the low power mode automatically.
Removed after activation	The device enters the pairing mode.

Power-on low power and auto-reconnect

Device status	Description
Unpaired	The device enters the low power mode when it is powered on. You can call the reset API to put the device into the pairing mode.
Ready for pairing or being paired	The device enters the pairing mode after it is removed locally: If the device is not paired within the specified time (3 minutes by default), it automatically connects to the last network used. In this case, if the device is restarted, the state it enters depends on the pairing time. If the pairing time is less than 10 seconds, the device restores to the last pairing state. If the pairing time exceeds 10 seconds, the device automatically connects to the last network used. The device enters the pairing mode either when it is not paired or is removed remotely: If the device is not paired within the specified time (3 minutes by default), it enters the low power mode automatically. In this case, if the device is restarted, the state it enters depends on the pairing time. If the pairing time is less than 10 seconds, the device restores to the last pairing state. If the pairing time exceeds 10 seconds, the device enters the low power mode.
Removed after activation	The device enters the pairing mode.

Power-on pairing, low power, and auto-reconnect

Device status	Description
Unpaired	The device enters the pairing mode when it is powered on.
Ready for pairing or being paired	The device enters the pairing mode after it is removed locally: If the device is not paired within the specified time (3 minutes by default), it automatically connects to the last network used. In this case, if the device is restarted, the state it enters depends on the pairing time. If the pairing time is less than 10 seconds, the device restores to the last pairing state. If the pairing time exceeds 10 seconds, the device automatically connects to the last network used. The device enters the pairing mode either when it is not paired or is removed remotely: If the device is not paired within the specified time (3 minutes by default), it enters the low power mode automatically. In this case, if the device is restarted, the state it enters depends on the pairing time. If the pairing time is less than 10 seconds, the device restores to the last pairing state. If the pairing time exceeds 10 seconds, the device enters the low power mode.
Removed after activation	The device enters the pairing mode.

Pairing startup mode

TuyaOS v3.4.0 and later do not support pairing in EZ mode. If you choose startup in EZ mode and startup in AP mode, the device will use startup in universal pairing mode instead.

Pairing startup mode	Description
AP mode only	The device supports AP mode only. It still starts up in AP mode after a reset.
EZ mode only	The device supports EZ mode only. It still starts up in EZ mode after a reset.
Startup in AP mode	The device enters AP mode on startup and enters EZ mode after a reset. It alternates between these two modes with a reset.
Startup in EZ mode	The device enters EZ mode on startup and enters AP mode after a reset. It alternates between these two modes with a reset.
Universal pairing	Any pairing solution can work, including AP pairing, EZ pairing, Pegasus pairing, and FFS pairing.

Bluetooth pairing is different from any other pairing solution. As long as the Bluetooth service and Bluetooth pairing are enabled, the framework will automatically turn on Bluetooth pairing.

Data structure

Definition of pairing mode

Macro definition	Pairing mode	Remarks
GWCM_OLD / GWCM_OLD_PROD	Power-on pairing	With the `GWCM_OLD_PROD` mode, the device will scan for the designated beacon specified for end-product testing on startup. In TuyaOS v3.0.0 and later, scanning for the designated beacon is implemented by you.
GWCM_LOW_POWER	Power-on low power	-
GWCM_SPCL_MODE	Power-on low power and auto-reconnect	-
GWCM_LOW_POWER_AUTOCFG	Power-on pairing and low power	-
GWCM_SPCL_AUTOCFG	Power-on pairing, low power, and auto-reconnect	-

/* tuya sdk definition of wifi work mode */
typedef BYTE_T GW_WF_CFG_MTHD_SEL; // wifi config method select
#define GWCM_OLD                0   // do not have low power mode
#define GWCM_LOW_POWER          1   // with low power mode
#define GWCM_SPCL_MODE          2   // special with low power mode
#define GWCM_OLD_PROD           3   // GWCM_OLD mode with product
#define GWCM_LOW_POWER_AUTOCFG 4   // with low power mode && auto cfg
#define GWCM_SPCL_AUTOCFG       5   // special with low power mode && auto cfg

Definition of pairing startup mode

Macro definition	Pairing startup mode	Remarks
WF_START_AP_ONLY	AP mode only	-
WF_START_SMART_ONLY	EZ mode only	TuyaOS v3.4.0 and later do not support pairing in EZ mode. The universal pairing mode is used instead.
WF_START_AP_FIRST	Startup in AP mode	-
WF_START_SMART_FIRST	Startup in EZ mode	TuyaOS v3.4.0 and later do not support pairing in EZ mode. The universal pairing mode is used instead.
WF_START_SMART_AP_CONCURRENT	Universal pairing	-

/* tuya sdk definition of wifi start mode */
typedef BYTE_T GW_WF_START_MODE;
#define WF_START_AP_ONLY        0   // only have ap-cfg mode
#define WF_START_SMART_ONLY     1   // only have smart-cfg mode
#define WF_START_AP_FIRST       2   // have both ap-cfg and smart-cfg. default is ap-cfg mode
#define WF_START_SMART_FIRST    3   // have both ap-cfg and smart-cfg. default is smart-cfg mode
#define WF_START_SMART_AP_CONCURRENT    4   // ap-cfg and smart-cfg is concurrent

How to

You can set the pairing mode by specifying the corresponding parameters in the device initialization interface.

API description

Set pairing timeout

Specify the time that will elapse before pairing times out. If the device is not paired within the specified time, the framework will terminate pairing and put the device into a state based on the pairing mode.

/**

 * @brief Set wifi netcfg timeout value in seconds
 *
 * @param[in] timeout_s time out value of netcfg.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */

VOID set_wf_netcfg_timeout(UINT_T timeout_s)

Prev DocEnd Product Testing – LAN

Next DocAP Pairing