AP Mode

Last Updated on : 2023-07-07 08:08:11download

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 app 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

AppDeviceCloudConnect to routerWi-Fi LED indicator blinks slowlyRequest a tokenReturn a tokenConnect to hotspot of deviceStart pairing and send token and router SSID/passwordAuto turn off hotspotConnect to Wi-Fi network of routerReconnect to routerPoll for device ready for pairing with the token at an interval of 2s within 100sActivate the deviceDevice activatedDevice activated, list of activated devices returnedAppDeviceCloudAP 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.

The TuyaOS version of the firmware built into the target device must be v3.6.1 or later.

AppDeviceCloudConnect to routerWi-Fi LED indicator blinks slowlyRequest a tokenReturn a tokenConnect to hotspot of deviceGet Wi-Fi networks discovered by deviceReturn Wi-Fi networksSelect a Wi-Fi networkStart pairing and send token and router SSID/passwordAuto turn off hotspot1. If the password is incorrect, connection to router failed or hotspot is restartedConnect to hotspot and get pairing status within specified periodRestart pairing according to pairing statusResend token and router SSID/passwordPoll for device ready for pairing with the token at an interval of 2s2. Router is connectedActivate the deviceDevice activatedDevice activated, list of activated devices returnedAppDeviceCloudNew Process of AP Mode

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.