Bluetooth LE Devices

This topic describes the technology to create a peer-to-peer connection between a Bluetooth or Bluetooth Low Energy (LE) device and a mobile phone.

Preparation

• System requirements: Bluetooth connectivity requires Android 4.3 and later, and the Smart Life 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 percheck is essential. Otherwise, the app cannot use Bluetooth connectivity as expected.
  • 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 Life App SDK. You can manually perform the precheck.

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 Bluetooth LE devices and combo devices.

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	Type	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 SINGLE_QR: scan a QR code for pairing	Yes
setRepeatFilter()	Boolean	Specifies whether a repeat filter is enabled. Default value: true.	No

Example

LeScanSetting scanSetting = new LeScanSetting.Builder()
		.setTimeout(60000) // The duration of the scanning. Unit: milliseconds.
		.addScanType(ScanType.SINGLE) // `ScanType.SINGLE`: scans for Bluetooth LE devices.
		// `.addScanType(ScanType.SIG_MESH)`: scans for other types of devices.
		.build();

// Starts scanning.
TuyaHomeSdk.getBleOperator().startLeScan(scanSetting, 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 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. A value of SingleBleProvider means that your development is only targeted to Bluetooth LE devices and this field can be ignored.
data	byte[]	The raw data.
configType	String	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.
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 5 GHz Wi-Fi network. bit2: indicates whether a shared device is used. bit3: indicates whether to support pairing over Bluetooth due to unavailable Wi-Fi connections. bit4: indicates whether QR code scanning is required to pair the 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. 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	Device type
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

TuyaHomeSdk.getActivatorInstance().getActivatorDeviceInfo(
	scanDeviceBean.getProductId(),
	scanDeviceBean.getUuid(),
	scanDeviceBean.getMac(),
	new ITuyaDataCallback<ConfigProductInfoBean>() {
		@Override
		public void onSuccess(ConfigProductInfoBean result) {

		}

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

		}
});

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

TuyaHomeSdk.getBleOperator().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 home 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.
bleActivatorBean.isShare = (mScanDeviceBean.getFlag() >> 2) & 0x01 == 1;// The flag that indicates whether the device is a shared one.

// Starts pairing.
TuyaHomeSdk.getActivator().newBleActivator().startActivator(bleActivatorBean, new IBleActivatorListener() {
	@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.
	}
});

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

TuyaHomeSdk.getBleManager().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	The callback of the pairing result.

Properties of MultiModeActivatorBean

Property	Type	Description
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 current home ID.
timeout	long	The timeout value of a pairing task. This parameter determines whether pairing failed. Unit: milliseconds.

Example

MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();

// `mScanDeviceBean`: returned by `ScanDeviceBean` in the scanning result callback.
multiModeActivatorBean.deviceType = mScanDeviceBean.getDeviceType(); // The type of device.
multiModeActivatorBean.uuid = mScanDeviceBean.getUuid(); // The UUID of the device.
multiModeActivatorBean.address = mScanDeviceBean.getAddress(); // The IP address of the device.
multiModeActivatorBean.mac = mScanDeviceBean.getMac(); // The MAC address of the device.
multiModeActivatorBean.ssid = "WIFI_2.4G"; // The SSID of the target Wi-Fi network.
multiModeActivatorBean.pwd = "WIFI_PASSWORD"; // The password of the target Wi-Fi network.
multiModeActivatorBean.token = "abcd1234"; // The pairing token.
multiModeActivatorBean.homeId = ; // The value of `homeId` for the current site.
multiModeActivatorBean.timeout = 120000; // The timeout value.

// Starts pairing.
TuyaHomeSdk.getActivator().newMultiModeActivator().startActivator(multiModeActivatorBean, 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.
	}
});

Callback description

• DeviceBean: the type of device data. For more information, see Data model of DeviceBean.

• Object handle: The response type of handle is the entity object ConfigErrorBean. The parameters are described in the following table.

  Parameter	Type	Description
  name	String	The name of the device.
  errorCode	String	The error code.
  devId	String	The device ID.
  iconUrl	String	The URL of a device icon.
  errorMsg	String	The error message.

Stop pairing a combo device

API description

TuyaHomeSdk.getActivator().newMultiModeActivator().stopActivator(uuid);

Parameters

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

Example

TuyaHomeSdk.getActivator().newMultiModeActivator().stopActivator("uuidxxxx");

Pair over Bluetooth due to unavailable Wi-Fi

Certain combo devices support pairing over Bluetooth if Wi-Fi connections are unavailable. 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.

API description

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

Properties of MultiModeActivatorBean

Parameter	Type	Description
homeId	long	The ID of the home 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. You can call getActivatorToken to get the token in the same way as that for pairing Wi-Fi devices.
mac	String	The MAC address of the device.

Example

// `scanDeviceBean` indicates the device information returned by the callback of the scanning result.
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 pairing over Wi-Fi only. 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.
TuyaHomeSdk.getActivator().newMultiModeActivator().startActivator(multiModeActivatorBean, listener);

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.

1. You can call getCommunicationOnline(CommunicationEnum.BLE) of DeviceBean to check the Bluetooth connection status.

2. 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.

Parameters 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.
TuyaHomeSdk.getActivator().newMultiModeActivator().startWifiEnable(multiModeActivatorBean, listener);

Operate Bluetooth devices

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

Check online status of a device

• Method 1: 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.

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

• Method 2: checks whether a device is locally connected over Bluetooth. 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.

  TuyaHomeSdk.getBleManager().isBleLocalOnline(devId);
  

Connect to an offline device

API description

void connectBleDevice(List<BleConnectBuilder> builderList);

Parameters

Parameter	Type	Description
builderList	List	A collection of BleConnectBuilder that is used to build the settings for device connections.

Description of BleConnectBuilder

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. FORCE: If connection resources have reached the upper limit, other resources are released to enable the current connection. Default value: NORMAL

Example

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

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder();
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder();

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.

TuyaHomeSdk.getBleManager().connectBleDevice(builderList); // Starts the connection task.

Disconnect a device

API description

void disconnectBleDevice(List<BleConnectBuilder> builderList);

Parameters

Parameter	Type	Description
builderList	List	BleConnectBuilder is used to build the settings for device disconnections.

Description of BleConnectBuilder

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

Example

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

builderList.add(new BleConnectBuilder().setDevId(devId1)); // The value of `devId` for Device 1.
builderList.add(new BleConnectBuilder().setDevId(devId2)); // The value of `devId` for Device 2.

TuyaHomeSdk.getBleManager().disconnectBleDevice(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. The following operations are supported:

• Query device information

• Initialize device control

• Register a device listener

• Unregister a device listener

• Data points of devices

• Rename a devices

• Remove a device

  Similar to a Wi-Fi device, to unbind a Bluetooth device, call TuyaHomeSdk.newDeviceInstance("devId").removeDevice() or resetFactory(). However, the following differences must be noted:

  • The target Bluetooth device will be removed from the cloud and locally connected device list. 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

Firmware update

Firmware information must be checked before the over-the-air (OTA) update.

Check firmware information

API description

void requestUpgradeInfo(String devId, IRequestUpgradeInfoCallback callback);

Parameters

Parameter	Type	Description
devId	String	The value of devId for the target device.
callback	IRequestUpgradeInfoCallback	The callback.

Example

TuyaHomeSdk.getMeshInstance().requestUpgradeInfo(mDevID, new IRequestUpgradeInfoCallback() {
	@Override
	public void onSuccess(ArrayList<BLEUpgradeBean> bleUpgradeBeans) {

	}

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

BLEUpgradeBean returns the firmware update information as described in the following table.

Field	Type	Description
upgradeStatus	Integer	The update status. Valid values: 0: no update available 1: update available 2: updating
version	String	The target firmware version.
currentVersion	String	The current version.
timeout	Integer	The timeout value. Unit: seconds.
upgradeType	Integer	0: app notification of update 2: forced app update 3: check for update
type	Integer	The type of module. Valid values: 0: Wi-Fi module 1: Bluetooth module 2: GPRS module 3: Zigbee module 9: MCU
typeDesc	String	The description of the update module.
lastUpgradeTime	long	The duration of the latest update. Unit: milliseconds.
url	String	The URL to download the new firmware. This parameter has a value when type is 1 or 9.
fileSize	long	The size of the new firmware.
md5	String	The MD5 (Message-Digest algorithm 5) hash value of the firmware.

Perform OTA update

Starts the OTA update after the available firmware update is downloaded.

API description

void startBleOta(String uuid, int type, String version, String binPackagePath, OnBleUpgradeListener listener);

Parameters

Parameter	Type	Description
uuid	String	The UUID of the target device. You can call deviceBean.getUuid() to get the value.
type	int	The type of update. Valid values: 0: Bluetooth firmware update, BLEUpgradeBean.type = 1. 1: MCU update, BLEUpgradeBean.type = 9.
version	String	The version number of the new firmware.
binPackagePath	String	The path of the downloaded firmware.
listener	OnBleUpgradeListener	The callback of the update progress.

TuyaHomeSdk.getBleManager().startBleOta(uuid, type, version, binPackagePath, new  OnBleUpgradeListener() {
	@Override
	public void onUpgrade(int percent) {
		// The progress of the firmware update.
	}

	@Override
	public void onSuccess() {
		// The firmware is updated.
	}

	@Override
	public void onFail(String errorCode, String errorMsg) {
		// Failed to update the firmware.
	}
});

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	Indicates that 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 in 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.