Tuya Mesh
Last Updated on : 2024-05-15 03:11:11download
This topic describes the implementation of communication over Bluetooth based on Thing’s proprietary mesh networking technology, also known as Thing mesh. Each Thing 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. This topic provides the development guidance on pairing, control, and management of devices that use Thing mesh. For more information about Bluetooth mesh concepts, see Bluetooth Mesh.
| Class name | Description |
|---|---|
| ThingBLEMeshManager | Encapsulates all API methods of Thing mesh. |
Preparation
Enables Thing mesh.
// Enables Thing mesh during initialization.
[[ThingSmartSDK sharedInstance] setValue:@(YES) forKey:@"bleMeshEnable"];
Management
Thing mesh operation classes are included in the file ThingSmartBleMesh.h.
Create a mesh network
A home can belong to multiple mesh networks, but one mesh network is recommended for each home. Before the request, check whether a mesh network is created. If not, you can call this API method to create one.
All mesh operations are implemented based on the initialized home data. For more information, see Home Management.
API description
+ (void)createBleMeshWithMeshName:(NSString *)meshName
homeId:(long long)homeId
success:(void(^)(ThingSmartBleMeshModel *meshModel))success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| meshName | The name of the Thing mesh network. It can be customized. |
| homeId | The home ID. |
| success | The success callback. |
| failure | The failure callback. |
Example
ThingSmartHome *home = #<The initialized home instance>;
long long homeId = home.homeModel.homeId;
[ThingSmartBleMesh createBleMeshWithMeshName:@"yourMeshName" homeId:homeId success:^(ThingSmartBleMeshModel *meshModel) {
// success do...
} failure:^(NSError *error) {
NSLog(@"create mesh error: %@", error);
}];
The meshName of this method is a custom parameter. We recommend that you uniquely set it in the format of mesh+<timestamp>.
Delete a mesh network
API description
Deletes a mesh network. If sub-devices are included in the mesh group, they are also removed. In this case, the Wi-Fi connector is also removed.
- (void)removeMeshWithSuccess:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| success | The success callback. |
| failure | The failure callback. |
Example
self.mesh = #<ThingSmartBleMesh instance>;
[self.mesh removeMeshWithSuccess:^{
// success do...
} failure:^(NSError *error) {
XCTFail(@"test remove mesh failure: %@", error);
}];
Query a list of mesh networks in a home
API description
Returns a list of mesh networks for an initialized home instance.
- (void)getMeshListWithSuccess:(void(^)(NSArray <ThingSmartBleMeshModel *> *list))success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| success | The success callback. |
| failure | The failure callback. |
Example
ThingSmartHome *home = #<home instance>
[home getMeshListWithSuccess:^(NSArray<ThingSmartBleMeshModel *> *list) {
// success do
} failure:^(NSError *error) {
NSLog(@"get mesh list error: %@", error);
}];
Query a mesh instance
API description
+ (instancetype)bleMeshWithMeshId:(NSString *)meshId homeId:(long long)homeId;
Parameters
| Parameter | Description |
|---|---|
| meshId | The mesh ID. |
| homeId | The current home ID. |
Example
You can create a mesh instance by using meshModel for the home instance of the ThingSmartHome class. Pass the mesh instance to ThingSmartUser. The SDK and the upper-layer encapsulation are based on whether ThingSmartUser has the value.
// The mesh network is not queried.
if ([ThingSmartUser sharedInstance].meshModel == nil) {
ThingSmartHome *home = #<home instance>
[home getMeshListWithSuccess:^(NSArray<ThingSmartBleMeshModel *> *list) {
if (list.count > 0) {
// Assigns values.
[ThingSmartUser sharedInstance].meshModel = home.meshModel;
[ThingSmartUser sharedInstance].mesh = [ThingSmartBleMesh bleMeshWithMeshId:home.meshModel.meshId homeId:home.meshModel.homeId];
// Subsequence operations.
} else {
// The created mesh instance is used if no mesh information is found in the cloud.
NSTimeInterval interval = [[NSDate date] timeIntervalSince1970];
NSString *meshName = [NSString stringWithFormat:@"tymesh%.0f", interval];
[ThingSmartBleMesh createBleMeshWithMeshName:meshName homeId:home.homeModel.homeId success:^(ThingSmartBleMeshModel *meshModel) {
// Assigns values.
[ThingSmartUser sharedInstance].meshModel = meshModel;
[ThingSmartUser sharedInstance].mesh = [ThingSmartBleMesh bleMeshWithMeshId:meshModel.meshId homeId:home.homeModel.homeId];
// Subsequence operations.
} failure:^(NSError *error) {
// Processes errors.
}];
}
} failure:^(NSError *error) {
// Processes errors.
}];
} else {
// Subsequence operations.
}
Connect to a mesh sub-device
Connect a paired device to a Thing mesh network. During this process, Bluetooth must be enabled.
API description
-
To run only a pairing task, enter the default mesh
nameandpassword. Then, only
- (void)bleMeshManager:(ThingBLEMeshManager *)manager didScanedDevice:(ThingBleMeshDeviceModel *)device;ofThingBLEMeshManagerDelegatereturns the scanning result. -
To connect a paired device to a mesh network, enter the
nameandpasswordof the created mesh network. The data is returned by cloud-based API methods. Then, the paired device is automatically connected to the mesh network. The system also automatically queries the online status of each device once on the mesh network.- (void)startScanWithName:(NSString *)name pwd:(NSString *)pwd active:(BOOL)active wifiAddress:(uint32_t)wifiAddress otaAddress:(uint32_t)otaAddress;
Parameters
| Parameter | Description |
|---|---|
| name | The name of the mesh network. |
| pwd | The password of the mesh network. |
| active | Specifies whether to pair and activate a device. |
| wifiAddress | The Wi-Fi address. This parameter is required for pairing a gateway and set to 0 for other types of devices. |
| otaAddress | The IP address of the OTA update device. This parameter is required for OTA update and set to 0 for other types of devices. |
Callback
Queries the online status of all devices on a mesh network after a paired device is connected to the mesh network. In the callback, the delegate method ThingSmartHomeDelegate is called.
// Device information such as a device name is changed.
- (void)home:(ThingSmartHome *)home deviceInfoUpdate:(ThingSmartDeviceModel *)device;
Example
// The parameters of `active`, `wifiAddress`, and `otaAddress`.
[[ThingBLEMeshManager sharedInstance] startScanWithName:[ThingSmartUser sharedInstance].meshModel.code pwd:[ThingSmartUser sharedInstance].meshModel.password active:NO wifiAddress:0 otaAddress:0];
// Device information such as a device name is changed.
- (void)home:(ThingSmartHome *)home deviceInfoUpdate:(ThingSmartDeviceModel *)device {
// The callback.
}
Pairing
A Bluetooth device in the reset and disconnected state can be paired to join a mesh network. Mesh devices to be paired are classified into:
- A Thing mesh sub-device, such as lights, sockets, and low-power devices. This type of device runs without a gateway.
- A mesh gateway.
Thing mesh operation classes are included in the file ThingBLEMeshManager. It is a singleton class.
Reset 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 | 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. |
Scan for sub-devices pending pairing
To simplify scanning and subsequent pairing operations, Thing encapsulates all operations in the same API.
-
To run only a pairing task, enter the default mesh
nameandpassword. Then, only
- (void)bleMeshManager:(ThingBLEMeshManager *)manager didScanedDevice:(ThingBleMeshDeviceModel *)device;ofThingBLEMeshManagerDelegatereturns the scanning result. -
To connect a paired device to a mesh network, enter the
nameandpasswordof the created mesh network. The data is returned by cloud-based API methods. Then, the paired device is automatically connected to the mesh network. The system also automatically queries the online status of each device once on the mesh network.
API description
- (void)startScanWithName:(NSString *)name
pwd:(NSString *)pwd
active:(BOOL)active
wifiAddress:(uint32_t)wifiAddress
otaAddress:(uint32_t)otaAddress;
Parameters
| Parameter | Description |
|---|---|
| name | The name of the mesh network. |
| pwd | The password of the mesh network. |
| wifiAddress | The Wi-Fi address. This parameter is required for pairing a gateway and set to 0 for other types of devices. |
| otaAddress | The IP address of the OTA update device. This parameter is required for OTA update and set to 0 for other types of devices. |
Callback
-
If
nameis the default valueout_of_meshin an activation task, the system will scan for surrounding devices to be paired. In the callback,ThingBLEMeshManagerDelegatereturns the scanning result. -
To connect a paired device to a mesh network, subsequent operations will automatically proceed without a callback. The API calls are similar to those for connecting to and disconnecting from a mesh network.
- (void)bleMeshManager:(ThingBLEMeshManager *)manager didScanedDevice:(ThingBleMeshDeviceModel *)device;
Parameters
| Parameter | Description |
|---|---|
| manager | The mesh manager. |
| device | The information about the device pending pairing. |
Example
// Starts scanning for a device pending pairing.
[[ThingBLEMeshManager sharedInstance] startScanWithName:@"out_of_mesh" pwd:@"123456" active:YES wifiAddress:0 otaAddress:0];
// The callback of `ThingBLEMeshManagerDelegate`.
- (void)bleMeshManager:(ThingBLEMeshManager *)manager didScanedDevice:(ThingBleMeshDeviceModel *)device {
// This callback method applies to scanning for both gateways and sub-devices.
// `device.type` and `device.vendorInfo` determines whether the target device is a mesh gateway.
if (device.type == [TPUtils getIntValueByHex:@"0x0108"] || ([TPUtils getIntValueByHex:[device.vendorInfo substringWithRange:NSMakeRange(0, 2)]] & 0x08) == 0x08) {
// The mesh gateway.
return;
} else {
// Mesh sub-devices.
}
}
// Implements `getIntValueByHex`.
+ (uint32_t)getIntValueByHex:(NSString *)getStr
{
NSScanner *tempScaner=[[NSScanner alloc] initWithString:getStr];
uint32_t tempValue;
[tempScaner scanHexInt:&tempValue];
return tempValue;
}
Activate sub-devices
API description
- (void)activeMeshDeviceIncludeGateway:(BOOL)includeGateway;
Parameters
| Parameter | Description |
|---|---|
| includeGateway | Indicates whether to activate a gateway. A value of yes indicates that a discovered gateway, rather than the sub-devices, will be activated. Otherwise, all discovered devices rather than the gateway will be activated. |
Callback
- (void)activeDeviceSuccessWithName:(NSString *)name deviceId:(NSString *)deviceId error:(NSError *)error;
Parameters
| Parameter | Description |
|---|---|
| name | The name of the device. |
| deviceId | The device ID. |
| error | The error message that might be returned during activation. If it is returned, name and deviceId are empty. |
Activate a specific sub-device
API description
- (void)activeMeshDevice:(ThingBleMeshDeviceModel *)deviceModel;
Parameters
| Parameter | Description |
|---|---|
| deviceModel | The device model. |
The pairing result will be returned by ThingBLEMeshManagerDelegate.
Callback
- (void)activeWifiDeviceWithName:(NSString *)name address:(NSInteger)address mac:(NSInteger)mac error:(NSError *)error;
Parameters
| Parameter | Description |
|---|---|
| name | The name of the device. |
| address | The IP address of the device. |
| mac | The MAC address of the gateway. |
| error | The failure callback. |
Query the pairing token for a mesh gateway
If the target device is a gateway device, after the callback of activeWifiDeviceWithName, the pairing with the Wi-Fi module must be implemented. The method ThingSmartActivator is called.
API description
This token is valid for 10 minutes.
- (void)getTokenWithMeshId:(NSString *)meshId
nodeId:(NSString *)nodeId
productId:(NSString *)productId
uuid:(NSString *)uuid
authKey:(NSString *)authKey
version:(NSString *)version
success:(ThingSuccessString)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| meshId | The mesh ID. |
| nodeId | The node ID. |
| productId | The product ID (PID). |
| uuid | The UUID of the device. |
| authKey | The AuthKey of the device. |
| success | The success callback. A pairing token is returned. |
| failure | The failure callback. |
Pair a mesh gateway
Pairs a mesh gateway by using the pairing token and the hotspot name and password of the router. This method can be called only the callback of activeWifiDeviceWithName of ThingBLEMeshManagerDelegate is executed.
API description
- (void)startBleMeshConfigWiFiWithSsid:(NSString *)ssid
password:(NSString *)password
token:(NSString *)token
timeout:(NSTimeInterval)timeout;
Parameters
| Parameter | Description |
|---|---|
| ssid | The hotspot name of the router. |
| password | The hotspot password of the router. |
| token | The pairing token. |
| timeout | The timeout value of a pairing task. Default value: 100. Unit: seconds. |
Example
// Pairs a mesh device without a mesh gateway.
// 1. Activates a sub-device.
[[ThingBLEMeshManager sharedInstance] activeMeshDeviceIncludeGateway:NO];
// 2. Executes the callback of `ThingBLEMeshManagerDelegate`.
- (void)activeDeviceSuccessWithName:(NSString *)name deviceId:(NSString *)deviceId error:(NSError *)error {
if (error) {
NSLog(@"error : %@", error);
return;
}
// 3. A sub-device is activated.
}
// Activates the mesh gateway.
// 1. Activates a sub-device.
[[ThingBLEMeshManager sharedInstance] activeMeshDeviceIncludeGateway:NO];
// 2. Executes the callback of `ThingBLEMeshManagerDelegate`.
- (void)activeWifiDeviceWithName:(NSString *)name address:(NSInteger)address mac:(NSInteger)mac error:(NSError *)error {
if (error) {
NSLog(@"error : %@", error);
return;
}
// The gateway is activated. Only the Bluetooth module is activated, and you need to continue to activate the Wi-Fi module.
// 3. The user enters the password for reconnection. After the device is reconnected, the SSID, password, and token are sent.
// This operation is required. Otherwise, a Wi-Fi data writing error will occur and cause the pairing task to be failed.
[ThingBLEMeshManager sharedInstance].wifiMac = (int)mac;
// 4. Returns the pairing token.
NSString *nodeId = [NSString stringWithFormat:@"%02x", (int)address];
[[ThingSmartActivator sharedInstance] getTokenWithMeshId:[ThingSmartUser sharedInstance].meshModel.meshId
nodeId:nodeId
productId:[ThingBLEMeshManager sharedInstance].productId
uuid:[ThingBLEMeshManager sharedInstance].uuid
authKey:[ThingBLEMeshManager sharedInstance].authKey
version:[ThingBLEMeshManager sharedInstance].version
success:^(NSString *token) {
// 5. Sets a pairing delegate to receive the activation result.
[ThingSmartActivator sharedInstance].delegate = self;
// 6. Starts Wi-Fi pairing.
[[ThingSmartActivator sharedInstance] startBleMeshConfigWiFiWithSsid:@"Wi-Fi name" password:@"Wi-Fi password" token:token timeout:100];
} failure:^(NSError *error) {
NSLog(@"error: %@", error);
}];
}
- (void)meshActivator:(ThingSmartActivator *)activator didReceiveDeviceId:(NSString *)deviceId meshId:(NSString *)meshId error:(NSError *)error {
// 7. Returns the activation result.
}
Identify mesh connections
Checks whether Bluetooth devices are connected to a mesh network. This result determines the way to send control and operation commands.
// The mesh connection tag. If a Bluetooth device is connected to the mesh network, this value is `yes`.
BOOL isLogin = [ThingBLEMeshManager sharedInstance].isLogin;
Pairing error codes
| Error code | Description |
|---|---|
| 3088 | Failed to activate the device. |
| 3090 | The specified mesh name and password are incorrect. |
| 3091 | Failed to log in. |
| 3092 | Failed to log in and decrypt. |
| 3093 | Failed to query the AuthKey. |
| 3094 | The length of the address has exceeded the upper limit. |
| 3095 | Failed to change the address. |
| 3096 | Failed to write the mesh information. |
| 3097 | The mesh information is empty. |
| 3098 | The mesh device has not been connected to the network. |
| 3099 | Failed to write data. |
| 4000 | An error has occurred while processing the Wi-Fi information. |
| 4001 | The Wi-Fi pairing token is incorrect. |
| 4010 | A timeout error has occurred while logging in. |
| 4011 | A timeout error has occurred while querying AuthKey. |
| 4012 | A timeout error has occurred while modifying the address. |
| 4013 | A timeout error has occurred while writing the mesh information. |
| 4014 | A timeout error has occurred while setting the Wi-Fi information. |
Devices
The device class is ThingSmartDevice. In this class, the deviceType field of ThingSmartDeviceModel indicates a device type. The value of deviceType for mesh devices is ThingSmartDeviceModelTypeSIGMeshSubDev.
Rename a sub-device
API description
- (void)renameMeshSubDeviceWithDeviceId:(NSString *)deviceId name:(NSString *)name success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| deviceId | The device ID. |
| name | The new name. |
| success | The success callback. |
| failure | The failure callback. |
Example
[[ThingSmartUser sharedInstance].mesh renameMeshSubDeviceWithDeviceId:self.device.devId name:name success:^{
// success do
} failure:^(NSError *error) {
// failure do
}];
Add a paired device to a mesh network (v2.0)
The SDK automatically processes this method during pairing. You can ignore this method.
- (void)addSubDeviceWithUuid:(NSString *)uuid
homeId:(long long)homeId
authKey:(NSString *)authKey
nodeId:(NSString *)nodeId
productKey:(NSString *)productKey
ver:(NSString *)ver
success:(void (^)(NSString *devId, NSString *name))success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| uuid | The short address of a Bluetooth sub-device. |
| authKey | The authorization key. |
| nodeId | The mesh node ID (short address). |
| productKey | The product ID. |
| ver | The version number. |
| success | The success callback. |
| failure | The failure callback. |
Example
[[ThingSmartUser sharedInstance].mesh addSubDeviceWithUuid:_uuid homeId:[ThingSmartUser sharedInstance].meshModel.homeId authKey:_authKey nodeId:nodeHex productKey:_selectedPeripheral.productId ver:_selectedPeripheral.version success:^(NSString *devId, NSString *name) {
// success do
} failure:^(NSError *error) {
// failure do
}];
Locally connect to sub-devices
Mesh sub-devices can be connected locally or in another online status. Connects to a mesh device over Bluetooth from a mobile phone on which Bluetooth is enabled. Commands are sent to the device over Bluetooth. You can use deviceModel.isOnline && deviceModel.isMeshBleOnline to check the device connection status.
Connect to sub-devices through a gateway
Mesh sub-devices can also be connected through a gateway. Connect to a mesh device through a mesh gateway from a mobile phone on which Bluetooth is disabled or that is far away from the device. Commands are sent to the device over Wi-Fi. You can use deviceModel.isOnline && !deviceModel.isMeshBleOnline to check the device connection status.
Remove a sub-device
Removes a sub-device from both the cloud and the local app.
Locally remove a sub-device
// Removes the device over Bluetooth.
- (void)kickoutLightWithAddress:(uint32_t)address type:(NSString *)type;
// Removes the device through a gateway.
- (NSString *)rawDataKickoutLightWithAddress:(uint32_t)address type:(NSString *)type;
/**
Sends commands of Raw type to the device.
@param raw The value of Raw type.
@param success The success callback.
@param failure The failure callback.
*/
- (void)publishRawDataWithRaw:(NSString *)raw
pcc:(NSString *)pcc
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
Remove a sub-device from the cloud
- (void)removeMeshSubDeviceWithDeviceId:(NSString *)deviceId success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| deviceId | The device ID. |
| success | The success callback. |
| failure | The failure callback. |
Example
int address = [smartDevice.deviceModel.nodeId intValue] << 8;
// 1. Removes the device from the cloud.
[[ThingSmartUser sharedInstance].mesh removeMeshSubDeviceWithDeviceId:[smartDevice.deviceModel.devId success:^{
} failure:^(NSError *error) {
}];
// 2. Locally removes the device.
// Checks whether the device is connected through a gateway or over Bluetooth.
if ([ThingBLEMeshManager sharedInstance].isLogin) {
[[ThingBLEMeshManager sharedInstance] kickoutLightWithAddress:address type:[smartDevice.deviceModel.pcc];
} else {
[[ThingSmartUser sharedInstance].mesh publishRawDataWithRaw:[[ThingBLEMeshManager sharedInstance] rawDataKickoutLightWithAddress:address type:[smartDevice.deviceModel.pcc] pcc:[smartDevice.deviceModel.pcc success:^{
} failure:^(NSError *error) {
}];
}
Query sub-device status
API description
- (void)getDeviceStatusAllWithAddress:(uint32_t)address
type:(NSString *)type;
Parameters
| Parameter | Description |
|---|---|
| address | The IP address of the device. |
| type | The category and type of the device. |
Groups
Certain devices on a mesh network can be grouped, so they can be controlled with group control commands. For example, all lights are added to a group. Users can control the switch status and colors of the group and thus control all lights in the group with the same properties.
The following methods of ThingSmartBleMeshGroup are available.
Create a mesh group
-
The value of
localIdfor a mesh group starts from0x8001and is sequentially incremented. -
A mesh group and its sub-devices follow the same rules of categories and types.
-
Currently, each mesh network supports up to 255 groups and each device can be added to up to 8 groups at the same time.
We recommend that devices of different categories do not belong to the same group. Otherwise, group device control might fail due to different device features.
API description
+ (void)createMeshGroupWithGroupName:(NSString *)groupName
meshId:(NSString *)meshId
localId:(NSString *)localId
pcc:(NSString *)pcc
success:(ThingSuccessInt)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| groupName | The name of the mesh group. |
| meshId | The mesh ID. |
| localId | The local short address of the group. |
| pcc | The category and type of the group device. |
| success | The success callback. |
| failure | The failure callback. |
Example
NSInteger localId = 0x8001;
[ThingSmartBleMeshGroup createMeshGroupWithGroupName:@<Group name> meshId:[ThingSmartUser sharedInstance].meshModel.meshId localId:[NSString stringWithFormat:@"%lx", localId] pcc:#<The category and type of the group> success:^(int result) {
// success do
// Queries the group instance.
self.meshGroup = [ThingSmartBleMeshGroup meshGroupWithGroupId:result];
} failure:^(NSError *error) {
// failure do
}];
Add sub-devices to a mesh group
Before a sub-device can be added to a mesh group, it must be verified both locally and in the cloud. Multiple sub-devices must be added one by one to the mesh group. They cannot be removed concurrently in the same task.
API description
// Locally-connected sub-device.
// The result is returned by `ThingBLEMeshManagerDelegate`.
- (void)addDeviceAddress:(uint32_t)deviceAddress type:(NSString *)type groupAddress:(uint32_t)groupAddress;
// ThingBLEMeshManagerDelegate
- (void)deviceAddGroupAddress:(uint32_t)address error:(NSError *)error;
// Sub-device connected through a gateway.
// Queries the command of Raw type to add a sub-device to a mesh group.
- (NSString *)rawDataAddDeviceAddress:(uint32_t)deviceAddress groupAddress:(uint32_t)groupAddress type:(NSString *)type;
API description
Sends pass-through commands to the device.
- (void)publishRawDataWithRaw:(NSString *)raw
pcc:(NSString *)pcc
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
// The result is returned by ``ThingSmartBleMeshDelegate` - (void)bleMeshReceiveRawData:(NSString *)raw`.
// ThingSmartBleMeshDelegate
- (void)bleMeshReceiveRawData:(NSString *)raw;
Parameters
| Parameter | Description |
|---|---|
| raw | The value of Raw type. |
| success | The success callback. |
| failure | The failure callback. |
API description
Records the operation in the cloud after the verification and continues to add the next sub-device.
- (void)addDeviceWithDeviceId:(NSString *)deviceId success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| success | The success callback. |
| failure | The failure callback. |
Example
- (void)addDeviceToGroup:(ThingSmartDeviceModel *)model {
int nodeId = [model.nodeId intValue] << 8;
// Records the IP address of the current device for future use.
_address = nodeId >> 8;
if ([ThingBLEMeshManager sharedInstance].isLogin) {
// Bluetooth LE
[[ThingBLEMeshManager sharedInstance] addDeviceAddress:nodeId type:self.meshGroup.meshGroupModel.pcc groupAddress:[self.meshGroup.meshGroupModel.localId intValue]];
} else {
// Wi-Fi
[[ThingSmartUser sharedInstance].mesh publishRawDataWithRaw:[[ThingBLEMeshManager sharedInstance] rawDataAddDeviceAddress:nodeId groupAddress:[self.meshGroup.meshGroupModel.localId intValue] type:self.meshGroup.meshGroupModel.pcc] pcc:self.meshGroup.meshGroupModel.pcc success:^{
} failure:^(NSError *error) {
}];
}
// The current operation is flagged as adding a device.
_isAdd = YES;
// Customizes a timeout value. After this timeout period, the failure callback is executed and the system continues to add the next device. Recommended value: `5`. Unit: seconds.
}
#pragma mark - ThingBLEMeshManagerDelegate
- (void)deviceAddGroupAddress:(uint32_t)address; {
NSLog(@" --- deviceAddGroupAddress %d ", address);
if (_address == address) {
[self.meshGroup addDeviceWithDeviceId:_devId success:^{
// Proceeds to add the next device after the success callback.
} failure:^(NSError *error) {
}];
}
}
#pragma mark - ThingSmartBleMeshDelegate
// Adds sub-devices that are connected through a gateway to a mesh group.
- (void)bleMeshReceiveRawData:(NSString *)raw {
if ([[raw substringWithRange:NSMakeRange(4, 2)] isEqualToString:@"d4"] && _address == [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(0, 2)]]) {
if (raw.length < 14) {
NSLog(@"Length error of raw data.");
return;
}
BOOL isNewProtocol = [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(10, 2)]] == 255;
if (isNewProtocol) {
int state = [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(12, 2)]];
if (state == 1 || state == 255) {
NSLog(@"The device is added to the group.");
} else {
// Proceeds to add the next device after the failure callback.
return;
}
}
[self.meshGroup addDeviceWithDeviceId:_devId success:^{
// Proceeds to add the next device after the success callback.
} failure:^(NSError *error) {
}];
}
}
Remove sub-devices from a group
Similar to the addition process, before a sub-device can be removed from a mesh group, it must be verified both locally and in the cloud. Multiple sub-devices must be removed one by one from the mesh group. They cannot be removed concurrently in the same task.
API description
// Locally-connected sub-device.
// The result is returned by `ThingBLEMeshManagerDelegate`.
- (void)deleteDeviceAddress:(uint32_t)deviceAddress type:(NSString *)type groupAddress:(uint32_t)groupAddress;
// ThingBLEMeshManagerDelegate
- (void)deviceAddGroupAddress:(uint32_t)address error:(NSError *)error;
// Sub-device connected through a gateway.
// Queries the command of Raw type to remove a sub-device from a mesh group.
- (NSString *)rawDataDeleteDeviceAddress:(uint32_t)deviceAddress groupAddress:(uint32_t)groupAddress type:(NSString *)type;
API description
- (void)publishRawDataWithRaw:(NSString *)raw
pcc:(NSString *)pcc
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
// The result is returned by ``ThingSmartBleMeshDelegate` - (void)bleMeshReceiveRawData:(NSString *)raw`.
// ThingSmartBleMeshDelegate
- (void)bleMeshReceiveRawData:(NSString *)raw;
Parameters
| Parameter | Description |
|---|---|
| raw | The value of Raw type. |
| success | The success callback. |
| failure | The failure callback. |
API description
Records the operation in the cloud after the verification and continues to add the next sub-device.
- (void)removeDeviceWithDeviceId:(NSString *)deviceId success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| deviceId | The device ID. |
| success | The success callback. |
| failure | The failure callback. |
Example
- (void)deleteDeviceFromGroup:(ThingSmartDeviceModel *)model {
int nodeId = [model.nodeId intValue] << 8;
// Records the IP address of the current device for future use.
_address = nodeId >> 8;
if ([ThingBLEMeshManager sharedInstance].isLogin) {
// Bluetooth LE
[[ThingBLEMeshManager sharedInstance] deleteDeviceAddress:nodeId type:self.meshGroup.meshGroupModel.pcc groupAddress:[self.meshGroup.meshGroupModel.localId intValue]];
} else {
// Wi-Fi
[[ThingSmartUser sharedInstance].mesh publishRawDataWithRaw:[[ThingBLEMeshManager sharedInstance] rawDataDeleteDeviceAddress:nodeId groupAddress:[self.meshGroup.meshGroupModel.localId intValue] type:self.meshGroup.meshGroupModel.pcc] pcc:self.meshGroup.meshGroupModel.pcc success:^{
} failure:^(NSError *error) {
}];
}
// The current operation is flagged as removing a device.
_isAdd = NO;
// Customizes a timeout value. After this timeout period, the failure callback is executed and the system continues to add the next device. Recommended value: `5`. Unit: seconds.
}
#pragma mark - ThingBLEMeshManagerDelegate
- (void)deviceAddGroupAddress:(uint32_t)address; {
NSLog(@" --- deviceAddGroupAddress %d ", address);
if (_address == address) {
[self.meshGroup removeDeviceWithDeviceId:_devId success:^{
// Proceeds to add the next device after the success callback.
} failure:^(NSError *error) {
}];
}
}
#pragma mark - ThingSmartBleMeshDelegate
// Adds sub-devices that are connected through a gateway to a mesh group.
- (void)bleMeshReceiveRawData:(NSString *)raw {
if ([[raw substringWithRange:NSMakeRange(4, 2)] isEqualToString:@"d4"] && _address == [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(0, 2)]]) {
if (raw.length < 14) {
NSLog(@"Length error of raw data.");
return;
}
BOOL isNewProtocol = [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(10, 2)]] == 255;
if (isNewProtocol) {
int state = [TPUtils getIntValueByHex:[raw substringWithRange:NSMakeRange(12, 2)]];
if (state == 1 || state == 255) {
NSLog(@"The device is added to the group.");
} else {
// Proceeds to add the next device after the failure callback.
return;
}
}
[self.meshGroup removeDeviceWithDeviceId:_devId success:^{
// Proceeds to remove the next device after the success callback.
} failure:^(NSError *error) {
}];
}
}
Query a mesh group instance
API description
+ (instancetype)meshGroupWithGroupId:(NSInteger)groupId;
Parameters
| Parameter | Description |
|---|---|
| groupId | The group ID. |
groupId is different from localId. It is the group ID returned from the cloud after the group is created. All group operations require the address indicated by localId, rather than the group ID.
Rename a mesh group
API description
- (void)updateMeshGroupName:(NSString *)meshGroupName success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| meshGroupName | The name of the mesh group. |
| success | The success callback. |
| failure | The failure callback. |
Delete a mesh group
Deletes a mesh group locally or from the cloud, in a similar way like removing a device.
API description
// Locally remove the device.
- (void)deleteGroupAddress:(uint32_t)groupAddress type:(NSString *)type;
// Sub-device connected through a gateway.
- (NSString *)rawDataDeleteGroupAddress:(uint32_t)groupAddress type:(NSString *)type
API description
// Sends commands of Raw type to the device.
- (void)publishRawDataWithRaw:(NSString *)raw
pcc:(NSString *)pcc
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| raw | The value of Raw type. |
| success | The success callback. |
| failure | The failure callback. |
API description
// Removes the device from the cloud.
- (void)removeMeshGroupWithSuccess:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| success | The success callback. |
| failure | The failure callback. |
Example
[self.meshGroup removeMeshGroupWithSuccess:^{
// The success callback.
} failure:^(NSError *error) {
// The failure callback.
}];
// Locally-connected sub-device.
if ([ThingBLEMeshManager sharedInstance].isLogin) {
// Removes a group over Bluetooth.
[[ThingBLEMeshManager sharedInstance] deleteGroupAddress:[self.meshGroup.meshGroupModel.localId intValue] type:self.meshGroup.meshGroupModel.pcc];
} else {
// Wi-Fi
// Removes a group through a gateway.
[[ThingSmartUser sharedInstance].mesh publishRawDataWithRaw:[[ThingBLEMeshManager sharedInstance] rawDataDeleteGroupAddress:[self.meshGroup.meshGroupModel.localId intValue] type:self.meshGroup.meshGroupModel.pcc] pcc:self.meshGroup.meshGroupModel.pcc success:^{
} failure:^(NSError *error) {
}];
}
Query a mesh group device
API description
- (void)getDeviveListInfoWithSuccess:(void (^)(NSArray <ThingSmartDeviceModel *> *deviceList))success failure:(ThingFailureError)failure;
Example
[self.meshGroup getDeviveListInfoWithSuccess:^(NSArray<ThingSmartDeviceModel *> *deviceList) {
// The success callback.
} failure:^(NSError *error) {
// The failure callback.
}];
Control
Smart devices are managed with DPs. Thing mesh devices are also controlled by device DPs.
Mesh commands carry DP data when they are sent to target devices.
Command format
DPs are sent to control devices in the following format: {"(dpId)" : "(dpValue)"}. Example: @{@"101" : @"44"}. For more information about DPs, see Device Control.
Send DPs to control a device
API description
- (void)publishNodeId:(NSString *)nodeId
pcc:(NSString *)pcc
dps:(NSDictionary *)dps
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| nodeId | The short address of a Bluetooth sub-device. |
| pcc | The product category and type. |
| dps | The DPs in the dictionary format. |
| success | The success callback. |
| failure | The failure callback. |
Example
int address = [[self.smartDevice deviceModel].nodeId intValue] << 8;
[self.mesh publishNodeId:[NSString stringWithFormat:@"%d", address] pcc:self.smartDevice.deviceModel.pcc dps:@{@"1":@(1)} success:^{
// success do
} failure:^(NSError *error) {
// error do
}];
Send DPs to control a group
API description
- (void)multiPublishWithLocalId:(NSString *)localId
pcc:(NSString *)pcc
dps:(NSDictionary *)dps
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| localId | localId |
| pcc | The product category and type. |
| dps | The DPs in the dictionary format. |
| success | The success callback. |
| failure | The failure callback. |
Example
int address = [[self.meshGroup meshGroupModel].localId intValue];
[self.mesh multiPublishWithLocalId:[NSString stringWithFormat:@"%d", address] pcc:self.meshGroup.meshGroupModel.pcc dps:@{@"1":@(1)} success:^{
// success do
} failure:^(NSError *error) {
// error do
}];
Send data of Raw type
ThingBLEMeshManager provides commands to send data of Raw type.
Sends commands of Raw type to devices
API description
- (void)publishRawDataWithRaw:(NSString *)raw
pcc:(NSString *)pcc
success:(ThingSuccessHandler)success
failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| raw | The value of Raw type. |
| success | The success callback. |
| failure | The failure callback. |
Update device data
Updates device data. The device response is returned by the delegate ThingSmartHomeDelegate.
API description
// Updates DP data.
- (void)home:(ThingSmartHome *)home device:(ThingSmartDeviceModel *)device dpsUpdate:(NSDictionary *)dps;
Update
A unified method for OTA firmware updates has been implemented in SDK v3.35.5 and later versions. For more information, see Firmware Update.
If you do not opt for the simplified OTA process, continue with the section below.
Get firmware update information
For more information, see Get Firmware Update Information.
Update sub-devices
Before the update, make sure that the target device has been connected over Bluetooth.
-
To run only a pairing task, enter the default mesh
nameandpassword. Then, only
- (void)bleMeshManager:(ThingBLEMeshManager *)manager didScanedDevice:(ThingBleMeshDeviceModel *)device;ofThingBLEMeshManagerDelegatereturns the scanning result. -
To connect a paired device to a mesh network, enter the
nameandpasswordof the created mesh network. The data is returned by cloud-based API methods. Then, the paired device is automatically connected to the mesh network. The system also automatically queries the online status of each device once on the mesh network.
API description
- (void)startScanWithName:(NSString *)name
pwd:(NSString *)pwd
active:(BOOL)active
wifiAddress:(uint32_t)wifiAddress
otaAddress:(uint32_t)otaAddress;
Parameters
| Parameter | Description |
|---|---|
| name | The name of the mesh network. |
| pwd | The password of the mesh network. |
| active | Specifies whether to pair and activate a device. |
| wifiAddress | The Wi-Fi address. This parameter is required for pairing a gateway and set to 0 for other types of devices. |
| otaAddress | The IP address of the OTA update device. This parameter is required for OTA update and set to 0 for other types of devices. |
The pairing result will be returned by ThingBLEMeshManagerDelegate.
API description
Connects to the mesh network to enable the update.
- (void)notifyLoginSuccessWithAddress:(uint32_t)address;
Parameters
| Parameter | Description |
|---|---|
| address | The IP address of the device. |
Send update package after callback
- (void)sendOTAPackWithAddress:(NSInteger)address version:(NSString *)version otaData:(NSData *)otaData success:(ThingSuccessHandler)success failure:(ThingFailureHandler)failure;
Parameters
| Parameter | Description |
|---|---|
| address | The IP address of the device. |
| version | The version number. |
| otaData | The update data. |
| success | The success callback. |
| failure | The failure callback. |
Update version number in the cloud
- (void)updateDeviceVersion:(NSString *)version type:(NSInteger)type success:(ThingSuccessHandler)success failure:(ThingFailureError)failure;
Parameters
| Parameter | Description |
|---|---|
| version | The version number. |
| type | The type of firmware. |
| success | The success callback. |
| failure | The failure callback. |
Example
1. Prepare for the update.
int otaAddress = [self.device.deviceModel.nodeId intValue] << 8;
// Connected without a gateway.
[[ThingBLEMeshManager sharedInstance] startScanWithName:[ThingSmartUser sharedInstance].meshModel.code pwd:[ThingSmartUser sharedInstance].meshModel.password active:NO wifiAddress:0 otaAddress:otaAddress];
[ThingBLEMeshManager sharedInstance].delegate = self;
2. Receive the callback and send the update package.
- (void)notifyLoginSuccessWithAddress:(uint32_t)address {
[[ThingBLEMeshManager sharedInstance] sendOTAPackWithAddress:address version:@"Target version number" otaData:_otaData success:^{
[self updateVersion];
} failure:^{
NSLog(@"ota failure!");
}];
}
3. Update the version number in the cloud.
- (void)updateVersion {
WEAKSELF_AT
[self.smartDevice updateDeviceVersion:_upgradeModel.version type:_upgradeModel.type success:^{
// success do..
} failure:^(NSError *error) {
// error do..
}];
}
Update light format in smart scenes
Before the update, make sure that the firmware supports smart scenes.
Scenes 1 to 4 are the static color mode. Update Scene 1:
{set_scene1="0ff808000000000E0"}
`0`: the static color mode
`ff`: R
`80`: G
`80`: B
`00`: W, warm
`00`: C, cold
`00`: L, brightness
`00`: S, step (set to `0`)
`E0`: V, the validity of `RGBWCLS`. `RGB` validity is `E0` and `WCL` validity is `1C`.
Scenes 5 to 8 are the dazzling mode. Update Scene 5:
{set_scene5="180ff560055AA0055AA"}
`1`: the dazzling mode
`80`: L, brightness of `HLS`
`ff`: S, saturation of `HLS`
`56`: the binary value `01010110`. Higher 5 bits indicate the gradient time=10 (unit: 200 ms). It represents the real time 10 × 200 ms = 2s. Lower 3 bits indicate the number of gradient groups=6 groups.
`00`, `55`, `AA`, `00`, `55`, and `AA`: H, hue of `HLS`, 6 groups
Based on the values of `L` and `S`, as well as `H` for each group, the RGB values of six groups are calculated.
0 c7 ed cc c8 37 64 00 e0
Start a scene and send `null` to query the values for the scene.
{set_scene1=null}
Switch to white: 109 = "white"
Switch to color: send the `rgb` command or `109 = "colour"`.
Switch to Scene 1: 109 = "scene_1"
Switch to Scene 2: 109 = "scene_2"
Switch to Scene 3: 109 = "scene_3"
...
Switch to Scene 8: 109 = "scene_8"
Set Scenes 1 to 8: sequentially send DPs 111 to 118.
For example, to set Scene 5: 115 = "0f19ec27f806400e0"
The format follows the previously mentioned DP format.
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback
