Last Updated on : 2023-05-22 06:38:25download
Bluetooth mesh enables Bluetooth devices to communicate with each other over a mesh network. This topic describes the API methods and examples of Bluetooth mesh capabilities provided by Smart Life App SDK for Android.
The Bluetooth Special Interest Group (SIG) provides Bluetooth mesh technologies to enable mesh networking. Bluetooth mesh is also known as Bluetooth SIG mesh. This mesh networking standard allows for many-to-many communication over Bluetooth radio. The standard must be followed to implement Bluetooth mesh networking and device updates.
Term | Description |
---|---|
Product category and type | Each Bluetooth mesh device corresponds to a product that belongs to a product category and a product type. The SDK provides pcc to specify a product category and type to specify a product type. |
Mesh group localId | The 2-byte localId field provides a unique identifier to distinguish each mesh group on a mesh network. To control devices in a group, commands can be sent to the mesh network with the specified localId field value. |
Mesh nodeId | The 2-byte node ID provides a unique identifier to distinguish each mesh device on a mesh network. To control a device on the network, commands can be sent to the mesh network with the specified nodeId field value. |
Local connections | Paired devices are controlled with commands on a mesh network through Bluetooth connections. |
Gateway connections | Paired devices are controlled with commands on a mesh network through gateway connections. The gateway must be deployed close to the devices. |
When devices are added, deleted, or managed in a group, these operations are implemented with local Bluetooth commands and synchronously recorded in the cloud. Therefore, device information is synchronized to the local mesh network and the cloud at the same time.
A device is classified with a combination of device type
, product category
, and product type
. The class name is then stored in the little-endian format.
1
2
Example:
Product | Category value | Description |
---|---|---|
Standard white and colored light (RGBCW) | 1510 | 1015 in the little-endian format:
|
Standard 4-outlet power strip | 2410 | 1024 in the little-endian format:
|
Raw type of device | xx20 | 20xx in the little-endian format: 2 represents a raw type of device. |
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.
This precheck is not provided by the Smart Life App SDK. You can manually perform the precheck.
::
Initialize a home: Before the development of Bluetooth mesh capabilities, get familiar with Smart Life App SDK. All Bluetooth mesh operations are implemented based on the initialized home data. For more information, see Home Management.
A home can belong to multiple Bluetooth mesh networks, but one Bluetooth mesh network is recommended for each home.
API description
void createSigMesh(ITuyaResultCallback<SigMeshBean> callback);
Example
TuyaHomeSdk.newHomeInstance(123xxx) // The `homeId` parameter of long type.
.createSigMesh(new ITuyaResultCallback<SigMeshBean>() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess(SigMeshBean sigMeshBean) {
}
});
Deletes a Bluetooth mesh network. If sub-devices are included in the mesh group, they are also removed.
API description
void removeMesh(IResultCallback callback);
Example
TuyaHomeSdk.newSigMeshDeviceInstance(meshId).removeMesh(new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Returns a list of mesh networks
for an initialized home
instance.
API description
List<SigMeshBean> getSigMeshList();
Example
ITuyaHome mTuyaHome = TuyaHomeSdk.newHomeInstance(123xxx); // The `homeId` parameter.
if (mTuyaHome.getHomeBean() != null){
List<SigMeshBean> meshList = TuyaHomeSdk.getSigMeshInstance().getSigMeshList()
}
API description
List<DeviceBean> getMeshSubDevList();
Example
List<DeviceBean> meshSubDevList = TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxxx").getMeshSubDevList();
Initializes a mesh network and registers a listener for status changes from the cloud. This API method is called when users switch between or initialize mesh networks.
API description
void initMesh(String meshId);
Example
TuyaHomeSdk.getTuyaSigMeshClient().initMesh("meshIdxxxxx");
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
void destroyMesh();
Example
TuyaHomeSdk.getTuyaSigMeshClient().destroyMesh();
ITuyaBlueMeshClient
provides API methods to start a connection, close a connection, start scanning, and stop scanning.
Example
// Starts a connection.
TuyaHomeSdk.getTuyaSigMeshClient().startClient(mSigMeshBean);
// Starts a connection with a specified scanning period.
TuyaHomeSdk.getTuyaSigMeshClient().startClient(mSigMeshBean,searchTime);
// Closes a connection.
TuyaHomeSdk.getTuyaSigMeshClient().stopClient();
// Starts scanning.
TuyaHomeSdk.getTuyaSigMeshClient().startSearch()
// Stops scanning.
TuyaHomeSdk.getTuyaSigMeshClient().stopSearch();
The background scanning will consume resources. You can start and stop scanning to control the background scanning.
startClient(mSigMeshBean)
: After a connection is started, available devices are scanned for in the background until a device is connected.startClient(mSigMeshBean,searchTime)
: After a connection is started, if no device is found within a period specified by searchTime
, scanning is stopped.startClient()
is called, the API methods of startSearch()
and stopSearch()
are invalid.startSearch
and stopSearch
are also invalid.In a pairing process, the Bluetooth mesh device joins the target mesh network based on certain communication technologies.
Scans for a Bluetooth mesh device pending pairing. When the device is discovered, it can be paired.
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() {
}
};
// The UUID of a Bluetooth mesh device to be paired is unchanged.
UUID[] MESH_PROVISIONING_UUID = {UUID.fromString("00001827-0000-1000-8000-00805f9b34fb")};
SearchBuilder searchBuilder = new SearchBuilder()
.setServiceUUIDs(MESH_PROVISIONING_UUID) // The UUID of a Bluetooth mesh device to be paired is unchanged.
.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();
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 | SearchDeviceBean.productId . byte[] must be converted into String before this parameter is set. |
uuid | String | The device UUID. It is null for a mesh device. |
mac | String | SearchDeviceBean.productId |
Example
TuyaHomeSdk.getActivatorInstance().getActivatorDeviceInfo(
// btye[] to String
new String(bean.getProductId(), StandardCharsets.UTF_8),
// uuid
null,
// mac
scanDeviceBean.getMacAdress(),
// callback
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. |
Sub-devices can be paired with the app over Bluetooth or through a gateway.
API description
// Starts pairing.
void startActivator();
// Stops pairing.
void stopActivator();
Example
TuyaSigMeshActivatorBuilder tuyaSigMeshActivatorBuilder = new TuyaSigMeshActivatorBuilder()
.setSearchDeviceBeans(mSearchDeviceBeanList)
.setSigMeshBean(sigMeshBean) // Bluetooth mesh network information.
.setTimeOut(100) // The timeout value.
.setTuyaBlueMeshActivatorListener(new ITuyaBlueMeshActivatorListener() {
@Override
public void onSuccess(String mac, DeviceBean deviceBean) {
L.d(TAG, "subDevBean onSuccess: " + deviceBean.getName());
}
@Override
public void onError(String mac, String errorCode, String errorMsg) {
L.d(TAG, "config mesh error" + errorCode + " " + errorMsg);
}
@Override
public void onFinish() {
L.d(TAG, "config mesh onFinish");
});
ITuyaBlueMeshActivator iTuyaBlueMeshActivator = TuyaHomeSdk.getTuyaBlueMeshConfig().newSigActivator(tuyaSigMeshActivatorBuilder);
// Starts pairing.
iTuyaBlueMeshActivator.startActivator();
// Stops pairing.
iTuyaBlueMeshActivator.stopActivator();
Parameters
Parameter | Description |
---|---|
mSearchDeviceBeanList | The collection of devices to be paired. They can be returned in the result of startSearch . |
timeout | The timeout value of a pairing task. Default value: 100 . Unit: seconds. The value can be increased to pair a large number of devices. |
sigMeshBean | SigMeshBean |
Response parameters
Parameter | Description |
---|---|
DeviceBean | The type of device data. For more information, see Data types of DeviceBean . |
errorCode | For more information, see Pairing error codes. |
A Bluetooth mesh gateway is a combo device.
For a gateway connected to the network over Wi-Fi, use the API for pairing in Wi-Fi Easy Connect (EZ) mode.
For a Bluetooth Low Energy (LE) and Wi-Fi combo gateway, use the pairing API for a combo device.
Bluetooth mesh sub-devices can be paired through a gateway in a similar way like Zigbee sub-devices. For more information, see Sub-Device Pairing.
Error code | Error message |
---|---|
21002 | The invite failure has occurred. |
21004 | The provision failure has occurred. |
21006 | Failed to send a public key. |
21008 | The conform failure has occurred. |
210010 | The random conform failure has occurred. |
210014 | Failed to send data. |
210016 | The composition data failure has occurred. |
210018 | Failed to add appkey . |
210020 | Failed to bind a model. |
210022 | A publication model failure has occurred. |
210024 | A network transmission failure has occurred. |
210026 | Failed to register the device in the cloud. |
210027 | The upper limit of the number of device addresses is reached. |
210034 | An error has occurred while processing notify . |
20021 | The pairing task timed out. |
The ITuyaBlueMeshDevice
class provides operations to manage mesh groups.
Example
ITuyaBlueMeshDevice mTuyaBlueMeshDevice = TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxx");
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()
Example
DeviceBean deviceBean=TuyaHomeSdk.getDataInstance().getDeviceBean(mDevId);
// Checks whether a Bluetooth mesh device is a gateway or a sub-device.
if(deviceBean.isSigMesh()){
// This device is sig mesh device"
}
// Check whether a device is a Bluetooth mesh gateway.
if(deviceBean.isSigMeshWifi()){
// This device is a Bluetooth mesh Wi-Fi device.
}
API description
void renameMeshSubDev(String devId, String name, IResultCallback callback);
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
name | The new name of the device. |
callback | The callback. |
Example
ITuyaBlueMeshDevice mTuyaBlueMeshDevice= TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxx");
mTuyaBlueMeshDevice.renameMeshSubDev("devIdxxxx","New device name", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
The data point (DP) data in the cloud might not be the real-time data of the current 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, final String nodeId, final IResultCallback callback);
Parameters
Parameter | Description |
---|---|
pcc | The category and type of the device. |
nodeId | The value of nodeId for the device. |
callback | The callback. |
Example
ITuyaBlueMeshDevice mTuyaBlueMeshDevice = TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxx");
mTuyaBlueMeshDevice.querySubDevStatusByLocal(devBean.getCategory(), devBean.getNodeId(), new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback. The result is returned by `IMeshDevListener`.
}
});
API description
void removeMeshSubDev(String devId, IResultCallback callback);
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
pcc | The category and type of the device. |
callback | The callback. |
Example
ITuyaBlueMeshDevice mTuyaBlueMeshDevice = TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxx");
mTuyaBlueMeshDevice.removeMeshSubDev(devBean.getDevId(), devBean.getCategory(), 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.
Example
GroupBean groupBean=TuyaHomeSdk.getDataInstance().getGroupBean("groupId");
if(!TextUtils.isEmpty(groupBean.getMeshId())){
// This group is mesh group"
}
Each mesh network supports up to 16,128 groups. In the response to group creation, the group ID ranges from C000
to FEFF
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. |
localId | The value of localId for the group. Valid values: C000 and FEFF . |
callback | The callback. |
Example
ITuyaBlueMeshDevice mTuyaSigMeshDevice= TuyaHomeSdk.newSigMeshDeviceInstance("meshId");
mTuyaSigMeshDevice.addGroup("Group name","Category and type of product", "C001", new IAddGroupCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess(long groupId) {
// The success callback.
}
});
API description
void addDevice(String devId,IResultCallback callback);
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
callback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newSigMeshGroupInstance(groupId);
mGroup.addDevice("devId", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
API description
void removeDevice(String devId,IResultCallback callback);
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
callback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newSigMeshGroupInstance(groupId);
mGroup.removeDevice("devId", new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
API description
void dismissGroup(IResultCallback callback);
Parameters
Parameter | Description |
---|---|
callback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newSigMeshGroupInstance(groupId);
mGroup.dismissGroup(new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
API description
void renameGroup(String groupName,IResultCallback callback);
Parameters
Parameter | Description |
---|---|
groupName | The new name of the group. |
callback | The callback. |
Example
ITuyaGroup mGroup = TuyaHomeSdk.newSigMeshGroupInstance(groupId);
mGroup.renameGroup("Group name",new IResultCallback() {
@Override
public void onError(String code, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
Smart devices are managed with DPs. Bluetooth 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:
{
"(dpId1)":(dpValue1),
"(dpId2)":(dpValue2)
}
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 list of DPs. For more information, see Data points. |
callback | The callback. |
Example
String dps = {"1":false};
ITuyaBlueMeshDevice mTuyaSigMeshDevice=TuyaHomeSdk.newSigMeshDeviceInstance("meshIdxxxx");
mTuyaSigMeshDevice.publishDps(devBean.getNodeId(), devBean.getCategory(), dps, new IResultCallback() {
@Override
public void onError(String s, String s1) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
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 list of DPs. For more information, see Data points. |
callback | The callback. |
Example
String dps = {"1":false};
ITuyaBlueMeshDevice mTuyaSigMeshDevice= TuyaHomeSdk.newSigMeshDeviceInstance("meshId");
mTuyaSigMeshDevice.multicastDps(groupBean.getLocalId(), devBean.getCategory(), dps, new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
// The failure callback.
}
@Override
public void onSuccess() {
// The success callback.
}
});
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
mTuyaSigMeshDevice.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.
*/
@Override
public void onStatusChanged(List<String> online, List<String> offline,String gwId) {
}
/**
* The changes in 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) {
}
});
Bluetooth mesh sub-devices can be updated over the air.
Bluetooth Low Energy (LE) mesh devices must be woken up before the update. The wake-up method varies depending on different devices.
API description
void requestUpgradeInfo(String devId, IRequestUpgradeInfoCallback callback);
Parameters
Parameter | Description |
---|---|
devId | The value of devId for the target device. |
callback | 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 | int | The update status. Valid values:
|
version | String | The target firmware version. |
currentVersion | String | The current version. |
timeout | int | The timeout value. Unit: seconds. |
upgradeType | int |
|
type | int | The type of module. Valid values:
|
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. url 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. |
API description
void startOta();
Example
private MeshUpgradeListener mListener = new MeshUpgradeListener() {
@Override
public void onUpgrade(int percent) {
// The progress of the firmware update.
}
@Override
public void onSendSuccess() {
// Transmission of updates is completed.
}
@Override
public void onUpgradeSuccess() {
// The firmware is updated.
mMeshOta.onDestroy();
}
@Override
public void onFail(String errorCode, String errorMsg) {
// Failed to update the firmware.
mMeshOta.onDestroy();
}
};
// Returns the byte stream of a specified file.
byte data[] = getFromFile(path);
TuyaBlueMeshOtaBuilder build = new TuyaBlueMeshOtaBuilder()
.setData(data)
.setMeshId(mDevBean.getMeshId())
.setMac(mDevBean.getMac())
.setProductKey(mDevBean.getProductId())
.setNodeId(mDevBean.getNodeId())
.setDevId(mDevID)
.setVersion("version")
.setTuyaBlueMeshActivatorListener(mListener)
.bulid();
ITuyaBlueMeshOta mMeshOta = TuyaHomeSdk.newMeshOtaManagerInstance(build);
// Starts an OTA update.
mMeshOta.startOta();
Request parameters
TuyaBlueMeshOtaBuilder
Parameter | Type | Description |
---|---|---|
data | byte[] | The byte stream of the target firmware. |
meshId | String | The value of meshId of the device. |
mac | String | The MAC address of the device. |
productKey | String | The product ID of the device. |
mNodeId | String | The value of nodeId for the device. |
devId | String | The device ID. |
version | String | The version number of the target firmware. |
Updates a Bluetooth mesh gateway in a similar way that a common device is updated.
Example
private IOtaListener iOtaListener = new IOtaListener() {
@Override
public void onSuccess(int otaType) {
// The firmware is updated.
}
@Override
public void onFailure(int otaType, String code, String error) {
// Failed to update the firmware.
}
@Override
public void onProgress(int otaType, final int progress) {
// The progress of the firmware update.
}
};
ITuyaOta iTuyaOta = TuyaHomeSdk.newOTAInstance(devId);
iTuyaOta.setOtaListener(mOtaListener);
// Starts an OTA update.
iTuyaOta.startOta();
// Destroys the update task.
iTuyaOta.onDestroy();
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback