The Node Reset Procedure is the way to remove a node from a network, which is like the node leaves the network actively. It's different from blacklisting which is the way to move all un-blacklisted nodes to the new network, so the node is left passively. Below table gives a simple comparison between these 2 methods to remove node(s) from network.

The node reset procedure includes below 2 messages:

• Config Node Reset - sent by the provisioner to ask the node to remove itself from the network.
• Config Node Reset Status - sent by the node to acknowledge the node has received the Config Node Reset message.

In general, how the node reset procedure looks like in the ideal situation is like figure 1 shows.

Figure 1

Given that the wireless communication can be affected by many environment factors, especially the packet collision, which results in certain packet cannot be received by the receiving device. Typically, the wireless protocols have a proper way to know the situation happens, then they can just retry sending the missing packets. However, for this procedure, because the node needs to remove itself from the network after sending the Config Node Reset Status message, it won't be able to communicate with the provisioner any more. Let's imagine what happens if either of those 2 packets is missing by the target device.

Figure 2 shows that if the node misses some of the Config Node Reset message.

Figure 2

From the figure you can see, the provisioner sends Config Node Reset then waits for the acknowledgement - the Config Node Reset Status message from the Node, whereas the node doesn't receive the Config Node Reset message successfully, which means the node will never send the acknowledgement. There is a predefined waiting time on the provisioner side, so the provisioner will get the timeout event after the predefined time, then it can retry sending the Config Node Reset message until the acknowledgement is received or it fails for a certain amount of times. In this case, only the user experience will be affected since the time for the procedure increases dramatically becauses of the timeouts.

Figure 3 shows that if the provisioner misses the Config Node Reset Status message.

Figure 3

From the figure you can see, the node receives the Config Node Reset message from the provisioner and acknowledges with the Config Node Reset Status message, then removes itself from the network. However, the message is missed by the provisioner, which means the real node status is uncertain to the provisioner since it doesn't know if the Config Node Reset message is received by the node or not. In this case, the situation is not recoverable, consider:

• No matter how many times the provisioner retries sending the Config Node Reset message, the node will not be able receive anymore because it has already removed itself from the network.
• The node will also never be able to send the Config Node Reset Status message, the reason is the same as above.

Actually, the figure 3 is still idealised. In practice, the provisioner won't know the status of the node before it successfully receives the Config Node Reset Status. So, this brings some problems:

1. It's not easy for the provisioner to decide when to stop retrying sending the Config Node Reset message. Apparently, it would be a deadloop for the provisioner to send Config Node Reset forever if the situation in figure 3 happens without specifying the times.
2. The real status of the node is unknown to the provisioner during this procedure, it could either be 1> the node doesn't receive any of the Config Node Reset messages, the node stay provisioned, or 2> the Config Node Reset Status missed by the provisioner. In both cases, there is no solid indication that the provisioner is OK to remove the node from device database. Below is a table to the cases mentioned above.

Conclusion

All in all, the conclusion is The Node Reset Procedure is UNRELIABLE without any other means of determining the real status of the node.

Ideas

From the above description, the most important thing for this procedure to finish properly is that the provisioner receiving the Config Node Reset Status message successfully. So, to improve the performance, you could try to increase the network retransmission. This can be done temporarily before the node reset procedure, e.g. normally, the network retransmission count is disabled or configured to be a low value. When the provisioner wants to remove the node, it could firstly configure a high network retransmission to the node then start the node reset procedure. See figure 4.

Figure 4

But this is just a way to improve the performance, it doesn't make the procedure to be reliable. Application developers should take this into account if it's desired to make it reliable. For example, based on the assumption that the unprovisioned device will always send unprovisioned device beacon, the provisioner can scan for the unprovisioned device beacon to know if the device is already in unprovisioned state before removes the node from database.

KBA_BT_0515: Bluetooth Mesh Mobile - Import/Export Functionalities Concepts

1. Introduction

The Import and Export feature can be regarded as one of the most important ones in the Bluetooth Mesh Silicon Laboratories’ ADK. Introduced in the 2.2.0 release can allow the User to implement completely new approach to control the Mesh Network. One of the use cases examples we suggest, and which is enabled by this functionality, is active usage of multiple data bases or in other words multiple different Mesh networks in the same application. Currently as stated in the AN1200 document the library does not natively support it but it can be worked around by using the Import and Export. Surely there are many other scenarios to be invented by the Users, and knowing the importance of the topic, we have tried to sum up the key steps that need to be followed, in the Document below.

2. Export

First of all, it is necessary for the Developer to understand how and what information exactly need to be exported into an external file to successfully move the Mesh Network structure between the devices. The Silabs’ ADK does not specify what type of file it needs to be, it is up to Developer to choose a specific format for storing the data base. Our API only provides appropriate methods which can be used to extract the necessary information from the Mesh structure which main components are Network, Subnet, Group, Node, Element and Model. As a help for the Developers to get started, we have also prepared a sample implementation of the Export which you can use as a reference or a starting point for your own, in which we have decided to use a JSON string file as a container for our database.

Warning: Due to complexity of the dependencies between the different objects in the Mesh Structure we were not able to gather all the necessary API for export in this document. Below you will find just examples of the methods which can be used to extract the data. The rest of the necessary functions can be found in the class documentation which was attached to the BLE mesh package in the Simplicity Studio directory.

Also, we would highly recommend, after the successful export procedure, to keep the file protected by implementing an appropriate encryption method according to the Customer's requirements.

2.1 Network

Firstly, it would be necessary to get access to the Network type objects available in the data base. It would allow the developer to extract all the necessary information stored inside and will allow you to get the lists of existing Subnets, Provisioners and Scenes in the Mesh Network. Following that, it is going to be needed to extract the data stored in each of the objects of these three types and then the lower layer as well (SubnetSecurity, NetKey, AddressRange). The API samples were listed below for both platforms.

2.1.1. iOS

• SBMBluetoothMesh:
  • networks – use SBMBluetoothMesh.networks
• SBMNetwork:
  • version – use SBMNetwork.version
  • uuid – use SBMNetwork.uuid
  • name – use SBMNetwork.name
  • timestamp – use SBMNetwork.timestamp
  • subnets – use SBMNetwork.subnets
  • provisioners – use SBMNetwork.provisioners
  • scenes – use SBMNetwork.scenes
• SBMSubnet
  • name – use SBMSubnet.name
  • netKey – use SBMSubnet.netKey
  • subnetSecurity – use SBMSubnet.subnetSecurity
  • groups – use SBMSubnet.groups
  • nodes – use SBMSubnet.nodes
• SBMProvisioner
  • provisionerName – use SBMProvisioner.provisionerName
  • uuid – use SBMProvisioner.uuid
  • allocatedUnicastRange – use SBMProvisioner.allocatedUnicastRange
  • allocatedGroupRange – use SBMProvisioner.allocatedGroupRange
  • allocatedSceneRange – use SBMProvisioner.allocatedSceneRange
• SBMScene
  • name – use SBMScene.name
  • number – use SBMScene.number
  • nodes – use SBMScene.nodes

2.1.2 Android

• Bluetoothmesh:
  • networks – use BluetoothMesh.getNetworks()
• Network:
  • version – use Network.getVersion()
  • uuid – use Network.getUuid()
  • name – use Network.getName()
  • timestamp – use Network.getTimestamp()
  • subnets – use Network.getSubnets()
  • provisioners – use Network.getProvisioners()
  • scenes – use Network.getScenes()
• Subnet
  • name – use Subnet.getName()
  • netKey – use Subnet.getNetKey()
  • subnetSecurity – use Subnet.getSubnetSecurity()
  • groups – use Subnet.getGroups()
  • nodes – use Subnet.getNodes()
