Last Updated on : 2022-02-17 07:05:07download
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
Manage and control paired devices
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
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.
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.
- Check whether Bluetooth is enabled.
- 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 devicesMESH : scan for Tuya mesh devicesSIG_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 deviceconfig_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 |
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. |
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();
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);
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");
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.
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");
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()
ofScanDeviceBean
to check whether a discovered device supports this type of pairing capability. The return value404
or304
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 callgetActivatorToken
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)
ofDeviceBean
returnstrue
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 oftrue
indicates that the cloud-based activation is successful.
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);
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
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.
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.
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.
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()
orresetFactory()
.
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 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. |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback