Bluetooth Devices

Tuya supports the following three Bluetooth connectivity topology options: Bluetooth Low Energy (LE), Tuya’s proprietary Bluetooth mesh connections (Tuya mesh), and Bluetooth mesh networking (Bluetooth mesh) provided by Bluetooth Special Interest Group (SIG). Smart Residence App SDK for Android supports these options to help you implement device control over Bluetooth.

Protocol category	Product example
Bluetooth LE	Body fat scales, wrist-worn trackers, thermostats, electric toothbrushes, smart locks, and burglar alarms
Bluetooth mesh	Cool white lights (C), cool and warm white lights (CW), white and colored lights (RGBCW), sockets, sensors, and other Bluetooth mesh sub-devices
Tuya mesh	Similar to the products that use Bluetooth mesh, but with Tuya mesh
Combo devices	Bluetooth mesh gateways, IP cameras (IPCs), and new devices that support Bluetooth and Wi-Fi combo

The following Bluetooth features are supported:

• Pairing

  • Scan for and discover devices
  • Pair devices

• Manage and control paired devices

  • Check current device networking status
  • Connect to a device
  • Operate devices
  • Unbind devices

Preparation

System requirements

Bluetooth connectivity requires Android 4.3 and later, and Tuya Smart Residence App SDK supports Android 4.4 and later.

Manifest permissions

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

Precheck of Bluetooth permissions

• Check whether the location permissions are enabled for an app before it uses Bluetooth connectivity or starts scanning.
• Check whether the Bluetooth feature is enabled.

This precheck is not provided by the Smart Residence App SDK. You can manually perform the precheck. This percheck is essential. Otherwise, the app cannot use Bluetooth connectivity as expected.

Scan for Bluetooth devices

Start scanning

Bluetooth devices to be paired broadcast Bluetooth packets. The SDK parses the packets with the protocol and discovers the target Powered by Tuya (PBT) Bluetooth LE devices and combo devices.

Bluetooth permissions must be prechecked. Scanning is allowed only after required permissions are granted.

1. Check whether Bluetooth is enabled.
2. Check whether the app is granted location permissions.

API description

void startLeScan(LeScanSetting setting, TyBleScanResponse response);

Parameters

Parameter	Type	Description
setting	LeScanSetting	The setting of the scanning feature.
response	TyBleScanResponse	The callback of the scanning result. It cannot be empty.

Builder class

LeScanSetting.Builder is used to build the settings for device scanning.

Method name	Parameter	Description	Required
setTimeout()	long	The timeout value of a pairing task. Default value: 40000. Unit: milliseconds.	No
addScanType()	ScanType	SINGLE: scan for Bluetooth LE devices MESH: scan for Tuya mesh devices SIG_MESH: scan for Bluetooth mesh devices	Yes
setRepeatFilter()	boolean	Specifies whether a repeat filter is enabled. Default value: true.	No

Example

LeScanSetting leScanSetting = new LeScanSetting.Builder()
        .setTimeout(60 * 1000) // The timeout value for a scanning task. Unit: milliseconds.
        .addScanType(ScanType.SINGLE) // `ScanType.SINGLE`: scans for Bluetooth LE devices.
        // `.addScanType(ScanType.SIG_MESH)`: scans for other types of devices.
        .build();

TuyaOSBLE.operator().startLeScan(leScanSetting, new TyBleScanResponse() {
    @Override
    public void onResult(ScanDeviceBean bean) {
        // The callback of the scanning result.
    }
});

Callback description

Properties of ScanDeviceBean

Property	Type	Description
id	String	The UUID that is used as a scanning ID to uniquely identify the device.
name	String	The name of the discovered Bluetooth device. The value is empty in most cases.
providerName	String	The name of a Bluetooth LE device provider. If your development is only targeted to Bluetooth LE devices, this field can be ignored.
data	byte[]	The raw data.
configType	String	config_type_single: Bluetooth LE device config_type_wifi: Bluetooth and Wi-Fi combo device
productId	String	The product ID.
uuid	String	The UUID that is used to uniquely identify the device.
mac	String	The media access control address (MAC address) of the device. It cannot be used as a unique code.
isbind	boolean	Indicates whether the device is activated. If a callback is executed, the device is inactivated.
flag	int	bit0: indicates whether a combo device supports the 5G Wi-Fi network. bit2: indicates whether a shared device is used. bit3: indicates whether a Bluetooth device can be paired with another device.
address	String	The IP address of the device.
deviceType	int	The type of device to distinguish different types of device protocols. This parameter can be ignored.

deviceType indicates the type of device to be paired and can be ignored. For more information about combo devices with Wi-Fi enabled, see subsequent instructions for pairing combo devices. For more information about Bluetooth devices, see subsequent instructions for pairing Bluetooth devices.

Value of deviceType	configType	The type of device.
200	config_type_single	Bluetooth device
300	config_type_single	Bluetooth device
301	config_type_wifi	Wi-Fi and Bluetooth combo device
304	config_type_wifi	Wi-Fi and Bluetooth combo device that supports pairing over Bluetooth if a Wi-Fi connection is unavailable
400	config_type_single	Bluetooth device
401	config_type_wifi	Wi-Fi and Bluetooth combo device
404	config_type_wifi	Wi-Fi and Bluetooth combo device that supports pairing over Bluetooth if a Wi-Fi connection is unavailable

Query a device name

Returns the name and icon of a discovered device.

API description

void getActivatorDeviceInfo(String productId, String uuid, String mac, ITuyaDataCallback<ConfigProductInfoBean> callback);

Parameters

Parameter	Type	Description
productId	String	ScanDeviceBean.getProductId
uuid	String	ScanDeviceBean.getUuid
mac	String	ScanDeviceBean.getMac is null for most devices and has values only for certain categories.

Example

TuyaOSActivator.deviceActivator().getActivatorDeviceInfo(
        scanDeviceBean.getProductId(), // productId
        scanDeviceBean.getUuid(), // uuid
        scanDeviceBean.getMac(), // mac
        new ITuyaDataCallback<ConfigProductInfoBean>() {
            @Override
            public void onSuccess(ConfigProductInfoBean result) {
                // Device information is returned.
            }

            @Override
            public void onError(String errorCode, String errorMessage) {
                // Failed to get device information.
            }
        }
);

Callback description

Properties of ConfigProductInfoBean

Property	Type	Description
name	String	The product name of the device. The value is set in the cloud. In most cases, it is the name used when you create the product.
icon	String	The icon of the product.

Stop scanning

Stops device scanning. For example, if a pairing page is exited or during a pairing process, scanning can be stopped, so that the overall process will not be slowed down by the scanning task.

API description

void stopLeScan();

Example

TuyaOSBLE.operator().stopLeScan();

Pair Bluetooth LE devices

Start pairing a Bluetooth LE device

If the configType property is config_type_single, a Bluetooth LE device is discovered. If it is config_type_wifi, a combo device is discovered.

API description

void startActivator(BleActivatorBean bleActivatorBean, IBleActivatorListener listener);

Parameters

Parameter	Type	Description
bleActivatorBean	BleActivatorBean	The collection of parameters for the target device.
listener	IBleActivatorListener	The callback of the pairing result.

BleActivatorBean stores the parameters and settings of the target device.

Property	Type	Description	Required
homeId	long	The current site ID.	Yes
uuid	String	The device UUID that is returned after scanning.	Yes
address	String	The device IP address that is returned after scanning.	No
productId	String	The product ID that is returned after scanning.	No
deviceType	Integer	The device type that is returned after scanning.	Yes
isShare	boolean	Indicates whether a shared device is used. The value is returned after scanning. Default value: false.	No
timeout	long	The timeout value of a pairing task. This parameter determines whether pairing failed. Unit: milliseconds. Default value: 60000.	No

Example

BleActivatorBean bleActivatorBean = new BleActivatorBean();

// `mScanDeviceBean`: returned by `ScanDeviceBean` in the scanning result callback.
bleActivatorBean.homeId = 123456; // homeId
bleActivatorBean.address = mScanDeviceBean.getAddress(); // The device IP address.
bleActivatorBean.deviceType = mScanDeviceBean.getDeviceType(); // The type of device.
bleActivatorBean.uuid = mScanDeviceBean.getUuid(); // The UUID.
bleActivatorBean.productId = mScanDeviceBean.getProductId(); // The product ID.

// Listens for the pairing result.
IBleActivatorListener listener = new IBleActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // The device is paired. The description of `DeviceBean` is the same as that for Wi-Fi device pairing. For more information, see the callback of Wi-Fi device pairing.
    }

    @Override
    public void onFailure(int code, String msg, Object handle) {
        // Failed to pair the device.
    }
};

// Starts pairing.
TuyaOSActivator.activator().newBleActivator().startActivator(bleActivatorBean, listener);

Stop pairing a Bluetooth LE device

Stops pairing during the pairing process.

API description

void stopActivator(String uuid);

Parameters

Parameter	Type	Description
uuid	String	The UUID of the discovered device. It is the same as the value of ScanDeviceBean.uuid

Example

TuyaOSBLE.manager().stopBleConfig("uuid");

Pair combo devices

Pair a combo device

Activates and pairs a combo device after it is discovered.
If the configType property is config_type_single, a Bluetooth LE device is discovered. If it is config_type_wifi, a combo device is discovered.

API description

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

Parameters

Parameter	Type	Description
multiModeActivatorBean	MultiModeActivatorBean	The collection of parameters for the target combo device.
listener	IMultiModeActivatorListener	Callback of the pairing result

Properties of MultiModeActivatorBean

Property	Type	Description
homeId	long	The ID of the site to which the target device is added.
deviceType	Integer	The device type that is returned after scanning.
uuid	String	The device UUID that is returned after scanning.
address	String	The device IP address that is returned after scanning.
mac	String	The device MAC address that is returned after scanning.
ssid	String	The service set identifier (SSID) of the target Wi-Fi network.
pwd	String	The password of the target Wi-Fi network.
token	String	The pairing token. You can call getActivatorToken to get the token in the same way as that for pairing Wi-Fi devices.
homeId	long	The value of homeId for the current site.
timeout	long	The timeout value of a pairing task. This parameter determines whether pairing failed. Unit: milliseconds.

If not stated, generic devices only support the 2.4 GHz Wi-Fi network. Other certain types of devices support the 5 GHz Wi-Fi network. ScanDeviceBean.flag indicates which type of network is supported.

token: the pairing token. You can call getActivatorToken to get the token in the same way as that for pairing Wi-Fi devices.

Example

MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();

// `scanDeviceBean` indicates the device information returned by the callback of the scanning result.
// The IP address of the target device.
multiModeActivatorBean.address = scanDeviceBean.getAddress();
// The UUID of the target device.
multiModeActivatorBean.uuid = scanDeviceBean.getUuid();
// The MAC address of the target device.
multiModeActivatorBean.mac = scanDeviceBean.getMac();
// The type of device.
multiModeActivatorBean.deviceType = scanDeviceBean.getDeviceType();
// The value of `homeId` for the target device.
multiModeActivatorBean.homeId = "homeId_xxx";
// The timeout value of the pairing task. Unit: milliseconds.
multiModeActivatorBean.timeout = 60 * 1000L;
// The pairing token generated in the cloud.
multiModeActivatorBean.token = "token_xxx";
// The SSID of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.ssid = "ssid_xxx";
// The password of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.pwd = "pwd_xxx";
// Listens for the pairing result.
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // The device is paired.
    }
    @Override
    public void onFailure(int code, String msg, Object handle) {
        // Failed to pair the device.
    }
};
// Starts pairing.
TuyaOSActivator.activator().newMultiModeActivator().startBleActivator(
        multiModeActivatorBean, listener);

Callback description

Properties of DeviceBean
For more information, see the data types of DeviceBean.

Stop pairing a combo device

Stops pairing during the pairing process. If the device has been activated in the cloud, it might be paired even after the pairing process is stopped.

API description

void stopActivator(String uuid);

Parameters

Parameter	Type	Description
devUuid	String	The UUID of the discovered device.

Example

TuyaOSActivator.activator().newMultiModeActivator().stopActivator("uuidxxxx");

Pair over Bluetooth due to unavailable Wi-Fi

Certain Wi-Fi and Bluetooth combo devices support pairing over Bluetooth if a Wi-Fi connection is unavailable. App users trigger cloud-based activation and required data is sent to a target device over Bluetooth. Then, the device attempts to connect to the target Wi-Fi network. If the device failed to be activated in the cloud, Bluetooth connections will be created between the device and the app on the mobile phone.

You can call the method getDeviceType() of ScanDeviceBean to check whether a discovered device supports this type of pairing capability. The return value 404 or 304 indicates that it is supported. Otherwise, it is not.

API description

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

Request parameters

MultiModeActivatorBean

Parameter	Type	Description
homeId	long	The ID of the site to which the target device is added.
uuid	String	The UUID of the target device.
deviceType	int	The type of device.
address	String	The IP address of the device.
timeout	long	The timeout value for pairing. Unit: milliseconds.
phase1Timeout	long	The timeout value for cloud-based activation. Unit: milliseconds. Default value: 60000.
ssid	String	The SSID of the target Wi-Fi network to which a paired device is connected.
pwd	String	The password of the target Wi-Fi network to which a paired device is connected. If no password is set, an empty string is passed.
token	String	The pairing token generated in the cloud to verify the account identity.
mac	String	The MAC address of the device.

If not stated, generic devices only support the 2.4 GHz Wi-Fi network. Other certain types of devices support the 5 GHz Wi-Fi network. ScanDeviceBean.flag indicates which type of network is supported.
The pairing token. You can call getActivatorToken to get the token.

Example

// `scanDeviceBean` indicates the details of the discovered Bluetooth LE device.
MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();
// The SSID of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.ssid = "SSID_xxx";
// The password of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.pwd = "pwd_xxx";
// The UUID of the device.
multiModeActivatorBean.uuid = scanDeviceBean.getUuid();
// The type of device.
multiModeActivatorBean.deviceType = scanDeviceBean.getDeviceType();
// The MAC address of a device.
multiModeActivatorBean.mac = scanDeviceBean.getMac();
// The IP address of the target device.
multiModeActivatorBean.address = scanDeviceBean.getAddress();
// The value of `homeId` for the target device.
multiModeActivatorBean.homeId = "homeId_xxx";
// The pairing token.
multiModeActivatorBean.token = "token_xxx";
// The timeout value for pairing. Unit: milliseconds.
multiModeActivatorBean.timeout = 120 * 1000L;
// The timeout value for cloud-based activation. Unit: milliseconds.
multiModeActivatorBean.phase1Timeout = 60 * 1000L;

// The callback of the pairing result.
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // The device is paired.
    }
    @Override
    public void onFailure(int code, String error, Object handle) {
        // Failed to pair the device.
    }
};

// Starts pairing.
IMultiModeActivator mMultiModeActivator = TuyaOSActivator.activator().newMultiModeActivator();
mMultiModeActivator.startActivator(multiModeActivatorBean, listener);

You can check whether a paired device is activated over Bluetooth due to the unavailable Wi-Fi connection. In this case, if the method getCommunicationOnline(CommunicationEnum.BLE) of DeviceBean returns true in the callback, the device supports this type of pairing and is locally connected to the app.

To check whether a device is activated in the cloud, call deviceBean.getMeta().get("wifiEnable") and get the Wi-Fi connection status. A value of true indicates that the cloud-based activation is successful.

Activate locally-connected combo device in cloud

A combo device is locally connected to the app over Bluetooth after it failed to connect to the Wi-Fi network. The following method helps you attempt to activate this device in the cloud through a Wi-Fi channel. In this call, the target device must be paired with the app over Bluetooth and cloud-based activation failed. You can call getCommunicationOnline(CommunicationEnum.BLE) of DeviceBean to check the Bluetooth connection status. To check whether a device is activated in the cloud, call deviceBean.getMeta().get("wifiEnable") and get the Wi-Fi connection status.

API description

void startWifiEnable(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

Parameters

Parameter	Type	Description
multiModeActivatorBean	MultiModeActivatorBean	The collection of parameters for the target device.
listener	IMultiModeActivatorListener	The callback.

Properties of MultiModeActivatorBean

Parameter	Type	Description
timeout	long	The timeout value for the attempt to reconnect the device to the Wi-Fi network and activate it in the cloud. Unit: milliseconds.
ssid	String	The SSID of the target Wi-Fi network to which a paired device is connected.
pwd	String	The password of the target Wi-Fi network to which a paired device is connected. If no password is set, an empty string is passed.
devId	Long	The device ID.

Example

MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();
multiModeActivatorBean.devId = "devId_xxx"; // The device ID.
multiModeActivatorBean.ssid = "ssid_xxx"; // The SSID of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.pwd = "pwd_xxx"; // The password of the target Wi-Fi network to which a paired device is connected.
multiModeActivatorBean.timeout = 120 * 1000L; // The timeout value for the Wi-Fi reconnection attempt. Unit: milliseconds.

// The callback.
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // The success callback.
    }
    @Override
    public void onFailure(int code, String msg, Object handle) {
        // The failure callback.
    }
};

// Starts the attempt.
TuyaOSActivator.activator().newMultiModeActivator().startWifiEnable(multiModeActivatorBean, listener);

Operate Bluetooth devices

This topic describes how to operate a paired Bluetooth LE device. For example, check the device status, connect to the device, or unbind it.

Overview

1. Query device status
2. Connect to a device.
3. Send commands to a device.
4. Modify the information about a device
5. Unbind a device

Query device status

Returns the online status by using the same method as that for a Wi-Fi device. If the Bluetooth device is added to a gateway, the device can stay online in the cloud.

TuyaOSDevice.getDataInstance().getDeviceBean(devId).getIsOnline();

Checks whether a device is locally connected over Bluetooth.

TuyaOSBLE.manager().isBleLocalOnline(devId);

In most cases of a Bluetooth device, you can care about only the local connection status. If the Bluetooth device is added to a Bluetooth gateway, the device status in the cloud must be checked.