• Provisioner
  • provisionerName – use Provisioner.getName()
  • uuid – use Provisioner.getUuid()
  • allocatedUnicastRange – use Provisioner.getAllocatedUnicastRange()
  • allocatedGroupRange – use Provisioner.getAllocatedGroupRange()
  • allocatedSceneRange – use Provisioner.getAllocatedSceneRange()
• Scene
  • name – use Scene.getName()
  • number – use Scene.getNumber()
  • nodes – use Scene.getNodes()

2.2 Group

Having extracted a list of Group objects from each Subnet instance, you would need to access the data stored in those by using the following API samples.

2.2.1 iOS

• SBMGroup:
  • name – use SBMGroup.name
  • address – use SBMGroup.address
  • virtualAddress – use SBMGroup.virtualAddress
  • parentGroup – use SBMGroup.parentGroup
  • appKey – use SBMGroup.appKey
  • subnet – use SBMGroup.subnet

2.2.2 Android

• Group:
  • name – use Group.getName
  • address – use Group.getAddress
  • virtualAddress – use Group.getVirtualAddress
  • parentGroup – use Group.getParentGroup
  • appKey – use Group.getAppKey
  • subnet – use Group.getSubnet

2.3 Node

In the next step you would need to extract the data from the above Node class structure for each Node object in the data base.

2.3.1 iOS

• SBMNode
  • uuid – use SBMNode.uuid
  • name – use SBMNode.name
  • primaryElementAddress – use SBMNode.primaryElementAddress
  • devKey – use SBMNode.devKey
  • deviceCompositionData – use SBMNode.deviceCompositionData
  • settings – use SBMNode.settings
  • security – use SBMNode.security
  • elements – use SBMNode.elements
  • subnets – use SBMNode.subnets

2.3.2 Android

• Node
  • uuid – use Node.getUuid
  • name – use Node.getName
  • primaryElementAddress – use Node.getPrimaryElementAddress
  • devKey – use Node.getDevKey
  • deviceCompositionData – use Node.getDeviceCompositionData
  • settings – use Node.getSettings
  • security – use Node.getSecurity
  • elements – use Node.getElements
  • subnets – use Node.getSubnets

2.4 Element

Next major step would be to extract the Element type objects which were extracted in the previous part.

2.4.1 iOS

• SBMElement
  • name – use SBMElement.name
  • address - use SBMElement.address
  • index - use SBMElement.index
  • location - use SBMElement.location
  • sigModels - use SBMElement.sigModels
  • vendorModels - use SBMElement.vendorModels

2.4.2 Android

• Element
  • name – use Element.getName
  • address – use Element.getAddress
  • index – use Element.getIndex
  • location – use Element.getLocation
  • sigModels – use Element.getSigModels
  • vendorModels – use Element.getVendormodels

2.5 Model

Having extracted the lists of supported models you would need to also export the Model structures as well.

2.5.1 iOS

• SBMModel
  • identifier – use SBMModel.identifier
  • settings – use SBMModel.modelSettings
  • bindedGroups - use SBMModel.bindedGroups

2.5.2 Android

• Model
  • identifier – use Model.getId()
  • settings – use Model.getModelSettings()
  • bindedGroups - use Model.getBindedGroups()

3. Import

Having successfully extracted all the necessary structures of a Mesh Network, it is now time to cover the import procedure to transfer it i.e. into another mobile device. It is a more complex in comparison to the export and there are a few challenges the Developer need to think about to come up with a solution. The following description would require at least basic understanding of Bluetooth Mesh Network mechanisms and safety solutions to enable the Developer to come up with an own solution for the given use case. In our implementation or rather code example we have taken a few shortcuts as this was not prepared for any particular real-life solution but rather for testing and reference for the Customers.

In general, the process would contain from a few key points mentioned below:

• Firstly, it is important to note that the existing data base in the receiver device needs to be emptied before starting the procedure, which means that to be sure it was correctly prepared we would recommend using the clearDatabase method from the BluetoothMesh/ SBMBluetoothMesh class.
• Secondly, the developer needs to take care of creating all the Mesh structure elements and filling them with appropriate data from the source file. For this purpose, we have prepared an implementation of Importer classes which would allow you to use the API to create the objects with specific configurations.
• Lastly, it is necessary to initialize the imported Network with the initializeNetwork method from the BluetoothMesh/SBMBluetoothMesh class. At this point it is necessary for the developer to implement a mechanism for handling the unicast addresses of the provisioners and maintaining both the correct sequence number and IV Index for the Mesh Network.

3.1 Importer class

The Importer/SBMImporter class on both platforms provides two methods createNetwork and performImport. The first one is used to create an object of a NetworkImport/SBMNetworkImport class which contains the API to create and fill all the preliminary MeshNetwork structures in the data base on the receiving device. However, the end responsibility of preparing implementation of creating an appropriate logic to make use of the available functions is on the developer’s side. (The methods were listed and briefly described in the Class Documentation available in the Simplicity Studio directory mentioned in section 2 Export.) Once you have prepared the structure, next step you would need to do is to call the second method from the Importer class which would be performImport. It would transfer all the ‘Import’ objects into the default data base classes and clear the previous instances.

To help you better understand the usage of the Importer we have prepared a code sample for both iOS and Android which shows the usage of these methods.

3.1.1 iOS

func import(from json: String) {
     let decoder = JSONDecoder()
 
     do {
        let meshData = try decoder.decode(JsonMesh.self, from: (json.data(using: .utf8))!)
        // clear database to ensure it's ready for import
        SBMBluetoothMesh.sharedInstance().clearDatabase()
        let importer = meshData.createImporter()
        try importer.performImport()
        let network = SBMBluetoothMesh.sharedInstance().networks()[0]
        let address = 0
        let ivi = 0
        try SBMBluetoothMesh.sharedInstance().initializeNetwork(item, address: address, ivIndex: ivi)
     } catch {
     }
}


func createImporter() -> SBMImporter {
        let importer = SBMImporter()
        
        let networkImport = importer.createNetwork((uuid.data(using: .hexadecimal))!)
        networkImport.name = name
 
        for item in netKeys {
            item.performImport(network: networkImport)
        }
        
        // AppKeys & Groups
        for item in groups {
            item.performImport(network: networkImport, appKeys: appKeys)
        }
        
        for item in provisioners {
            item.performImport(network: networkImport)
        }
        
        for node in nodes {
            node.performImport(network: networkImport)
        }
        
        return importer
}

3.1.2 Android

fun import() { 
    val bluetoothMesh = BluetoothMesh.getInstance() 
    val customAddress = 0 
    val customIvIndex = 0 
    val importer = createImporter() 
    bluetoothMesh.clearDatabase() 
    importer.performImport()
    val network = bluetoothMesh.networks.first() 
    bluetoothMesh.initializeNetwork(network, customAddress, customIvIndex) 
}

private fun createImporter(): Importer { 
    	val importer = Importer() importer.createNetwork(Converter.stringToUuid(jsonMesh.meshUUID!!)) 
        .apply { name = jsonMesh.meshName } 
        .also { 
           handleAppKeys() 
           handleSubnets(it) 
           handleNodes(it) 
           handleProvisioners(it) 
           handleScenes(it) 
       } 
	return importer 
}

3.2 Network initialization

As it can be seen, next step after a successful data import would be the Network initialization which can be done using the initializeNetwork method from the BluetoothMesh/SBMBluetoothMesh class. (In the code examples attached at sections 3.1.1 and 3.1.2 it can be seen how the usage should look like.) At this point, it is important for the Developer to understand the meaning of the three arguments that this function should receive because wrong values of these parameters may have big influence on the ability to control the imported Network by the mobile device.

