Terms

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.

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.

Device classification rules (categories and types)

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

  • Device type:
    • Standard type: 1
    • Raw: 2
  • Bluetooth mesh products are classified into the following product categories:
    • Lighting (01): smart lights ranging from cool white lights (C) to white and colored lights (RGBCW)
    • Electrical (02): one to six-outlet sockets
    • Remote control (05): one to six-button remote controls
  • Product types of a category:
    • Smart lights ranging from cool white lights (C) to white and colored lights (RGBCW) (01–05)
    • One to six-outlet power strips (01–06)
    • One to six-button remote controls (01–06)

• Example:

  Product	Category value	Description
  Standard white and colored light (RGBCW)	1510	1015 in the little-endian format: 1: standard device 01: light 5: white and colored light (RGBCW)
  Standard 4-outlet power strip	2410	1024 in the little-endian format: 1: standard device 02: socket 4: 4-outlet power strip
  Raw type of device	xx20	20xx in the little-endian format: 2 represents a raw type of device.

Create a Bluetooth mesh network

A home can belong to multiple Bluetooth mesh networks, but one Bluetooth mesh network is recommended for each home. Before the request, check whether a Bluetooth mesh network is created. If not, you can call this API method to create one.

API description

+ (void)createSIGMeshWithHomeId:(long long)homeId
                        success:(void(^)(ThingSmartBleMeshModel *meshModel))success
                        failure:(ThingFailureError)failure;

Parameters

Parameter	Description
homeId	The home ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

ThingSmartHome *home = #<The initialized home instance>;
long long homeId = home.homeModel.homeId;
[ThingSmartBleMesh createSIGMeshWithHomeId:homeId success:^(ThingSmartBleMeshModel *meshModel) {
    // success do...
} failure:^(NSError *error) {
    NSLog(@"create mesh error: %@", error);
}];

Delete a Bluetooth mesh network

API description

Deletes a Bluetooth mesh network. If sub-devices are included in the mesh group, they are 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 Bluetooth mesh networks in a home

API description

Returns a list of mesh networks for an initialized home instance.

- (void)getSIGMeshListWithSuccess:(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 getSIGMeshListWithSuccess:^(NSArray<ThingSmartBleMeshModel *> *list) {
    // success do
} failure:^(NSError *error) {
    NSLog(@"get Bluetooth mesh list error: %@", error);
}];

Query a Bluetooth mesh instance

API description

+ (instancetype)bleMeshWithMeshId:(NSString *)meshId homeId:(long long)homeId;

Parameters

Parameter	Description
meshId	The Bluetooth mesh ID.
homeId	The home ID.

Example

// Returns the mesh instance `sigMeshModel` for the `home` instance of the `ThingSmartHome` class.
ThingSmartBleMeshModel *sigMeshModel = [self getCurrentHome].sigMeshModel;

Initialize a Bluetooth mesh network controller

Initializes a Bluetooth mesh network controller to implement features, such as device scanning, pairing, and connection.

API description

+ (ThingSmartSIGMeshManager * _Nullable)initSIGMeshManager:(ThingSmartBleMeshModel *)meshModel
                                                      ttl:(NSInteger)ttl
                                                  nodeIds:(NSArray * _Nullable)nodeIds

Parameters

Parameter	Description
meshModel	The Bluetooth mesh model.
ttl	The maximum number of times a message can be forwarded over a Bluetooth mesh network. Default value: 8.
nodeIds	The list of nodeId for each device on a Bluetooth mesh network, excluding low-power nodes.

Get a Bluetooth mesh network controller

Returns a Bluetooth mesh network controller only after ThingSmartBleMesh is used to initialize one.

API description

+ (ThingSmartSIGMeshManager * _Nullable)getSIGMeshManager:(NSString *)meshId;

Parameters

Parameter	Description
meshId	The Bluetooth mesh ID.

Bluetooth mesh operation classes are included in the file ThingSmartSIGMeshManager.

Configure online profile of networked Bluetooth mesh devices

The default online profile is ThingSIGMeshOnlineProfileMeshNetworkLogin.

API description

typedef NS_ENUM(NSUInteger, ThingSIGMeshOnlineProfile) {
    // By default, devices go online after they are connected to a Bluetooth mesh network.
    ThingSIGMeshOnlineProfileMeshNetworkLogin,
    // Check whether devices are online or offline after they are connected to a Bluetooth mesh network.
    ThingSIGMeshOnlineProfileMeshQuery,
};

@interface ThingSIGMeshConfigModel : NSObject

@property (nonatomic, assign) ThingSIGMeshOnlineProfile onlineProfile;

@end

- (void)setConfig:(ThingSIGMeshConfigModel *)configModel;

Connect to a Bluetooth mesh sub-device

Connects to a Bluetooth mesh sub-device with ScanForProxyed. For more information, see Pairing.

- (void)startScanWithScanType:(ThingSmartSIGScanType)scanType
          meshModel:(ThingSmartBleMeshModel *)meshModel __deprecated_msg("This method is deprecated, Use startSearch instead");

- (void)startSearch;

Scan for sub-devices ready for pairing

API description

Starts scanning for a Bluetooth mesh device ready for pairing. When the device is discovered, it can be paired. In a pairing process, the Bluetooth mesh device joins the target mesh network based on certain communication technologies.

- (void)startScanWithScanType:(ThingSmartSIGScanType)scanType
          meshModel:(ThingSmartBleMeshModel *)meshModel __deprecated_msg("This method is deprecated, Use startSearch instead");

- (void)startSearch;

Parameters

Parameter	Description
scanType	The type of scanning. Devices that are paired or not paired can be discovered. If paired devices are discovered, they automatically join the target mesh network.
meshModel	The information about the Bluetooth mesh model.

Example

//[ThingSmartSIGMeshManager sharedInstance].delegate = self;
// ScanForUnprovision, // Scans for devices that are not paired.
// ScanForProxyed, // Scans for paired devices.
//[[ThingSmartSIGMeshManager sharedInstance] startScanWithScanType:ScanForUnprovision
//                            meshModel:home.sigMeshModel];

    ThingSmartSIGMeshManager *manager = [ThingSmartBleMesh getSIGMeshManager:@"meshId"];
    manager.delegate = self;
    [manager startSearch];

Callback

After a device is discovered, the following method can be implemented in the callback ThingSmartSIGMeshManagerDelegate to query the discovered device.

// A device ready for pairing is discovered.
- (void)sigMeshManager:(ThingSmartSIGMeshManager *)manager
       didScanedDevice:(ThingSmartSIGMeshDiscoverDeviceInfo *)device;

Parameters

Parameter	Description
manager	The information about the Bluetooth mesh manager.
device	The information about the device ready for pairing.

Activate sub-devices

Pairs standard Bluetooth mesh devices.

API description

- (void)startActive:(NSArray<ThingSmartSIGMeshDiscoverDeviceInfo *> *)devList meshModel:(ThingSmartBleMeshModel *)meshModel __deprecated_msg("This method is deprecated, Use startActive: instead");

- (void)startActive:(NSArray<ThingSmartSIGMeshDiscoverDeviceInfo *> *)devList;

Parameters

Parameter	Description
devList	The list of devices to be activated.
meshModel	The information about the Bluetooth mesh model.

Callback for an activated sub-device

API description

After a device is activated or failed to be activated, the following method can be implemented in the callback ThingSmartSIGMeshManagerDelegate.

The sub-device is activated:

- (void)sigMeshManager:(ThingSmartSIGMeshManager *)manager
    didActiveSubDevice:(ThingSmartSIGMeshDiscoverDeviceInfo *)device
                 devId:(NSString *)devId
                 error:(NSError *)error;

Parameters

Parameter	Description
manager	The information about the Bluetooth mesh manager.
device	The device information.
devId	The device ID.
error	The error message that might be returned during activation. If it is returned, name and deviceId are empty.

API description

The sub-device failed to be activated:

- (void)sigMeshManager:(ThingSmartSIGMeshManager *)manager
 didFailToActiveDevice:(ThingSmartSIGMeshDiscoverDeviceInfo *)device
                 error:(NSError *)error;

Parameters

Parameter	Description
manager	The information about the Bluetooth mesh manager.
device	The device information.
error	The error message that might be returned during activation.

Stop activating a sub-device

Stops pairing a Bluetooth device during either the device scanning or pairing stage.

API description

- (void)stopActiveDevice;

Identify Bluetooth mesh connections

Checks whether Bluetooth devices are connected to a Bluetooth 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 = [ThingSmartSIGMeshManager sharedInstance].isLogin;

BOOL isLogin = [ThingSmartBleMesh getSIGMeshManager:@"meshId"].isLogin;

Pair a Bluetooth mesh gateway

• Pairs a Bluetooth mesh gateway in Wi-Fi Easy Connect (EZ) mode. For more information, see Wi-Fi EZ Mode.
• Pairs a Bluetooth Low Energy (LE) and Wi-Fi combo gateway. For more information, see Pair a combo device.

Pair a sub-device with a Bluetooth mesh gateway

Pairs a sub-device with a Bluetooth mesh gateway. For more information, see Pair sub-devices.

Pairing error codes

Error code	Description
701	An error has occurred while connecting to the device over Bluetooth.
702	An error has occurred while processing the composition response.
703	A composition timeout error has occurred.
704	Failed to add appkey.
705	A timeout error has occurred while adding appkey.
706	An error has occurred while processing the network transmission response.
707	A network transmission timeout error has occurred.
708	An error has occurred while processing the publication model response.
709	A publication model timeout error has occurred.
710	An error has occurred while processing the response of adding bind.
711	A timeout error has occurred while adding bind.
712	An IdentifySet timeout error has occurred.

Query a device instance

API description

+ (instancetype)deviceWithDeviceId:(NSString *)devId;

Parameters

Parameter	Description
devId	The device ID.

Connect a mesh device over Bluetooth

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 a mesh device through a Bluetooth mesh gateway

Users can connect to a mesh device through a Bluetooth 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.

Query Bluetooth mesh sub-device status

API description

- (void)getDeviceStatusWithDeviceModel:(ThingSmartDeviceModel *)deviceModel;

Parameters

Parameter	Description
deviceModel	The device model.

Remove a Bluetooth mesh sub-device

The device removal method is simplified and applies to all devices. For more information, see Remove devices.

Generate a group ID in the cloud

API description

+ (void)getBleMeshGroupAddressFromCluondWithMeshId:(NSString *)meshId
                    success:(ThingSuccessInt)success
                    failure:(ThingFailureError)failure;

Parameters

Parameter	Description
meshId	The Bluetooth mesh ID.
success	The success callback with the decimal value of localId returned.
failure	The failure callback.

Create a Bluetooth mesh group

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 Bluetooth mesh group.
meshId	The Bluetooth mesh ID.
localId	The local short address of the group. It is a 2-byte hexadecimal string.
pcc	The category and type of the group device.
success	The success callback with a group ID returned.
failure	The failure callback.

Add a device to a mesh group over Bluetooth

API description

Adds a device to a group. The following method of ThingSmartSIGMeshManager is used.

- (void)addDeviceToGroupWithDevId:(NSString *)devId
                     groupAddress:(uint32_t)groupAddress;

Parameters

Parameter	Description
devId	The device ID.
groupAddress	The address of the group.

Callback

// The callback for `ThingSmartSIGMeshManagerDelegate`.
- (void)sigMeshManager:(ThingSmartSIGMeshManager *)manager
didHandleGroupWithGroupAddress:(nonnull NSString *)groupAddress
          deviceNodeId:(nonnull NSString *)nodeId
             error:(NSError *)error;

Parameters

Parameter	Description
manager	The information about the manager.
groupAddress	The hexadecimal Bluetooth mesh address of the group.
nodeId	The hexadecimal Bluetooth mesh node address of the device.
error	The failure callback.