TUYA mesh User manual

Tuya mesh
Version: 20211129
Online Version

Contents
Contents
1 Scenarios 2
2 Preparation 3
3 Concepts 4
3.1 Product categories and types . . . . . . . . . . . . . . . . . . . . 4
3.2 Mesh terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4 Manage mesh networks 6
4.1 Create a mesh network . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.2 Delete a mesh network . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.3 Query a list of mesh networks in a site . . . . . . . . . . . . . . . . . 7
4.4 Query a list of mesh sub-devices . . . . . . . . . . . . . . . . . . . . 8
4.5 Query and destroy mesh instances . . . . . . . . . . . . . . . . . . . 8
4.6 Connect to and disconnect from a mesh sub-device . . . . . . . . . . 8
5 Pair devices 10
5.1 Reset devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2 Scan for sub-devices pending pairing . . . . . . . . . . . . . . . . . . 11
5.3 Pair mesh sub-devices . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.4 Pair a mesh gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.5 Pairing error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6 Manage devices 17
6.1 Check a mesh device type . . . . . . . . . . . . . . . . . . . . . . . . 17
6.2 Rename a sub-device . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.3 Connect to a mesh network and a gateway . . . . . . . . . . . . . . . 18
6.4 Remove a sub-device . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.5 Query sub-device status . . . . . . . . . . . . . . . . . . . . . . . . . 20
7 Manage groups 22
7.1 Check a mesh group . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.2 Create a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.3 Add sub-devices to a group . . . . . . . . . . . . . . . . . . . . . . . 23
7.4 Remove sub-devices from a group . . . . . . . . . . . . . . . . . . . . 24
I

Contents
7.5 Delete a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.6 Rename a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8 Control devices and groups 27
8.1 Control devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.2 Control groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.3 Listen for mesh device status . . . . . . . . . . . . . . . . . . . . . . 29
9 Update rmware 31
II

Contents
Tuya supports the following three Bluetooth connectivity topology options: Blue-
tooth Low Energy (Bluetooth LE), Tuya’s proprietary Bluetooth mesh connections
(Tuya mesh), and Bluetooth mesh networking (Bluetooth mesh) provided by Blue-
tooth Special Interest Group (Bluetooth SIG). This topic describes the development
guidance on pairing, control, and management of devices that use Tuya mesh.
1 / 31

1 Scenarios
1 Scenarios
The following table lists the Bluetooth connectivity topology options that vary de-
pending on di󰍒erent smart products.
Type Product
Bluetooth LE Body fat scales, wrist-worn trackers,
thermostats, electric toothbrushes, and
smart locks
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 devices that support Bluetooth and Wi-Fi combo can be paired over ei-
ther Bluetooth or Wi-Fi. In this case, Bluetooth LE technology is used when combo
devices are paired over Bluetooth. For more information, see Bluetooth.
Before the development of Bluetooth mesh capabilities, get familiar with Smart Life
App SDK. All Bluetooth mesh operations are implemented based on the initialized
site data. A site can belong to multiple Bluetooth mesh networks, but one Bluetooth
mesh network is recommended for each site.
2 / 31

2 Preparation
2 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
1<uses-permission android :name="android .permission .ACCESS_COARSE_LOCA
2TION" />
3<uses-permission android :name="android .permission .ACCESS_FINE_LOCATI
4ON" />
5<uses-permission android :name="android .permission .BLUETOOTH " />
6<uses-permission android :name="android .permission .BLUETOOTH_ADMIN " /
7>
•Precheck of Bluetooth permissions
• Check whether the location permissions are enabled for an app before it uses
Bluetooth connectivity or starts scanning.
• Check whether the Bluetooth feature is enabled.
This precheck is not provided by the Smart Life App SDK. You can manually perform
the precheck. This percheck is essential. Otherwise, the app cannot use Bluetooth
connectivity as expected.
3 / 31

3 Concepts
3 Concepts
3.1 Product categories and types
Bluetooth mesh products are classi󰍓ed into:
• Five categories:
• Lighting (01): smart lights ranging from cool white lights (C) to white and col-
ored lights (RGBCW)
• Electrical (02): one to six-outlet sockets
• Sensors (04): contact sensors, passive infrared (PIR) sensors, and more
• Actuators (10): devices used for actuation, such as motors and alarms
• Adapters (08): gateways (adapters with Bluetooth mesh and other communi-
cation nodes)
• Product types of a category:
• Smart lights ranging from cool white lights (C) to white and colored lights (RG-
BCW) (01–05)
• One to six-outlet power strips (01–06)
• Examples of device category values
• Cool white and colored light (RGBC): 0401
• Five-outlet socket: 0502
3.2 Mesh terms
Term Description
NodeId Represents a mesh node in a 2-byte
󰍓eld. The NodeId 󰍓eld provides a unique
identi󰍓er to distinguish each mesh
device on a mesh network. To control a
device on the network, commands can
be sent to the device with the speci󰍓ed
NodeId 󰍓eld value.
4 / 31

3 Concepts
Term Description
LocalId Represents a mesh group in a 2-byte
󰍓eld. The LocalId 󰍓eld provides a unique
identi󰍓er to distinguish each mesh
group on a mesh network. To control a
group device on the network,
commands can be sent to the speci󰍓ed
LocalId 󰍓eld value of the device.
Synchronous operations 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.
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.
5 / 31

4 Manage mesh networks
4 Manage mesh networks
4.1 Create a mesh network
API description
1void createBlueMesh(String meshName,ITuyaResultCallback <BlueMeshBea
2n>callback );
Parameters
Parameter Type Description
meshName String The name of a mesh
network, with up to 16
bytes.
callback ITuyaResultCallback The callback.
Example
1TuyaHomeSdk.newHomeInstance("siteId ").createBlueMesh(" meshName ",new
2ITuyaResultCallback<BlueMeshBean >() {
3@Override
4public void onError(String errorCode ,String errorMsg ) {
5}
6@Override
7public void onSuccess(BlueMeshBean blueMeshBean) {
8}
9});
4.2 Delete a mesh network
API description
6 / 31

4 Manage mesh networks
1void removeMesh(IResultCallback callback );
Parameters
Parameter Type Description
callback IResultCallback The callback.
Example
1TuyaHomeSdk.newBlueMeshDeviceInstance(meshId).removeMesh(new IResult
2Callback () {
3@Override
4public void onError(String errorCode ,String errorMsg ) {
5}
6@Override
7public void onSuccess() {
8}
9});
4.3 Query a list of mesh networks in a site
API description
1List<BlueMeshBean>getMeshList();
Example
1ITuyaHome mTuyaHome =TuyaHomeSdk.newHomeInstance("siteId");
2if (mTuyaHome .getHomeBean() != null){
3List<BlueMeshBean>meshList =mTuyaHome.getHomeBean(). getMeshList();
4BlueMeshBean meshBean=meshList.get(0);
5}
7 / 31

4 Manage mesh networks
4.4 Query a list of mesh sub-devices
API description
1List<DeviceBean >getMeshSubDevList();
Example
1List<DeviceBean >meshSubDevList =TuyaHomeSdk.newBlueMeshDeviceInsta
2nce("meshId").getMeshSubDevList();
4.5 Query and destroy mesh instances
We recommend that you destroy the current mesh instance and initialize the mesh
instance for the target site when you switch between sites.
API method
1// Initializes the mesh network.
2TuyaHomeSdk.getTuyaBlueMeshClient(). initMesh (String meshId);
3// Destroys the current mesh network.
4TuyaHomeSdk.getTuyaBlueMeshClient(). destroyMesh();
4.6 Connect to and disconnect from a mesh sub-device
ITuyaBlueMeshClient provides API methods to start a connection, close a connection,
start scanning, and stop scanning.
API method
8 / 31

4 Manage mesh networks
1// Starts a connection .
2TuyaHomeSdk.getTuyaBlueMeshClient(). startClient(mBlueMeshBean);
3// Closes a connection .
4TuyaHomeSdk.getTuyaBlueMeshClient(). stopClient();
5// Starts scanning .
6TuyaHomeSdk.getTuyaBlueMeshClient(). startSearch()
7// Stops scanning .
8TuyaHomeSdk.getTuyaBlueMeshClient(). stopSearch();
:::important
• After a connection is started, available devices are scanned for in the back-
ground until a device is connected.
• The background scanning will consume resources. You can start and stop scan-
ning to control the background scanning.
• Before a connection is started with startClient(), the API methods of startSearch
() and stopSearch() are invalid.
• After a mesh network is connected, the API methods of startSearch() and
stopSearch() are also invalid. :::
9 / 31

5 Pair devices
5 Pair devices
Mesh devices to be paired are classi󰍓ed into:
• A common Bluetooth mesh device, also known as a mesh sub-device
• A mesh gateway
Common gateway sub-devices include smart lights, smart sockets, and low-power
products. All mesh devices without mesh gateways can be regarded as common
Bluetooth mesh devices.
5.1 Reset devices
The default name of a device in the reset state is out_of_mesh and the default pass-
word is 123456. The following table lists multiple common reset methods.
Product type Reset method State pending pairing
Smart light Turns on and o󰍒 the light
consecutively three times
in a row
The indicator is 󰍔ickering
quickly.
Smart socket Long press the switch for
three seconds
The indicator is 󰍔ickering
quickly.
Gateway product Long press the switch for
three seconds
The red and blue
indicators are 󰍔ickering
quickly.
Low-power device Long press 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 Long press the switch for
three seconds
The indicator is 󰍔ickering
quickly.
10 / 31

5 Pair devices
5.2 Scan for sub-devices pending pairing
You must check Bluetooth and location permissions and then start scanning for mesh
devices pending pairing.
API description
1// Starts scanning .
2void startSearch();
3// Stops scanning .
4void stopSearch();
Example
1ITuyaBlueMeshSearchListener iTuyaBlueMeshSearchListener =new ITuyaB
2lueMeshSearchListener() {
3@Override
4public void onSearched(SearchDeviceBean deviceBean) {
5}
6@Override
7public void onSearchFinish() {
8}
9};
10 SearchBuilder searchBuilder =new SearchBuilder()
11 // The name of the device to be scanned for . Default value: `out_of_
12 mesh`to represent the name of the device in the pairing state .
13 .setMeshName("out_of_mesh")
14 .setTimeOut(100) // The duration of the scanning . Unit: seconds .
15 .setTuyaBlueMeshSearchListener (iTuyaBlueMeshSearchListener).build();
16 ITuyaBlueMeshSearch mMeshSearch =TuyaHomeSdk.getTuyaBlueMeshConfig(
17 ). newTuyaBlueMeshSearch(searchBuilder);
18 // Starts scanning .
19 mMeshSearch.startSearch();
20 // Stops scanning .
21 mMeshSearch.stopSearch();
5.3 Pair mesh sub-devices
API description
11 / 31

5 Pair devices
1// Starts pairing.
2void startActivator();
3// Stops pairing.
4void 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 site
Wi-Fi network to which a
paired device is
connected.
mMeshBean MeshBean MeshBean
homeId Long The site to which the
mesh network of the
paired device belongs.
version String The type of paired
device. Valid values:
1.0 to represent
common mesh devices.
2.2 to represent
gateway devices.
Example
12 / 31

5 Pair devices
1// Pairs a common mesh device.
2TuyaBlueMeshActivatorBuilder tuyaBlueMeshActivatorBuilder =new Tuya
3BlueMeshActivatorBuilder()
4.setSearchDeviceBeans(foundDevices)
5.setVersion("1.0")
6.setBlueMeshBean(mMeshBean)
7.setTimeOut(timeOut)
8.setTuyaBlueMeshActivatorListener(new ITuyaBlueMeshActivatorListener
9() {
10 @Override
11 public void onSuccess(DeviceBean deviceBean) {
12 }
13 @Override
14 public void onError(String errorCode ,String errorMsg ) {
15 }
16 @Override
17 public void onFinish () {
18 }});
19 ITuyaBlueMeshActivator iTuyaBlueMeshActivator =TuyaHomeSdk.getTuyaB
20 lueMeshConfig().newActivator(tuyaBlueMeshActivatorBuilder);
21 // Starts pairing.
22 iTuyaBlueMeshActivator.startActivator();
23 // Stops pairing.
24 iTuyaBlueMeshActivator.stopActivator();
5.4 Pair a mesh gateway
API description
1// Starts pairing.
2void startActivator();
3// Stops pairing.
4void stopActivator();
Parameters
13 / 31

5 Pair devices
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 site Wi-Fi
network to which a paired
device is connected.
password String The password of the site
Wi-Fi network to which a
paired device is
connected.
mMeshBean MeshBean MeshBean
homeId Long The site to which the
mesh network of the
paired device belongs.
version String The type of paired
device. Valid values:
1.0 to represent
common mesh devices.
2.2 to represent
gateway devices.
Example
14 / 31

5 Pair devices
1// Pairs the gateway.
2TuyaBlueMeshActivatorBuilder tuyaBlueMeshActivatorBuilder =new Tuya
3BlueMeshActivatorBuilder()
4.setWifiSsid(mSsid)
5.setWifiPassword(mPassword)
6.setSearchDeviceBeans(foundDevices)
7.setVersion("2.2 ")
8.setBlueMeshBean(mMeshBean)
9.setHomeId(" siteId ")
10 .setTuyaBlueMeshActivatorListener(new ITuyaBlueMeshActivatorListener
11 () {
12 @Override
13 public void onSuccess(DeviceBean devBean ) {
14 // The callback that is used when a single device is paired.
15 L.d(TAG," startConfig success ");
16 }
17 @Override
18 public void onError(String errorCode ,String errorMsg ) {
19 // The callback that is used when a single device failed to be paire
20 d.
21 // The error code. See the list of pairing error codes .
22 L.d(TAG," errorCode: " +errorCode +" errorMsg : " +errorMsg );
23 }
24 @Override
25 public void onFinish () {
26 // The callback that is used when all devices are paired.
27 }
28 });
29 ITuyaBlueMeshActivator iTuyaBlueMeshActivator =TuyaHomeSdk.getTuyaB
30 lueMeshConfig().newWifiActivator (tuyaBlueMeshActivatorBuilder);
31 // Starts pairing.
32 iTuyaBlueMeshActivator.startActivator();
33 // Stops pairing.
34 // iTuy aBl ueM esh Act iva tor . stopActivator () ;
5.5 Pairing error codes
Error code Description
13007 Failed to log in to a device.
13004 Failed to reset a device address.
13005 The upper limit of the number of device
addresses is reached.
13007 The SSID is empty.
15 / 31

5 Pair devices
Error code Description
13011 The pairing task timed out.
16 / 31

6 Manage devices
6 Manage devices
6.1 Check a mesh device type
API method
1DeviceBean deviceBean=TuyaHomeSdk.getDataInstance(). getDeviceBean(mD
2evId);
3// Checks whether a Bluetooth mesh device is a gateway or a sub - devi
4ce.
5if(deviceBean.isBlueMesh()){
6L.d(TAG," This device is blue mesh device ");
7}
8// Checks whether a Bluetooth mesh gateway is used.
9if(deviceBean.isBlueMeshWifi()){
10 L.d(TAG," This device is blue mesh wifi device ");
11 }
6.2 Rename a sub-device
API description
1void renameMeshSubDev (String devId ,String name,IResultCallback cal
2lback);
Parameters
Parameter Type Description
devId String The device ID.
name String The new name of the
device.
callback IResultCallback The callback.
Example
17 / 31