AP Mode

This topic describes the access point (AP) or hotspot mode to pair devices. It is a connection capability for pairing over Wi-Fi. After a mobile phone is connected to the Wi-Fi hotspot of a target device, the device is paired and communicates with the mobile phone over Wi-Fi. With a high success rate and good reliability, this mode adapts to 2.4 GHz and 5 GHz dual-band routers. However, users need to manually switch between the Wi-Fi bands connected to the mobile phone.

Process of pairing in AP mode

Initialize pairing parameters

API description

ActivatorBuilder builder = new ActivatorBuilder()
        .setContext(context)
        .setSsid(ssid)
        .setPassword(password)
        .setActivatorModel(ActivatorModelEnum.TY_AP)
        .setTimeOut(timeout)
        .setToken(token)
        .setListener(new IThingSmartActivatorListener() {

                @Override
                public void onError(String errorCode, String errorMsg) {

                }

                @Override
                public void onActiveSuccess(DeviceBean devResp) {

                }

                @Override
                public void onStep(String step, Object data) {

                }
            }
        ));

Parameters

Parameter	Description
token	The pairing token.
context	The context to be set in activity.
ssid	The name of the Wi-Fi network to which a paired device is connected.
password	The password of the Wi-Fi network to which a paired device is connected.
activatorModel	The pairing mode. For example, the value is set to ActivatorModelEnum.TY_AP to represent the AP mode.
timeout	The timeout value of a pairing task. Default value: 100. Unit: seconds.

Get a token

Before the pairing process, the SDK must get a pairing token from the cloud in the networked state. The token is valid for 10 minutes and expires immediately after the device is paired. A new token must be generated if the device needs to be paired again.

API description

ThingHomeSdk.getActivatorInstance().getActivatorToken(homeId,
        new IThingActivatorGetToken() {

            @Override
            public void onSuccess(String token) {

            }

            @Override
            public void onFailure(String s, String s1) {

            }
        });

Parameters

Parameter	Description
homeId	The home ID. For more information, see Home Management.

Call the pairing method

IThingActivator mThingActivator = ThingHomeSdk.getActivatorInstance().newActivator(builder);
// Starts pairing.
mThingActivator.start();
// Stops pairing.
mThingActivator.stop();
// Exits the page and destroys certain caches and listeners.
mThingActivator.onDestroy();

New process of pairing in AP mode

To improve the user experience and success rate of pairing, Tuya provides a new pairing process that is available to the new device firmware version only.

Get list of security configurations

 ThingHomeSdk.getActivatorInstance().getDeviceSecurityConfigs(new IThingDataCallback<String>() {
            @Override
            public void onSuccess(String result) {
                securityConfig = result;
                // Security configurations are obtained.

            }

            @Override
            public void onError(String errorCode, String errorMessage) {

            }
        });

API description

ThingApActivatorBuilder builder = new ThingApActivatorBuilder().setContext(this);

Parameters

Parameter	Description
context	The context to be set in activity.

Sample request

IThingOptimizedActivator mThingActivator = ThingHomeSdk.getActivatorInstance().newOptimizedActivator(builder);

Query Wi-Fi networks discovered by device

Before this call, the SDK checks the device status first. If the device has a status exception, for example, an unknown state, the system will not query the Wi-Fi networks discovered by the device.

ApQueryBuilder queryBuilder = new ApQueryBuilder.Builder().setContext(context).setTimeout(queryParam.timeout == null ? 0 : queryParam.timeout * 1000).build();
mThingActivator.queryDeviceConfigState(queryBuilder, new IThingResultCallback<List<Wi-FiInfoBean>>() {
        @Override
        public void onSuccess(List<Wi-FiInfoBean> result) {
            // The list of Wi-Fi networks is obtained.
        }

        @Override
        public void onError(String errorCode, String errorMessage) {
            // Failed to get the list of Wi-Fi networks.
        }
    });

Parameters

ApQueryBuilder

Parameter	Description
context	The context to be set in activity.
timeout	This parameter is optional. If the value is larger than 0, the countdown for timeout is enabled. Unit: ms.

Wi-FiInfoBean

Parameter	Description
ssid	The name of the Wi-Fi network discovered by the device.
rssi	The Wi-Fi signal strength.
sec	The protocol value. Valid values: 0: WAAM_OPEN 1: WAAM_WEP 2: WAAM_WPA_PSK 3: WAAM_WPA2_PSK 4: WAAM_WPA_WPA2_PSK 5: WAAM_WPA_WPA3_SAE 6: WAAM_UNKNOWN After the list of Wi-Fi networks is returned, if users select a required Wi-Fi network, the system can verify the entered password beforehand according to the specified protocol value. For example, if sec is set to a value from 2 to 5, the length of the password must be at least eight characters. This mechanism helps improve the success rate.

Start pairing

You can display the returned list of Wi-Fi networks for users to choose from.

ApActivatorBuilder builder = new ApActivatorBuilder.Builder()
        .setSsid("ssid")
        .setPwd("password")
        .setTimeout(timeout)
        .setToken(token)
        .setSecurityConfig(securityConfig)
        .setListener(new IThingSmartActivatorListener() {
            @Override
            public void onError(String errorCode, String errorMsg) {
                // Failed to pair the device.
                // The error code. See the subsequent list of pairing error codes.
            }

            @Override
            public void onActiveSuccess(DeviceBean devResp) {
                // The device is paired.
            }

            @Override
            public void onStep(String step, Object data) {
                // The same as the original pairing parameters.
            }
        }).build();
mThingActivator.startActivator(builder);

Parameters

ApActivatorBuilder

Parameter	Description
ssid	The name of the Wi-Fi network to which a paired device is connected.
password	The password of the Wi-Fi network to which a paired device is connected.
token	The pairing token.
timeout	The timeout value of a pairing task. This parameter is required. Unit: ms.
securityConfig	The list of security configurations returned. This parameter is optional and used to indicate the security level of device pairing.

Restart pairing

Asks users to provide the correct Wi-Fi name and password, and restarts pairing if the entered password is incorrect.

During the pairing process, the SDK automatically connects to the hotspot of the device within a certain period. After the device is connected, the SDK gets and reports the device status. This feature is supported by the latest firmware version only.

ApHandlerBean bean = new ApHandlerBean.Builder()
               .setSsid("ssid")
               .setPassword("password")
               .build();
mThingActivator.resumeAPConfigWifi(bean);

Parameters

ApHandlerBean

Parameter	Description
ssid	The name of the Wi-Fi network to which a paired device is connected.
password	The password of the Wi-Fi network to which a paired device is connected.

Stop pairing

You need to manually call this API method when the pairing task is stopped or resources are destroyed.

mThingActivator.stopActivator();

Error codes

The following error codes occur while processing the device connection. The error messages can be obtained from the device.

Error code	Description
207201	Failed to create a connection channel with the device.
207206	An unknown state is returned during the query of device status.
207207	The device does not support the feature of getting Wi-Fi networks discovered.
207209	The pairing information received by the device is incorrect.
207210	The device failed to find a router after receiving the pairing information.
207211	The password in the pairing information received by the device is incorrect.
207212	The device failed to connect to a router after receiving the pairing information.
207213	Failed to get a Dynamic Host Configuration Protocol (DHCP)-assigned IP address after receiving the pairing information.
207214	An error has occurred while activating the device in the cloud.
207215	Failed to connect the device to the cloud.
207216	The request to activate the device failed.
207218	The request to activate the device in the cloud failed.
207219	Failed to connect to iot-dns in the cloud during device activation.
207220	The pairing task timed out.
207222	Failed to get the Wi-Fi networks of the device.