Connect to a device

Connects to an offline device.

:::info This class is called in the main thread. :::

API description

void connectBleDevice(List<BleConnectBuilder> builderList);

Parameters

Parameter	Type	Description
builderList	List	A collection of BleConnectBuilder.

Builder class

BleConnectBuilder is used to build the settings for device connections.

Method name	Parameter	Description
setDirectConnect()	boolean	true: uses a cached connection to accelerate the process. false: does not use a cached connection.
setDevId()	String	The value of devId for the target device.
setScanTimeout()	Integer	The timeout value for scanning. Unit: milliseconds.
setLevel()	BleConnectBuilder.Level	NORMAL: If connection resources have reached the upper limit, the current connection is ignored. (Default value) FORCE: If connection resources have reached the upper limit, other resources are released to enable the current connection.

Example

List<BleConnectBuilder> builderList = new ArrayList<>();

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder(); // Stores the details of Device 1.
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder(); // Stores the details of Device 2.

bleConnectBuilder1.setDevId(devId1); // The value of `devId` for Device 1.
bleConnectBuilder2.setDevId(devId2); // The value of `devId` for Device 2.

builderList.add(bleConnectBuilder1); // Adds Device 1.
builderList.add(bleConnectBuilder2); // Adds Device 2.

TuyaOSBLE.manager().connectBleDevice(builderList); // Starts the connection task.

Disconnect a device

Closes a Bluetooth connection of a device.

:::info This class is called in the main thread. :::

API description

void disconnectBleDevice(List<BleConnectBuilder> builderList);

Parameters

Parameter	Type	Description
builderList	List	A collection of BleConnectBuilder.

Builder class

BleConnectBuilder is used to build the settings for device disconnections.

Method name	Parameter	Description
setDevId()	String	The value of devId for the target device.

Example

List<BleConnectBuilder> builderList = new ArrayList<>();

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder(); // Stores the details of Target device 1.
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder(); // Stores the details of Target device 2.

bleConnectBuilder1.setDevId("DevId_1"); // The value of `DevId` for Device 1.
bleConnectBuilder2.setDevId("DevId_2"); // The value of `DevId` for Device 2.
// More target devices are supported.

TuyaOSBLE.manager().connectBleDevice(builderList); // Starts the disconnection task.

Operate devices

Listens for device status by using the device operation class. Similar API methods as Wi-Fi devices are called. For more information, see Device Management

• Get device information

  For more information, see Get device information.

• Initialize device control

  For more information, see Initialize device control.

• Register a device listener

  For more information, see Register a device listener.

• Remove a device listener

  For more information, see Remove a device listener.

• Query data points (DPs) of devices

  For more information, see Query DPs of devices.

• Rename a devices

  For more information, see Rename a device.

• Remove a device

  For more information, see Remove a device.

Similar to a Wi-Fi device, to unbind a Bluetooth device, call
TuyaOSDevice.newDeviceInstance("devId").removeDevice() or resetFactory().
The difference is that the target Bluetooth device will be removed from the cloud and locally connected device list. If the device is locally online, it is automatically removed. If the device is offline, it is only removed from the cloud and is still bound with the app. To bind a device again after the unbinding operation, the device must be manually set to the state to be paired. During device scanning, if the SDK discovers the device in the bound state but disconnected from the cloud, the device will be automatically reset.

• Recycle device resources

  For more information, see Recycle device resources.

Error codes

Error code	Description
1	The format of the packet received by the device is wrong.
2	The device failed to find a router.
3	The password of the target Wi-Fi network is wrong.
4	The device failed to connect to a router.
5	Failed to get a DHCP-assigned IP address.
6	Failed to connect the device to the cloud.
100	The pairing process is canceled by the user.
101	An error has occurred while connecting to the device over Bluetooth.
102	An error has occurred while scanning for Bluetooth devices.
103	Failed to enable a Bluetooth channel.
104	Failed to query Bluetooth device information.
105	Failed to pair devices over Bluetooth.
106	The pairing task timed out.
107	Failed to send Wi-Fi information.
108	The specified token is invalid.
109	Failed to query the key with which Bluetooth connections are encrypted.
110	The specified device does not exist.
111	Failed to register the device in the cloud.
112	Failed to activate the device in the cloud.
113	The specified device has been bound in the cloud.
114	The current connection is manually closed.
115	Failed to query device information from the cloud.
116	The specified device is being paired in another mode.
117	The OTA update failed.
118	The OTA update timed out.
119	Failed to verify the parameters for Wi-Fi pairing.