• Network
  First of the arguments is relatively easy to define because it is going be a Network/SBMNetwork type instance which was created by the Importer/SBMImporter.performImport call and can be obtained by using the bluetoothMesh.networks.first() on Android side or SBMBluetoothMesh.networks[0] on the iOS platform.

Warning: With the current version of the ADK library which is 2.3.0 it is always going to be the first element of the networks list because it does not support importing multiple Network instances.

• Address
  According to the Bluetooth Mesh specification, a provisioner device is still regarded as a Node but with capabilities to add new devices to the Network. This implies that it needs to have a unicast address defined to be identifiable in the structure and it should be unique for a mobile device across mesh. One of the reasons why it is so important is that the address is strictly tied with a certain value of Sequence Number (check out section 3.2.1) and in a case when these two would not match, the provisioner the provisioner device would not be able to control the Network.

• IV Index
  Last but not least important is for the Developer to set a correct IV Index value and because the updates intervals of this value may differ across different Mesh Networks we can not be sure if the value has not changed since the data base has been exported so hard coding the value in the source file would not be a good solution. Luckily, the IV Index can be retrieved from the Secure Network Beacon (for more information please check Bluetooth Mesh Profile Specification rev. 1.0.1 chapter 3.9.3) data so our recommendation would be to implement a mechanism shown in the AN1200: Bluetooth Mesh for iOS and Android ADK section 13.5 Retrieving the IV Index from the Secure Network Beacon (section number valid for a document rev. 1.3) before calling the initializeNetwork method.

3.2.1 Sequence number

Definition taken from Bluetooth Mesh Profile Specification rev. 1.0.1 chapter 3.8.3.

The sequence number, a 24-bit value contained in the sequence number field of the Network PDU, is primarily designed to protect against replay attacks. Elements within the same node may or may not share the sequence number space with each other. Having a different sequence number in each new Network PDU for every message source (identified by the unicast address contained in the SRC field) is critical for the security of the mesh network.

With a 24-bit sequence number, an element can transmit 16,777,216 messages before repeating a nonce. If an element transmits a message on average once every five seconds (representing a fairly high frequency message for known use cases), the element can transmit for 2.6 years before the nonce repeats.

Each element shall use strictly increasing sequence numbers for the Network PDUs it generates. Before the sequence number approaches the maximum value (0xFFFFFF), the element shall update the IV Index using the IV Update procedure (see Section 3.10.5). This is done to ensure that the sequence number will never wrap around.

3.2.2 IV Index

Definition taken from Bluetooth Mesh Profile Specification rev. 1.0.1 chapter 3.8.4.

The IV Index is a 32-bit value that is a shared network resource (i.e., all nodes in a mesh network share the same value of the IV Index and use it for all subnets they belong to).

The IV Index starts at 0x00000000 and is incremented during the IV Update procedure as described in Section 3.10.5. The timing when the value is incremented does not have to be exact, since the least significant bit is communicated within every Network PDU. Since the IV Index value is a 32-bit value, a mesh network can function approximately 5 trillion years before the IV Index will wrap.

The IV Index is shared within a network via Secure Network beacons (see Section 3.9.3). IV updates received on a subnet are processed and propagated to that subnet. The propagation happens by the device transmitting Secure Network beacons with the updated IV Index for that particular subnet. If a device on a primary subnet receives an update on the primary subnet, it shall propagate the IV update to all other subnets. If a device on a primary subnet receives an IV update on any other subnet, the update shall be ignored.

If a node is absent from a mesh network for a period of time, it can scan for Secure Network beacons (see Section 3.10.1) or use the IV Index Recovery procedure (see Section 3.10.6), and therefore set the IV Index value autonomously.

4. Conclusion

As stated at the beginning, the above article shows just a concept of using the Import and Export functionalities available in our mobile library. The mentioned sample implementation will be presented in details with the KBA_BT_0516 which should be available soon on our community forum. In case of any questions regarding this document you can create a support ticket at our web page or comment below.