Last Updated on : 2023-03-29 02:40:45download
This topic describes the implementation of communication over Bluetooth based on Tuya’s proprietary mesh networking technology, also known as Tuya mesh. Each Tuya mesh device serves as a child node, and multiple mesh devices form a mesh network, in which the child nodes communicate with each other by advertising. App users can access one of the mesh devices to access and control all devices on the mesh network. This topic provides the development guidance on pairing, control, and management of devices that use Tuya mesh. For more information about Bluetooth mesh concepts, see Bluetooth Mesh.
<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" />
This precheck is not provided by the Smart Life App SDK. You can manually perform the precheck.
A home can belong to multiple mesh networks, but one mesh network is recommended for each home.
API description
void createBlueMesh(String meshName, ITuyaResultCallback<BlueMeshBean> callback);
Parameters
Parameter | Type | Description |
---|---|---|
meshName | String | The name of a mesh network, with up to 16 bytes. |
callback | ITuyaResultCallback | The callback. |
Example
TuyaHomeSdk.newHomeInstance("homeId").createBlueMesh("meshName", new ITuyaResultCallback<BlueMeshBean>() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess(BlueMeshBean blueMeshBean) {
}
});
API description
void removeMesh(IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
callback | IResultCallback | The callback. |
Example
TuyaHomeSdk.newBlueMeshDeviceInstance(meshId).removeMesh(new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
API description
List<BlueMeshBean> getMeshList();
Example
ITuyaHome mTuyaHome = TuyaHomeSdk.newHomeInstance("homeId");
if (mTuyaHome.getHomeBean() != null){
List<BlueMeshBean> meshList = mTuyaHome.getHomeBean().getMeshList();
BlueMeshBean meshBean= meshList.get(0);
}
API description
List<DeviceBean> getMeshSubDevList();
Example
List<DeviceBean> meshSubDevList = TuyaHomeSdk.newBlueMeshDeviceInstance("meshId").getMeshSubDevList();
We recommend that you destroy the current mesh instance and initialize the mesh instance for the target home when you switch between homes.
API description
// Initializes the mesh network.
TuyaHomeSdk.getTuyaBlueMeshClient().initMesh(String meshId);
// Destroys the current mesh network.
TuyaHomeSdk.getTuyaBlueMeshClient().destroyMesh();
ITuyaBlueMeshClient
provides API methods to start a connection, close a connection, start scanning, and stop scanning.
API description
// Starts a connection.
TuyaHomeSdk.getTuyaBlueMeshClient().startClient(mBlueMeshBean);
// Closes a connection.
TuyaHomeSdk.getTuyaBlueMeshClient().stopClient();
// Starts scanning.
TuyaHomeSdk.getTuyaBlueMeshClient().startSearch()
// Stops scanning.
TuyaHomeSdk.getTuyaBlueMeshClient().stopSearch();
After a connection is started, available devices are scanned for in the background until a device is connected. The background scanning will consume resources. You can start and stop scanning to control the background scanning.
startClient()
is called, the API methods of startSearch()
and stopSearch()
are invalid.startSearch()
and stopSearch()
are also invalid.Mesh devices to be paired are classified into:
A common Tuya mesh device that runs without a gateway, also known as a mesh sub-device
A mesh gateway
Common mesh sub-devices include smart lights, smart sockets, and low-power products. All mesh devices without mesh gateway capabilities can be regarded as common Tuya mesh devices.
The default name of a device in the reset state is out_of_mesh
and the default password is 123456
. The following list describes common device resetting methods.
Product category | Reset method | State pending pairing |
---|---|---|
Lighting | Turn on and off the light consecutively three times in a row | The indicator is flickering quickly. |
Socket | Tap and hold the switch for three seconds | The indicator is flickering quickly. |
Gateway product | Tap and hold the switch for three seconds | The red and blue indicators are flickering quickly. |
Low-power device | Tap and hold the switch for three seconds | Press the switch once again to see that the indicator is steady on. The pairing process must be completed when the indicator is on. |
Alarm | Tap and hold the switch for three seconds | The indicator is flickering quickly. |
You must check Bluetooth and location permissions and then start scanning for mesh devices pending pairing.
API description
// Starts scanning.
void startSearch();
// Stops scanning.
void stopSearch();
Example
ITuyaBlueMeshSearchListener iTuyaBlueMeshSearchListener = new ITuyaBlueMeshSearchListener() {
@Override
public void onSearched(SearchDeviceBean deviceBean) {
}
@Override
public void onSearchFinish() {
}
};
SearchBuilder searchBuilder = new SearchBuilder()
// The name of the device to be scanned for. Default value: `out_of_mesh` to represent the name of the device in the pairing state.
.setMeshName("out_of_mesh")
.setTimeOut(100) // The duration of the scanning. Unit: seconds.
.setTuyaBlueMeshSearchListener(iTuyaBlueMeshSearchListener).build();
ITuyaBlueMeshSearch mMeshSearch = TuyaHomeSdk.getTuyaBlueMeshConfig().newTuyaBlueMeshSearch(searchBuilder);
// Starts scanning.
mMeshSearch.startSearch();
// Stops scanning.
mMeshSearch.stopSearch();
API description
// Starts pairing.
void startActivator();
// Stops pairing.
void stopActivator();
Parameters
Parameter | String | Description |
---|---|---|
mSearchDeviceBeans | List | The set of devices pending pairing. |
timeout | Int | The timeout value of a pairing task. Default value: 100 . Unit: seconds. |
ssid | String | The name of the home Wi-Fi network to which a paired device is connected. |
password | String | The password of the home Wi-Fi network to which a paired device is connected. |
mMeshBean | MeshBean | MeshBean |
homeId | Long | The home to which the mesh network of the paired device belongs. |
version | String |
|
Example
// Pairs a common mesh device.
TuyaBlueMeshActivatorBuilder tuyaBlueMeshActivatorBuilder = new TuyaBlueMeshActivatorBuilder()
.setSearchDeviceBeans(foundDevices)
.setVersion("1.0")
.setBlueMeshBean(mMeshBean)
.setTimeOut(timeOut)
.setTuyaBlueMeshActivatorListener(new ITuyaBlueMeshActivatorListener() {
@Override
public void onSuccess(DeviceBean deviceBean) {
}
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onFinish() {
}});
ITuyaBlueMeshActivator iTuyaBlueMeshActivator = TuyaHomeSdk.getTuyaBlueMeshConfig().newActivator(tuyaBlueMeshActivatorBuilder);
// Starts pairing.
iTuyaBlueMeshActivator.startActivator();
// Stops pairing.
iTuyaBlueMeshActivator.stopActivator();
API description
// Starts pairing.
void startActivator();
// Stops pairing.
void stopActivator();
Parameters
Parameter | String | Description |
---|---|---|
mSearchDeviceBeans | List | The set of devices pending pairing. |
timeout | Int | The timeout value of a pairing task. Default value: 100 . Unit: seconds. |
ssid | String | The name of the home Wi-Fi network to which a paired device is connected. |
password | String | The password of the home Wi-Fi network to which a paired device is connected. |
mMeshBean | MeshBean | MeshBean |
homeId | Long | The home to which the mesh network of the paired device belongs. |
version | String |
|
Example
// Pairs the gateway.
TuyaBlueMeshActivatorBuilder tuyaBlueMeshActivatorBuilder = new TuyaBlueMeshActivatorBuilder()
.setWifiSsid(mSsid)
.setWifiPassword(mPassword)
.setSearchDeviceBeans(foundDevices)
.setVersion("2.2 ")
.setBlueMeshBean(mMeshBean)
.setHomeId("homeId")
.setTuyaBlueMeshActivatorListener(new ITuyaBlueMeshActivatorListener() {
@Override
public void onSuccess(DeviceBean devBean) {
// The callback that is used when a single device is paired.
L.d(TAG, "startConfig success");
}
@Override
public void onError(String errorCode, String errorMsg) {
// The callback that is used when a single device failed to be paired.
// The error code. See the subsequent list of pairing error codes.
L.d(TAG, "errorCode: " + errorCode + " errorMsg: " + errorMsg);
}
@Override
public void onFinish() {
// The callback that is used when all devices are paired.
}
});
ITuyaBlueMeshActivator iTuyaBlueMeshActivator = TuyaHomeSdk.getTuyaBlueMeshConfig().newWifiActivator(tuyaBlueMeshActivatorBuilder);
// Starts pairing.
iTuyaBlueMeshActivator.startActivator();
// Stops pairing.
//iTuyaBlueMeshActivator.stopActivator();
Error code | Description |
---|---|
13007 | Failed to log in to a device. |
13004 | Failed to reset a device address. |
13005 | The upper limit for the number of device addresses is reached. |
13007 | The SSID is empty. |
13011 | The pairing task timed out. |
API description
DeviceBean deviceBean=TuyaHomeSdk.getDataInstance().getDeviceBean(mDevId);
// Checks whether a Bluetooth mesh device is a gateway or a sub-device.
if(deviceBean.isBlueMesh()){
L.d(TAG, "This device is blue mesh device");
}
// Checks whether a Bluetooth mesh gateway is used.
if(deviceBean.isBlueMeshWifi()){
L.d(TAG, "This device is blue mesh wifi device");
}
API description
void renameMeshSubDev(String devId, String name, IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
devId | String | The device ID. |
name | String | The new name of the device. |
callback | IResultCallback | The callback. |
Example
mTuyaBlueMesh.renameMeshSubDev(devBean.getDevId(),"Device name", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Example
DeviceBean deviceBean=TuyaHomeSdk.getDataInstance().getDeviceBean(mDevId);
DeviceBean gwBean=TuyaHomeSdk.getDataInstance().getDeviceBean(deviceBean.getParentId());
// The online status, including the status of connections to the local mesh network and gateway.
boolean online=deviceBean.getIsOnline()
// The device online status of connections to the local Bluetooth mesh network.
boolean localOnline=deviceBean.getIsLocalOnline()
// The device online status of connections to the gateway. The gateway is online only when the gateway and its sub-devices are both online.
boolean wifiOnline=deviceBean.isCloudOnline() && gwBean.getIsOnline()
API description
void removeMeshSubDev(String devId, IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
devId | String | The device ID. |
pcc | String | The category and type of the device. |
callback | IResultCallback | The callback. |
Example
mTuyaBlueMesh.removeMeshSubDev(devBean.getDevId(), new IResultCallback(){
@Override
public void onError(String code, String errorMsg) {
Toast.makeText(mContext, "Failed to remove a sub-device"+ errorMsg, Toast.LENGTH_LONG).show();
}
@Override
public void onSuccess() {
Toast.makeText(mContext, "Sub-device removed successfully", Toast.LENGTH_LONG).show();
}
});
The data point (DP) information returned from the cloud might not be the real-time data of the specified device. You can run the following command to query the current DP value of the device. The result is returned by the method onDpUpdate
of IMeshDevListener
.
API description
void querySubDevStatusByLocal(String pcc, String nodeId, IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
pcc | String | The category and type of the device. |
nodeId | String | The value of nodeId for the device. |
callback | IResultCallback | The callback. |
Example
mTuyaBlueMeshDevice.querySubDevStatusByLocal(devBean.getCategory(), devBean.getNodeId(), new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
The ITuyaGroup
class provides operations to manage mesh groups.
You can check whether MeshId
is used by a group to determine whether it is a mesh group or a common Wi-Fi group.
API description
GroupBean groupBean=TuyaHomeSdk.getDataInstance().getGroupBean("groupId");
if(!TextUtils.isEmpty(groupBean.getMeshId())){
L.d(TAG, "This group is a Bluetooth mesh group");
}
Each mesh network supports up to 28,672 groups. In the response to group creation, the group ID ranges from 8000
to EFFF
in hexadecimal and can be locally maintained.
API description
void addGroup(String name, String pcc, String localId,IAddGroupCallback callback);
Parameters
Parameter | Description |
---|---|
name | The name of the group. |
pcc | The categories and types of devices in the group. Different types of devices can be created in a group. FF01 specifies the lighting category. |
localId | The value of localId for the group. Valid values: 8000 to EFFF in hexadecimal. |
callback | The callback. |
Example
mITuyaBlueMesh.addGroup("Group name","Category and type", "8001", new IAddGroupCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess(long groupId) {
}
});
API description
void addDevice(String devId,IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
devId | String | The device ID. |
callback | IResultCallback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newBlueMeshGroupInstance(groupId);
mGroup.addDevice("devId", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
API description
void removeDevice(String devId,IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
devId | String | The device ID. |
callback | IResultCallback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newBlueMeshGroupInstance(groupId);
mGroup.removeDevice("devId", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
API description
void dismissGroup(IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
callback | IResultCallback | The callback. |
API description
ITuyaGroup mGroup = TuyaHomeSdk.newBlueMeshGroupInstance(groupId);
mGroup.dismissGroup(new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
API description
void renameGroup(String groupName,IResultCallback callback);
Parameters
Parameter | Type | Description |
---|---|---|
groupName | String | The new name of the group. |
callback | IResultCallback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newBlueMeshGroupInstance(groupId);
mGroup.renameGroup("Group name",new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Smart devices are managed with DPs. Tuya mesh devices are also controlled by device DPs. The ITuyaBlueMeshDevice
class provides operations to manage mesh groups.
Send a control command in the following format:
{
"(dpId)":"(dpValue)"
}
For more information about DPs, see Data points.
API description
void publishDps(String nodeId, String pcc, String dps, IResultCallback callback);
Parameters
Parameter | Description |
---|---|
nodeId | The local ID of a sub-device. |
pcc | The product category and type of the sub-device. |
dps | The control command. |
callback | The callback. |
Example
String dps = {"1":false};
ITuyaBlueMeshDevice mTuyaBlueMeshDevice=TuyaHomeSdk.newBlueMeshDeviceInstance("meshId");
mTuyaBlueMeshDevice.publishDps(devBean.getNodeId(), devBean.getCategory(), dps, new IResultCallback() {
@Override
public void onError(String s, String s1) {
}
@Override
public void onSuccess() {
}
});
API description
void multicastDps(String localId, String pcc, String dps, IResultCallback callback)
Parameters
Parameter | Description |
---|---|
localId | The local ID of a group. |
pcc | The product category and type of the sub-device. |
dps | The control command. |
callback | The callback. |
Example
String dps = {"1":false};
ITuyaBlueMeshDevice mTuyaBlueMeshDevice= TuyaHomeSdk.newBlueMeshDeviceInstance("meshId");
mTuyaBlueMeshDevice.multicastDps(groupBean.getLocalId(), devBean.getCategory(), dps, new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Device information on a mesh network, such as DP data, status changes, device name, and device removal, is synchronized to IMeshDevListener
in real time.
Example
mTuyaBlueMeshDevice.registerMeshDevListener(new IMeshDevListener() {
/**
* Data is updated.
* @param nodeId The value of `nodeId` for the device.
* @param dps DP data.
* @param isFromLocal The data source. Valid values: `true` to indicate the local Bluetooth mesh network, and `false` to indicate the cloud.
*/
@Override
public void onDpUpdate(String nodeId, String dps,boolean isFromLocal) {
// Returns `DeviceBean` by using `node`.
DeviceBean deviceBean = mTuyaBlueMeshDevice.getMeshSubDevBeanByNodeId(nodeId);
}
/**
* Reports the device status.
* @param online The list of online devices.
* @param offline The list of offline devices.
* @param gwId The source of the status. If `gwId` is not empty, the cloud returns the status. `gwId` indicates the ID of the gateway that reports the data. If `gwId` is empty, the local Bluetooth mesh network returns the status.
*/
@Override
public void onStatusChanged(List<String> online, List<String> offline,String gwId) {
}
/**
* The changed network status.
* @param devId
* @param status
*/
@Override
public void onNetworkStatusChanged(String devId, boolean status) {
}
/**
* Reports the Raw type of data.
* @param bytes
*/
@Override
public void onRawDataUpdate(byte[] bytes) {
}
/**
* The changes of device information, such as the device name.
* @param bytes
*/
@Override
public void onDevInfoUpdate(String devId) {
}
/**
* The device is removed.
* @param devId
*/
@Override
public void onRemoved(String devId) {
}
});
Tuya mesh shares the same logic of device firmware updates as Bluetooth mesh. For more information, see Firmware updates for Bluetooth mesh.
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback