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.

	Node Reset	Notes	Blacklisting	Notes
Node status after the procedure	Unprovisioned		Same as before	Stay provisioned
Network Status	Unchanged		Network key changed	Application key may change
Involved in the procedure	Yes	node should be present and function normally in the procedure	No	Node state doesn't matter

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.

	Node Removed from Device Database	Node Not Removed from Device Database
Node Reset	Normal	Abnormal 2
Node Not Reset	Abnormal 1	Need to Continue the Removal Procedure

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.

Introduction

The Gecko SDK and hence Bluetooth SDK gets a regular update, usually on a monthly basis, in the form of major, minor and patch releases. These updates contain important bug fixes, new features, and sometimes they add support for freshly released hardware (new parts or new boards). This article discusses how to update an existing project, once a new release was downloaded to your computer.

Releases

When you download an SDK with a new major or minor version number (e.g. you update from v2.6.2 to v2.7.0) a new SDK folder will be created on your computer, and from that point you can choose which SDK to use when creating a new project. Your already existing projects won't be touched.

In contrast to this, when you download a patch release to your computer, it will automatically overwrite your existing SDK content. E.g. Gecko SDK v2.7.3 will overwrite Gecko SDK v2.7.2 when downloaded. Now, if you create a new project, it will be created using the new patch release. However, your already existing projects will still contain the files originated from the previous patch release! This is because when you create a project, the SDK files will be copied to your project during project creation, and an SDK update won't touch your already created projects. (This is to avoid automatically updating projects that were already tested with the earlier patch release.)

Updating Existing Projects

If you want to update an already existing project, there are to ways to go:

1. Creating a new SoC-Empty project with the new SDK, and merging all your changes that were done on the top of the SoC-Empty project generated with the previous SDK

2. Replacing all SDK files in your already existing project

In general, it is highly recommended to take the first path, as the project generator takes care of copying all the files and making all the configuration needed for the latest SDK version to work.

Updating with Freshly Created SoC-Empty Project

It is recommended to write Bluetooth application in a way, that the application files are completely separated from the SDK files. That's why the SoC-Empty example project contains app.c / app.h files, that implements the application and are independent from the underlying SDK version. (Of course more files can be added implementing application code.) In this case the best way to migrate to a new SDK version is:

1. Create a new SoC-Empty project with the new SDK version

2. Overwrite app.c/app.h with your application

3. Add your other application files (e.g. modules that handles peripherals and provide data for Bluetooth)

4. Copy the needed SDK dependencies into your project from the updated SDK folder (e.g. if you use LE timer in your project, you have to copy em_letimer.c / em_letimer.h into your project)

5. Import your GATT database with the GATT configurator. Find the import button on the right side, and import the gatt.xml file from your old project. Press Generate to generate the GATT database code in your project.

6. You may have applied changes on init_mcu.c, init_board.c, init_app.c in your already existing project. Instead of overwriting these files with the ones from your old project, rather merge in the changes you made. This is important, because these files are not SDK independent, and there may be important changes in them between two SDK versions. Important: do not press Generate in the GATT configurator after this point, as it may regenerate these files, and your changes can disappear!

7. Add your additional include directories (e.g. if you created a new folder for own header files, or you copied SDK files into a new folder) and libraries in the project settings. Important: do not press Generate in the GATT configurator after this point, as it may regenerate project settings, and your changes can disappear!

8. You are ready to build your project.

Updating SDK files in your already existing project

You may also take the other path, and update all SDK files in your project one-by-one. In this case you should

1. Update the /hardware, /platform and /protocol folders in your project. Since these folders in your project contain only a subset of the files existing in the /hardware, /platform, /protocol folders of the SDK (C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\vX.Y), you should copy the files one-by-one instead of copying the whole folders into your project!

2. Check at least main.c, init_mcu.c, init_board.c, init_app.c if they contain any important update since the last SDK version. Create a new SoC-Empty project for your part, and compare the new files with your existing project. If you see any changes that was not done by you, merge those changes in your project.

Some applications require security features beyond those provided by the Bluetooth specification. This article describes the steps necessary for a building a BLE project with mbedtls.

Mbedtls is a library of cryptographic functions, defined here https://tls.mbed.org/api/, which are used by the Silicon Laboratories Bluetooth Low Energy stack. Silicon Labs provides low level drivers for the cryptographic engines in it SoCs to allow mbedtls to run efficiently.

Any application that needs to use mbedtls must remove the prebuilt mbedtls library and build the mbedtls library from source to avoid conflicts. Mbedtls is a highly configurable library with features that can be enabled by defining preprocessor symbols to a configuration file. The basic setup is described below

1. Remove the prebuilt mbedtls.a library from your project as shown.

2. At a minimum, the following files must be added to the project. These are found in the SDK folder under util\third_party\mbedtls

   

3. Add the following to your project's include paths

   util/third_party/mbedtls/include  util/third_party/mbedtls/include/mbedtls util/third_party/mbedtls/sl_crypto/include util/silicon_labs/silabs_core/memory_manager

4. Add the following definition to the preprocessor symbols

   MBEDTLS_CONFIG_FILE="mbedtls_config.h"

5. Copy protocol\bluetooth\ble_stack\inc\soc\mbedtls_config.h from the SDK to the project's protocol\bluetooth\ble_stack\inc\soc folder. This ensures that the project enables all of the mbedtls features that the Bluetooth stack requires. Additional features can be enabled in this file but none of the existing features can be disabled.

6. Add the following to your application code

   #if !defined(MBEDTLS_CONFIG_FILE) #include "mbedtls/config.h" #else #include MBEDTLS_CONFIG_FILE #endif

7. Now you can begin using mbedtls in your application code.

 

 

 

Introduction

Bluetooth 5 introduces several enhancements to advertising. This article discusses the concept of chained advertising.

Discussion

Chained advertising allows advertising packets to be linked or chained together to allow for larger advertisements, up to 1650 bytes, to be sent. A new packet type, AUX_CHAIN_IND, is used to transmit the individual portions of these advertisements. Chained advertising works together with extended advertising and periodic advertising. The following example allows a synchronizer, i.e. the receiver of a periodic advertisement, to synchronize to a chained periodic advertisement and begin receiving these advertisements.

Implementation

Advertiser

The maximum size of a BGAPI command is 255B, which does not allow to use one command to set 1650B of advertisement data. Therefore, version 2.12 of Silicon Labs Bluetooth SDK introduces a new API: gecko_cmd_system_data_buffer_write() to write up to 255 bytes of data to the system data buffer, in which the stacks assembles the full advertisement data. This API can be called multiple times when more than 255 bytes must be written to the buffer.

The sample code provided with this article implements a simple function, writeSystemDataBuffer(), to simplify writing up to 1650 bytes to the system data buffer. Once the desired advertising data has been written to the buffer the application starts advertising. The advertisement will include a service UUID, which the synchronizer will look for, and the sync info, on which the synchronizer can sync on. Next, the periodic advertisement is started. Finally, the data assembled in the system data buffer is transferred to the periodic advertisement by calling another new API: gecko_cmd_le_gap_set_long_advertising_data().

Scanner

The scanner, or synchronizer, begins by starting scanning for advertisements containing the ‘watchable’ service with the UUID f69dd7f9-340a-4693-9e46-c8630c898558. The first step is to request the extended scan response by calling gecko_cmd_le_gap_set_discovery_extended_scan_response(), this provides more information about the scanner than the basic scan response. Next, the scanner sets the discovery timing and type and starts discovery. Advertisements or scan responses are handled by gecko_evt_le_gap_extended_scan_response_id event handler. This event handler first filters out any packets which are not extended advertising packets. Next, the advertisement is searched for the service UUID mentioned above by calling findServiceInAdvertisement(). When an advertisement containing this UUID is found, the scanner syncs to this device by calling gecko_cmd_sync_open().

The sample code for the scanner/synchronizer includes event handlers for sync_open and sync_closed events. The sync_closed event is triggered when a sync timeout expires and is used to start scanning again. The gecko_evt_sync_opened_id event is purely informative and simply prints a message indicating that a sync has been opened. The gecko_evt_sync_data_id is triggered whenever sync data is received. This event handler handles three situations:

• data received complete,

• data received with more to follow and

• data truncated.

The first situation occurs either when the advertisement fits in a single packet or when the last packet in a chain is received, in either case the data is saved. The second situation occurs when data is received, and more is expected. When this happens, event handler saves the data and begins reassembly the advertisement. If subsequent data is expected, but none is received, the status is set to data truncated. In this case, the sample application considers the data to be corrupt and discards it all by clearing it’s buffer.

Chained advertisements are buffered using the bluetooth_stack_heap found in main.c. The definition must be increased as shown below to provide sufficient space for the data.

uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

Running the Example

The attached example requires two WSTK/radioboards.

1. Create a soc-empty project for your desired radio board.

2. Overwrite the app.c file in this project with app.c from the advertiser folder in the attached zip file.

3. Open main.c and modify the heap size uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

4. Import gatt.xml from the advertiser folder using the ‘Import GATT’ icon in the GATT Configurator. When finished the result should look like this

5. Click generate.

6. Build and download to the first kit.

7. Create another soc-empty for the second kit.

8. Overwrite app.c in this project with app.c from the scanner folder in the attached zip file.

9. Open main.c and modify the heap size uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

10. Open app.h and change the value of DEBUG_LEVEL from 0 to 1 to enable debug printing.

11. Build and download to the second board.

12. Open a terminal program, such as the SimplicityStudio serial console, to view the output from the device. The result should look similar to the followingShortly after starting up, the scanner discovers an advertiser that has come into range and synchronizes with it. Each gecko_evt_sync_data_id comes with a maximum of 250 bytes. The entire advertising packet contains 1650 bytes so we see the final event contains 150 bytes and displays a message indicating that the sync is complete. In the next chained advertisement, one of the advertising packet PDUs is not received, so the data is discarded. After one more successful chained advertisement, the sync is closed due to a timeout 

Conclusion

Chained advertising provides a way of distributing larger amounts of data to multiple synchronizers without the need for connections. The focus of this article is chained advertising, for more information on periodic advertising in general please see our periodic advertising knowledgebase article

 

IV Index & Sequence Number

Below is the definition of Sequence number and IV index from chapters 3.8.3 and 3.8.4 of Mesh Profile Specification v1.0.1.

Sequence Number

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.

Sequence number Storing Strategy

Sequence number should be non-volatile, software stacks should make sure that every time the device sends a valid packet, it should never use the sequence numbers which had been already used before, so it would be a good way to store it in the flash. However, writing flash once per each sequence number increment is probably too often so that the flash may easily wear out before the life time of the real product. To balance the impact, the stack will only write the sequence number to flash at a fixed interval when the sequence number increases by pstore_write_interval_elem_seq times, which is adjustable and located in the dcd.c file in your project. Given that there is a chance that the device may loss power unexpectedly before the interval, which means the real sequence number has not been written to flash, next time when the device boots, it will use the old value in the flash. To avoid the node uses any old sequence number, the node will always increase pstore_write_interval_elem_seq after reset. Besides, the stack will detect if there is valid sequence number increasing between the 2 times of reset, if no, the stack won't increase the sequence number. For more information, you can refer to the example in Figure 1.

NOTE: This is not standard but Silicon Labs' current solution and it may change in the future.

IV Index

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.

Environments

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.5.0 GA or newer, the latest version are always recommended.
• Hardware – At least 2 Bluetooth Mesh compatible boards - EFR32xG12 or EFR32xG13 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• Provisioner - Bluetooth Mesh app on smartphones, or the Host Provisioner.
• Tools – J-Link RTT viewer or serial terminal for print, if using serial terminal, the parameters are as below:
  • Baud rate: 115200
  • Data bits: 8
  • Stop bit: 1
  • Flow control: False

IV Update & Recovery Introduction

IV Update & Recovery Procedure

IV Update Procedure:

The sequence number is 24-bit length, as the example provided above, with 5 seconds cadence, the sequence number will repeat after 2.6 years. To avoid this, the node could start the IV update procedure to update the network to a new IV index so that the sequence number could be reset to 0. The IV update procedure can be initiated by any node in the primary subnet. Table 1 shows the summary of IV update procedure.

IV Recovery Procedure:

A node shall support the IV index recovery procedure because a node that is away from the network for a long time may miss IV Update procedures, in which case it can no longer communicate with the other nodes. In order to recover the IV Index, the node must listen for a Secure Network beacon, which contains the Network ID and the current IV Index.

IV Update & Recovery Limitations

There are some limitations on initiating IV update and recovery procedure, mentioned in chapters 3.10.5 and 3.10.6 of Mesh Profile Specification v1.0.1. Generally, as below:

• If a node in Normal Operation receives a Secure Network beacon with an IV index less than the last known IV Index or greater than the last known IV Index + 42, the Secure Network beacon shall be ignored. Note: This above requirement allows a node to be away from the network for 48 weeks. A node that is away from a network for longer than 48 weeks must be reprovisioned.
• A node shall not start an IV Update procedure more often when once every 192 hours.
• The transition from Normal Operation state to IV Update in Progress state must occur at least 96 hours before the sequence numbers are exhausted.
• After at least 96 hours and before 144 hours of operating in IV Update in Progress state, the node shall transition back to the IV Normal Operation state and not change the IV Index. At the point of transition, the node shall reset the sequence number to 0x000000.
• The node shall not execute more than one IV Index Recovery within a period of 192 hours.

IV Test Mode

Because the limitations mentioned above, it's not easy to test the IV update & recovery procedure. So the IV test mode removes the 96 hours limit. All other behavior of the devices remains unchanged.

Secure Network Beacon

The secure network beacon must be enabled to do the IV update & recovery since it's the carrier of the information that a node is updating the IV index.

NOTE: the Bluetooth Mesh app may not support to configure the secure network beacon state, so you may need to enable it locally with the mesh test class commands. If using the Host Provisioner, then it's not a problem since it supports that.

Running The Example

The example contains two projects - iv_update and iv_recovery, they needs to work together to show how the IV update & recovery procedure works, as well as showing the sequence number storing strategy. Let's call the node flashed with iv_update firmware node U, and the node flashed with iv_recovery firmware node R.

BGAPI Commands & Events

Below is a list of BGAPI commands and events related to the IV update & recovery procedure, all of which are demonstrated in the example.

Commands:

• gecko_cmd_mesh_node_request_ivupdate(...) - this command is used to initiate an IV update procedure.
• gecko_cmd_mesh_node_set_ivrecovery_mode(...) - this command is used for enabling/disabling the IV recovery mode, this can typically be called when the stack reports it's found that the IV of the network is different than the IV of node itself.
• gecko_cmd_mesh_test_set_iv_index(...) - this command is used to set the IV index of the node itself.
• gecko_cmd_mesh_test_set_ivupdate_state(...) - this command is used to forcedly set the iv update procedure state

Events:

• gecko_evt_mesh_node_changed_ivupdate_state_id - This event is generated whenever the node IV update state changes.
• gecko_evt_mesh_node_ivrecovery_needed_id - this event is generated whenever the stack consider the found network IV index is too far to catch up automatically, so that the application will decide if to catch up or not.

Import The Projects

1. Download the attachment and extract it, create a soc-btmesh-switch example project and a soc-btmesh-light example and specify the names, e.g. iv_update and iv_recovery.
2. Replace the main.c file of the iv_update project with the main.c in the ${extract_folder}/iv_update folder.
3. Replace the app.c file of the iv_recovery project with the app.c in the ${extract_folder}/iv_recovery folder.
4. The example uses the Logging System, if you want to use printf instead, you can comment out the #define USE_LOG_MODULE in app.c.
5. Build both projects and flash them to 2 boards respectively.
6. Use Bluetooth Mesh app on smartphones or any other kinds of provisioner to provision the 2 boards to the same network and configure them properly.

Behaviors of The Example

As you can see from the last section that the examples are based on the light and switch examples, so they still keep the basic functionalities and behaviors as the original example. What is modified is listed below:

On the Node U side - iv_update project:

• Very long press on PB0 - It will start the IV update procedure by increasing the IV index by MIN(TEST_IV_HOP, MAX_IV_HOP - 1) + 1 to demonstrate the IV index hop if the node is not in IV update state. Otherwise, it will terminate the IV update procedure if it's in IV update procedure.
• Very long press on PB1 - It will start the IV update procedure by increasing the IV index by 1 to demonstrate the typical IV update procedure if the node is not in IV update state. Otherwise, it will terminate the IV update procedure if it's in IV update procedure.
• Whenever the node sends a packet, it will print the current and remaining sequence number.

On the Node R side - iv_recovery project:

• Press on PB0 - It will disable the IV recovery mode.
• Press on PB1 - It will enable the IV recovery mode.

Test The Sequence Number Increasing

Every time the node U boots and if the node is provisioned, it will print the current and remaining sequence number. Every time any button is pressed to send a packet, the current and remaining sequence number will be printed. You can try to send some packets then reset the device to see what happens. How about if not send packets but reset the node directly? See the result in Figure 1, the pstore_write_interval_elem_seq here is 0x10000.

Figure 1. Sequence Number Increasing

1. System boots, node Sequence number is 0x30000.
2. Short press the PB0 once, the sequence number increments to 0x30001.
3. The same as step 2. After that, reset the device.
4. System boots, node sequence number is 0x40000. After that, directly reset the device without letting it send any packet.
5. System boots, node sequence number is still 0x40000.

Test IV Update & Recovery

Figure 2 shows the procedure of IV update and IV recovery, there are 2 nodes in the same network, as you can see from figure 1, on the left side, it's the print of the node which initiates IV update procedure, this is node U, on the right side, it's the print of the node which catches up the IV update, this is node R. There are 4 times of the IV update & recovery procedure, describing below:

1. From the print of node R you can see the IV recovery mode is disabled after reset. Both node U and R have IV index 158. Node U initiates the IV update from 158 to 159, which is the value of the current IV index of node R plus 1, at the same time, the IV update flag in the secure network beacon is set. So it catches up the IV update procedure automatically without application involved.
2. Manually set the IV index to 189, then starts IV update procedure. Because the current IV index of node R is 159, the IV index sent from node U is 190 which is not equal to 159 + 1, so the node R generates the event gecko_evt_mesh_node_ivrecovery_needed_id to let the application to decide if to catch up the IV update and start the IV recovery procedure. As you can see the IV recovery mode is enabled after it gets the event, so the node catches up to 190.
3. The IV index of node U is 156 and the flag in secure network beacon is not set, which means it's not in IV update procedure. The IV index of node R is 155, it generates the event gecko_evt_mesh_node_ivrecovery_needed_id to let the application to decide if to catch up the IV update and start the IV recovery procedure. The application didn't do it in this case, so the IV index didn't change after reset after a while.
4. The situation is the same as step 3, the only difference is the application enabled the IV recovery mode, so the node catches up the IV index to 156.

Figure 2. IV Update & Recovery Procedure

Introduction

Proxy protocol

The proxy protocol is designed to enable nodes to send and receive the Bluetooth Mesh network packets over a connection-oriented bearer. For example, a node could support GATT but not be able to advertise the Mesh Message AD Type. This node will establish a GATT connection with another node that supports the GATT bearer and the advertising bearer, using the Proxy protocol to forward messages between these bearers.

Roles

The proxy protocol defines two roles: the Proxy Server and the Proxy Client.

The Proxy Server is a node that supports a mesh bearer using the Proxy protocol and at least one other mesh bearer. For example, the Proxy Server can forward mesh messages between the advertising bearer and the GATT bearer.

The Proxy Client supports a mesh bearer using the Proxy protocol. For example, the Proxy Client can use the GATT bearer to send mesh messages to a node that supports the advertising bearer.

Filters

The proxy server uses a filter to decide if to forward the message to the proxy client or not. There are 2 types of filters could be used - white list or black list.

A white list filter has an associated white list, which is a list of destination addresses that are of interest for the Proxy Client. The white list filter blocks all destination addresses except those that have been added to the white list.

A black list filter has an associated black list, which is a list of destination addresses that the Proxy Client does not want to receive. The black list filter accepts all destination addresses except those that have been added to the black list.

The white list filter with an empty list is the default filter type. The Proxy Client can change the filter type as well as configure the addresses in the proxy filter.

 

Environments

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.5.0 GA or newer, the latest version are always recommended.
• Hardware – At least 3 Bluetooth Mesh compatible boards - EFR32xG12 or EFR32xG13 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• Tools – J-Link RTT viewer or serial terminal for print, if using serial terminal, the parameters are as below:
• Baud rate: 115200
• Data bits: 8
• Stop bit: 1
• Flow control: False

 

Details About The Example

The example is based on the light example which is available in the Bluetooth Mesh SDK. The light example is a proxy server which can be connected to forward Bluetooth Mesh network packets to the proxy client. With modification, the proxy client light will disable the PB-ADV bearer and rely on a proxy server to communicate with the network. For demonstration, 3 nodes are needed in the example - one light, one switch and the proxy client light. Because the PB-ADV bearer is turned off, the proxy client light node cannot receive any commands from the switch directly unless it connects to a proxy server node which is the original light node in this setup.

How It Works

Figure 1 shows how the 3 nodes network works.

 

Figure 1. Network Topology

How to Identify The Server Node

After the proxy client node being provisioned, it needs to find a proxy server to communicate with the network. For the proxy server nodes, once they are provisioned with PB-GATT bearer or explicitly enabled the proxy feature, they will start advertising with Mesh Proxy Service immediately. So there must be a way for the proxy client to identify if the advertising node is in the same network or not, is the target node or not? The advertisement sent by proxy server nodes has 2 types of payload for the client nodes to parse and decide if to connect - Network ID and node identity, both of which are encrypted. Currently, the SDK doesn't provide a way to decrypt the payload for application layer, so we probably need some other ways to identify the target server node. In the example, it provides 2 workarounds:

1. Match the network ID without decryption. You can use any Bluetooth scanner to get the proxy service advertisement payload, then record the 8 bytes encrypted network ID. For the client node, it can simply compare the scanned advertisement with the encrypted network ID.
2. Match the BD_ADDR.

NOTE, this is only the limitation for the time being, this should be deprecated when the SDK exposes the APIs for parsing the encrypted payload.

Network Configuration

You need to provision both nodes and configure them properly before you can verify the functionality. Basically, you need 2 addresses to let the node publish to and subscribe from, follow the setup in below picture.

 

Figure 2. Typical Setup

Proxy Client Node Work Flow

The work flow of the proxy client node shows in figure 3.

 

Figure 3. Work Flow

 

Running The Example

1. Download the attachment and extract it, create a soc-btmesh-light project in Simplicity Studio with a specified name.
2. Replace the app.c in your project with the app.c in the attachment.
3. The example uses the Logging System, if you want to use printf instead, you can comment out the #define USE_LOG_MODULE in app.c.
4. Flash 2 boards respectively with light and switch, then provision and configure them properly. Remember to enable the proxy feature on the light node.
5. If using the 1st workaround to identify the proxy server node, do the 6th step, if using the 2nd workaround, do the 7th step.
6. Find a Bluetooth scanner to scan for the proxy server advertisement and record the 8 bytes encrypted network ID in the payload.
7. Get the BD_ADDR of the light node which is the proxy server, e.g. using Simplicity Commander or a Bluetooth scanner etc.
8. If using 1st workaround, modify the #define USE_FAKE_NETWORK_ID 1 and fill the dummy_network_id with the value recorded in the 6th step. If using 2nd workaround, modify the #define USE_FAKE_NETWORK_ID 0 and fill the target_server_node_bd_addr with the value recorded in the 7th step. Build and flash the project to the remaining board.
9. Factory reset the board if needed, then provision and configure the node properly. After which, it will start to find the target server node and connect to it automatically. You can either check the LCD or the logging via serial/RTT to check the status. Once you see the "Proxy configured" on the LCD or "Proxy configured"/"Filter Length = " depending on what type of filter you are using on the logging, you can operate on the switch node to verify if the proxy client light will react or not. If everything goes well, you should be able to see "Req x" where x indicates the number of received requests sent from the switch, see figure 4.

 

Figure 4. LCD Status

Introduction

Bluetooth mesh is based on advertisements, meaning that under the hood the stack is scanning all the time. By default, the scan response events are not passed to the application but they are just consumed by the mesh stack and then silently discarded.

This article illustrated a way to scan BLE advertisements when the Bluetooth mesh stack is running. It uses advertising event filter which allows you to configure which type of events you want to have exposed to the application. It can be used to scan mesh nodes and possibly report the advertisements found to a master node which processes the data.

Implementation

Step1: Configure the advertising event filter by adding this in your boot event handler. For more details about the command refer the Bluetooth Mesh Software API reference manual.

gecko_cmd_mesh_node_set_adv_event_filter(0x7,0,NULL);

0x7: Enabled advertising packet type mask. This indicates the advertisement could be Connectable undirected, Scannable undirected or, Non connectable undirected advertising.

Step 2: Handle the scan response event by adding following case to the handle_gecko_event() function:

case gecko_evt_le_gap_scan_response_id:
        print_scan_resp(&(evt->data.evt_le_gap_scan_response));
        break;

Step 3: Add a function that handles the BLE scan responses, here's a sample:

static void print_scan_resp(struct gecko_msg_le_gap_scan_response_evt_t *pResp)
{
    // decoding advertising packets is done here. The list of AD types can be found
    // at: https://www.bluetooth.com/specifications/assigned-numbers/Generic-Access-Profile
​
    // example of adv data including proxy service data:020106030328180c16281800f03f4f79774c65a2
    // (UUID 0x1828)
​
    // 020106-03032818-0c16281800f03f4f79774c65a2
    const uint8 proxy_UUID[2] = {0x28, 0x18};
​
    int i = 0;
    int ad_match_found = 0;
    int ad_len;
    int ad_type;
​
    while (i < (pResp->data.len - 1))
    {
​
        ad_len  = pResp->data.data[i];
        ad_type = pResp->data.data[i+1];
​
        if (ad_type == 0x03)
        {
            // type 0x03= Complete List of 16-bit Service Class UUIDs
​
            if(memcmp(proxy_UUID, &(pResp->data.data[i+2]),2) == 0)
            {
                ad_match_found = 1;
            }
        }
​
        //jump to next AD record
        i = i + ad_len + 1;
    }
​
    if(ad_match_found)
    {
        for(i=5;i>=0;i--)
        {
            printf("%2.2x", pResp->address.addr[i]);
        }
​
        printf(", RSSI: %d\r\n", pResp->rssi);
    }
}

The above code looks through advertising data in scan response events and searches for the mesh proxy UUID 0x1828. If a proxy advertisement is found, the address of the sender and RSSI are printed to debug output.

Testing

• In Simplicity Studio, select your radio board, select the latest Bluetooth Mesh SDK and create soc-btmesh-light example project for your device.

• Copy and replace the attached file (app.c) into your project.

• Compile and flash to your radio board.

• Open serial console and observe the print statements.

• On another radio board, flash any Bluetooth mesh application consisting of the Mesh Proxy service with UUID 0x1828 and provision it.

This functionality was tested with two BGM13P22 radio boards and v1.4.3 of the Silabs Bluetooth Mesh stack.

Introduction

This article will introduce how to blacklist nodes from a Bluetooth Mesh network and the related APIs when developing with Silicon Labs Bluetooth Mesh SDK. Blacklisting nodes is an important part of the Bluetooth network management, which prevents the "trash-can-attach" risk. It utilizes the key refresh procedure to remove the nodes whose keys are compromised.

When a node is removed from the network, all remaining nodes would have their keys changed such that the removed node would not have knowledge of the new security credentials being used if that node was compromised after being disposed. This is known as the ”trash-can attack.”

There are 2 ways for Bluetooth Mesh network to remove one or more nodes from the network. The first one is via "Config Node Reset" command, the other way is via key refresh, both ways are supported by Silicon Labs Bluetooth Mesh SDK. Table 1 shows a comparison between these 2 ways.

In addition to blacklist node(s) from the network, the key refresh procedure is also capatible to refresh the application key(s), which results in blacklisting node(s) from some specific group(s) but remaining in the network. One note for refreshing the application keys, it's impossible to refresh only the application keys without refresh the bound network key.

How Key Refresh Works

If you are interested with the detailed information about how the key refresh procedure is designed and how it works, you can look into the chapter 3.10.4 of the Mesh Profile Specification 1.0.

Because the Silabs Bluetooth Mesh SDK has implemented this and packed the procedure to simple API calls, it's OK to just understand the procedure in general, it has 3 phase:

1. Receive the net key.
2. Inform the provisioner that the new key has been received.
3. Use the new key and revoke the old key.

Related APIs In Silabs Bluetooth SDK

Commands

• gecko_cmd_mesh_prov_set_key_refresh_blacklist - this is used to add a node to the blacklist list which is maintained by the stack.
• gecko_cmd_mesh_prov_set_key_refresh_appkey_blacklist - same as the above one but for refreshing appkey.
• gecko_cmd_mesh_prov_get_key_refresh_blacklist - this is used to check if a node is in the blacklist list which is maintained by the stack.
• gecko_cmd_mesh_prov_get_key_refresh_appkey_blacklist - same as the above one but for refreshing appkey.
• gecko_cmd_mesh_prov_key_refresh_start - command to start the key refresh procedure, nodes in the blacklist list will get blacklisted.

Test Class Commands

The test class commands are for developing and testing purpose, it's NOT recommended to use in the production firmware.

• gecko_cmd_mesh_test_update_local_key - this is used to update the key locally by a node.
• gecko_cmd_mesh_test_prov_prepare_key_refresh - this command will set the network key and the application key(s) if any which will be used for the next key refresh procedure.

Events

• gecko_evt_mesh_prov_key_refresh_node_update_id - there are 3 parameters carried in this event, key (network key index), phase (which phase the node has moved into) and uuid (UUID of the node). This event indicates that the node has moved to the specific phase.
• gecko_evt_mesh_prov_key_refresh_phase_update_id - this event indicates that the whole network has moved to the specific phase.
• gecko_evt_mesh_prov_key_refresh_complete_id - this event indicates that the key refresh procedure has completed.

Typical Flow

Below is a pseudo code to demonstrate to blacklist 3 nodes with UUID - uuid1, uuid2 and uuid3.

  #define BLACKLIST 1
  #define UUID_LEN  16
  #define NET_KEY_INDEX 0
  #define APP_KEY_NUM_TO_REFRESH 0
  struct gecko_msg_mesh_prov_set_key_refresh_blacklist_rsp_t *pBgRet = NULL;
  struct gecko_msg_mesh_prov_key_refresh_start_rsp_t *pKeyRefStartRet = NULL;

  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid1);
  check the result value, pBgRet->result.
  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid2);
  check the result value, pBgRet->result.
  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid3);
  check the result value, pBgRet->result.


  pKeyRefStartRet = gecko_cmd_mesh_prov_key_refresh_start(netkey_id,
                                                          NET_KEY_INDEX,
                                                          APP_KEY_NUM_TO_REFRESH,
                                                          NULL);
  check the result value, pKeyRefStartRet->result.

  while(1) {
     check the events from the stack.
    switch(evt_id) {
      case gecko_evt_mesh_prov_key_refresh_node_update_id:
        record any information carried by the event if needed.
        break;

      case gecko_evt_mesh_prov_key_refresh_phase_update_id:
        record any information carried by the event if needed.
        break;

      case gecko_evt_mesh_prov_key_refresh_complete_id:
           check the e->data.evt_mesh_prov_key_refresh_complete.result to see if success?
        record the new network key index
        break;
    }
  }

  ...

Example

The project in KBA_BT_0509: Bluetooth Mesh Host Provisioner implements the blacklisting feature, you can use it to try out blacklisting nodes from the network. If you don't have time to go through and understand the whole project, you can just poll out the stuff in blacklisting_devices.c which contains all the blacklisting related code.

A provisioner plays an important role in the Bluetooth Mesh network, which creates and manages the network by adding, configuring and removing devices into/from the network. This article will provide you a ncp host example which works with the ncp target to act as the provisioner. For more information about the ncp mode and ncp host and target, please go through KBA_BT_1602: NCP Host Implementation and Example.

Prior to this example, we have the SoC mode provisioner example introduced in KBA_BT_0501: BT Mesh embedded provisioner example, it has the full implementation of provisioning and configuring a device into a network and is easier to understand and more suitable for beginners. However, it has below limitations:

• In SoC mode, only 14 devices can be added to the same network, while in ncp mode, it supports to add up to 512 devices for now.
• Application and network configuration are fixed at the compiling time, any changes to the network require to re-build and flash the provsioner.
• Due to the limitation of the resources on the WSTK, it has limited features.

Given the above limitations, the host network manager was developed with below ideas in mind.

• Make it as automatic as possible so that it can be used for automatic testing.
• Separate the application and configuration, so that it doesn't need to rebuild the application to apply any configuration changes to the network.
• Configuration file can be changed at any time, the application will check if needs to reload them before issuing a command.
• Robustness improvement, every process may fail because of any reason. Retry and some recovery mechanisms are needed to make the network more robust.
• A console to receive commands from the user. Easy to add any customized command to extend the application.

 

Capabilities

The host network manager supports below functionalities:

• Create network and application keys
• Provision multiple devices into a network simultaneously
• Configure multiple devices simultaneously
  • Add application keys
  • Bind application keys to models
  • Set publication address to models
  • Add subscription addresses to models
  • Set default TTL value
  • Set relay/friend/proxy feature on or off
  • Set the network/relay transmission - count and interval
  • Set Secure Network Beacon on or off
• Remove devices from a network via node reset procedure
• Blacklist devices from a network via key refresh procedure
• Set the light status
  • On or off
  • Lightness
  • Color temperature

NOTE: Removing a node is different than blacklisting a node from the network. Removing is like to ask the node to leave the network actively - provisioner sends a command to force the node to factory reset itself, while blacklist is passively being blacklisted from the network - provisioner sends packets to the reset of the nodes to migrate to a new network key, see table 1. For more information, you can go through KBA_BT_0510: Blacklisting Nodes From Bluetooth Mesh Network.

	Remove	Blacklist
Network key change	No	Yes
Before the procedure	Target needs to work normally	Doesn't matter
After the procedure	Factory reset	Remaining unchanged

Table 1. Comparison between removing and blacklisting

 

Dependencies

Hardware & SDK

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.6.0 GA or newer, the latest version is always recommended.
• NCP target – WSTK with Bluetooth Mesh compatible radio boards - EFR32xG12, EFR32xG13 or EFR32MG21 (x= M, B) based.
• NCP host - POSIX compatiable machine to run the host application, THIS HAS ONLY BEEN TESTED ON Linux and MacOS. Running the application on Windows or other platforms probably needs some porting effort.

Libraries

This project uses the open source library for parsing the JSON configuration files and glib for the data structures. Users needs to install the libraries properly before using the example.

• json-c - Download and install it from https://github.com/json-c/json-c.
• glib - Download and install it from https://developer.gnome.org/
• readline - Download and install it from http://tiswww.case.edu/php/chet/readline/rltop.html

Architecture

Figure 1. Functional Diagram

The architecture of the host network manager is as shown in figure 1. Below is a brief introduction to each module in this diagram.

• Event Handler - read BGAPI events from NCP target and dispatch them to corresponding modules.
• Generic Config Parser - An abstract layer for parsing different types of config files, which provides the configuration to all other modules.
• Configuration Database - Store all the configuration, including network and nodes configuration
• MNG - Loads the configuration from CFG part and deploy to the network.
• Logging - Receives data from other layers and writes to the log file.
• CLI - Receives user input.

Limitation of this design - Only ONE subnet is supported, while multiple subnets feature is supported by the Bluetooth Mesh SDK. It's because the requirements for multiple subnets in practice is not very common yet, so just leave it for future implementation.

Generally, there are 3 parts in the program, CLI, MNG and CFG.

CLI

The command line interface part receives commands from user and pass them to MNG for further processing if needed.

Supported commands

Conventions:

• Each [] stands for an argument iteam, some of them are mandatory to present and some are not, in which case, a default value of the argument is applied.
• Argument followed by ... means variable number of the argument.

Command	Args	Defaults	Usage	Description
sync	[1/0]	1	sync	Start or stop synchronizing the network configuration with the JSON configuration files
reset	[1/0]	0	reset	Reset the device, if argument is 1, erase the storage as well, known as factory reset
info	[addr...]	/	info 0x003a	If no argument is given, shows the overall configuration of the network, if address is given, shows the specific configuration to the node, including UUID, Device key etc.
q	\	/	q	Quit the program
freemode1	[on/off]	on	freemode on	Turning on/off the free mode.
help	\	\	help	Print the usage of all commands.
status	\	\	status	Print the device status.
rmall	\	\	rmall	Remove all the nodes from the network
clrrb	\	\	clrrb	Clear the RM_Blacklist fieldof the nodes
seqset	combination of a, r, b and -	\	seqset ar-	determine the sequence of loadding the adding/removing/blacklisting/none actions.
loglvlset	[e/w/m/d/v] [1/0]	\	loglvlset w	Log with priority "warning" or higher will be sent to the log file, the second parameter determines if the logging will be sent to printf (stdout if not redirect)

Table 2: Network Configuration Commands

Command	Args	Usage	Description
onoff	[on/off] [addr...]	onoff on 0x1203 0x100c	Set the light onoff status, if no address is given, set to all light nodes
lightness	[pecentage] [addr...]	lightness 50 0x1203 0x100c	Set the light lightness status, if no address is given, set to all light nodes
colortemp	[pecentage] [addr...]	colortemp 30 0x1203 0x100c	Set the light color temperature status, if no address is given, set to all light nodes

Table 3: Lighting Control Commands

1. When freemode is on, the device will start scanning for unprovisioned device beacon and record the device information to the backlog in the nodes configuration file if found.

MNG

The MNG part is the core part of the application, which coprate with the other two parts and make sure the network is properly configured according to the configuration files and the received commands.

Features

Simultaneously Provision and Configure Devices

Silicon Labs Bluetooth Mesh SDK supports this feature, as most of the demos uses a 'single thread' way to do it (provision one -> configure one -> provision another -> ...), users may be misled that provision/configure the next device must wait for the compete of the previous one.

To benefit from this, you need to set the 2 fields in the "Memory Configuration" in the NCP target isc file.

• Max Prov Sessions - this determines how many devices can be provisioned by the provisioner simultaneously. There is a define #define MAX_PROV_SESSIONS 4 in adding_devices.h of the host project, this value must be equal or less than the setting in the NCP target memory configuration.

• Max Foundation Client Cmds - this determines how many nodes can be configured by the provisioner simultaneously. There is a define #define MAX_CONCURRENT_CONFIG_NODES 6 in async_config_client.c of the host project, this value must be equal or less than the setting in the NCP target memory configuration.

Below is a rough time comparison of provisioning and configuring a 50-node network between using 'single thread' way and the asynchronous way. The time itself is meaningless because it heavily depends on the environment, how you configure each node, how many retries for timeouts and interval between retries etc..

• 'Single thread' way - around 20 minutes
• Asynchronous way - around 4.5 minutes

Retry

Due to the nature of Bluetooth Mesh technology and the fact that wireless communication is heavily affected by the environments such as packet collision, commands sent to the nodes may be lost. Retry mechanism on the application layer has been implemented to increase the robustness. However, given that retry probably won't solve the error other than timeout or out of memory, so the current implementation will only retry on timeout and out of memory situation. For other errors, it will end the current operation immediately and record the failure status to the node configuration file, so developers could check the error and determine how to deal with it afterwards. It is easy to add any error events to retry, add any specific error event to below the timeout event case in each state callback switch block.

The define symbols in the projconfig.h file determines the maximum retry times for each specific configuration process.

CFG

An example of the configuration files is available in the ${PROJECT_ROOT}/tools/mesh_config/example folder, you could copy it and use it as starting point to configure your network and nodes.

Self Configuration

The content in this file describes how the provisioner should configure itself and how to create the network, see table 4.

What's it	Key	Value	Description
Last sync time1	SyncTime	uint32	Time stamp that the appliaction write to the file most recently
IV index	IVI	uint32
Keys	\	\	Details in Table 5 below
Time To Live	TTL	uint8
Network Transmit Count	TX Parameters - Count	uint8	[0, 7]
Network Transmit Interval	TX Parameters - Interval	uint8	[10, 320]@step10
Config timeout for non-LPN nodes	Config Timeout - Normal	uint16	in milliseconds
Config timeout for LPN nodes	Config Timeout - LPN	uint16	in milliseconds
Publication Groups	PubGroups	uint16array	Not Used Yet
Subscription Groups	SubGroups	uint16array	Not Used Yet

Table 4. Provisioner Config File Content

What's it	Key	Value	Description
Reference ID2	RefId	uint16
Key Index	Id	uint16
Key Value	Value	16BL uint8array
Created successfully?	Done	bool

Table 5. Key Content

Network & Nodes

The content of this file describes how the nodes will be processed, including adding, removing, configuring and blacklisting.

What's it	Key	Value	Description
Last sync time1	SyncTime	uint32	Time stamp that the appliaction write to the file most recently
UUID	UUID	16BL uint8array	16 bytes device UUID of the node
Unicast address	Address	uint16	unicast address of the primary element of the node, 0 for unprovisioned/unassigned node
Error bit masks	Err	uint32	error bit masks to record where the last failure is
Template Identifier	Template ID	uint8	template identified by ID to load to the node
Removing and Blacklisting Flags	RM_Blacklist	uint8	bit 0 indicates if to blacklist the node, bit 4 indicates if to remove the node, other bits reserved
Funtionality	Funtionality	uint8	Funtionality of the node, a light, sensor or others
Configured Flag	Done	uint8	Indicates if the node has been configured properly
Time To Live	TTL	uint8
Network Transmit Count	TX Parameters - Count	uint8	[0, 7]
Network Transmit Interval	TX Parameters - Interval	uint8	[10, 320]@step10
Features supported by the node	Features - *	Structure	Indicates if the feature is supported (1) or not (0)
Model Key Binding settings	Bind Appkeys	uint16array	Appkey reference IDs to bind to the models
Publication settings	Publish To - *	Structure	Parameters for publication
Subscription settings	Subscribe From	uint16array	Addresses the nodes subscribe from
Enable/disable secure network beacon	Secure Network Beacon	uint8	1 to enable, 0 to disable
Backlog	Backlog	Nodes	Nodes in backlog won't be processed

Table 6. Network & Nodes Config File Content

Template

The configuration of one single node might be long, and multiple nodes may have the same configuration just like the concept of group. So the configuration item in the template file provides the configuration for groups. You could add the "Template ID" field to the node and fill it with the specific reference ID of the group. For the case where a specific configuration is both defined in the node field and the group field. The configuration in the node field will be used.

1. By checking the last modification time against last synchronized time to know if the configuration is changed out of the program.
2. The real id is allocated when the key is created successfully, however, in most of the cases, configuration of the network happens before it. So the keys are referenced by the RefId across the configuration files.

Security

Security is extremely important for your products and the Bluetooth Mesh network. The application aims to provide an example or a starting point for developing this sort of application, so it stores the sensitive data including the network and application keys into the file without encryption. That SHALL NEVER be used when developping the real products. How to securely store the data to the file and make the file to be safe is left for developers respectively.

Secure & Insecure NCP

The provisioner supports both secure and insecure NCP, which are 2 ways of commnicating between the NCP host and target provided by Silicon Labs. With secure NCP, the ncp secure daemon must be running and user needs to feed the socket file path with parameter if it's encrypted to the application. With the insecure NCP, user needs to feed the UART port and baud rate.

Utils

This part can be used by any other parts as utils.

Error Code

The error code design is to provide as much information as possible from the return value. Most of the functions in the program returns a err_t which can either be a 64-bit or 32-bit unsigned value. With separating the bits into different fields, it could contain multiple information pieces. The design in this application divides the unsigned value into 3 fields - error code, line and file information where the error code is generated. There are several functions in the err.h and err.c for generating and parsering the unsigned value. In general, when there is a specific error happens, return the error code surrounded by err(x) macro, when getting a non-zero (not ec_success) unsigned return value, use elog(x) to print the error information to the log file or use eprint(x) which calls printf rather than writting to the log file. Figure 2 shows the elog output.

Figure 2. Error Information

Logging

Logging has the level feature which is inspired from Android logging system. The threshold of the logging is settable via 'loglvlset' command, as a result of which, the logging messages with priority lower than the threshold will not be sent to the logging file. See the table 7 for the logging message types with priorities in descending order.

The logging messages will be written to the file system, the path is specified when initializing the logging.

Logging Format: [Time][File:Line][Level]: Log Message...
[2019-12-12 21:22:33][xxx_source_xxx.c:225][MSG]: Initializing...

Key word	Message Type	Note
AST	Assert	Call assert(0) after the message, NON-MASKABLE
ERR	Error	Error messages
WRN	Warning	Warning messages
MSG	Message	Normal messages
DBG	Debug	Debugging message
VER	Verbose	Verbose messages

Table 7. Logging

Figure 3. Demonstration of Logging

Recommended NCP Target Configuration

The NCP target owns the device database of the network, it's important to set the memory configuration properly so that it can actually store the necessary information of the whole network for the target size. In other words, the memory configuration determines how large your network could be.

Below is an example of setting the memory configuration, in which the network target size is 128. You need to set AT LEAST below items to the memory configuration file, which is in the {PROJECT_NAME}.isc file in your ncp target project.

Item	Value	Note
Feature bitmask	0x0001
RPL size	128(0x80)	set to the expected network size if possible
Net Cache Size	128(0x80)	set to the expected network size if possible
Max Provisioned Devices	128(0x80)	set to the expected network size

Table 8. Memory Configuration of NCP Target

Furthermore, there are 2 important settings in NVM3 which is the persistent storage solution used in the Bluetooth Mesh stack. You possibly need to increase the settings below if you increase the network target size. For more information, please go through the AN1135: Using Third Generation Non-Volatile Memory (NVM3) Data Storage.

• NVM3_DEFAULT_CACHE_SIZE
• NVM3_DEFAULT_NVM_SIZE

Usage Example for Typical Scenarios

Get It Running

You need to do at least below steps to get it running.

1. Create a "NCP - Mesh Empty Target" or "NCP - Secure NCP Mesh Empty Target" example based on the board you use.
2. Modify the memory configuration mentioned above to meet your target network size requirement.
3. Properly set the "Max Prov Sessions" and the "Max Foundation Client Cmds" in the memory configuration file, and make sure Max Prov Sessions >= MAX_PROV_SESSIONS and Max Foundation Client Cmds >= MAX_CONCURRENT_CONFIG_NODES
4. Build the program and flash it to your board. Connect it to your host platform and make sure the UART is working.
5. Make sure you have all the dependent libraries installed, and download the application.
6. Speicify the JSON configuration file pathes to SELFCFGFILE_PATH and NWNODES_FILE_PATH symbols in _projconfig.h file. You could specify a non-existing path so the application will create the files with basic configurations and you could modify the configuration afterwards. Note, the folder should exist already.
7. Compile and run the application with proper argument according to your setup. Once you have successfully run it once, the arguments will be written to a cache file, the next time you can emit them if you don't want to change the arguments.
8. A console should start and you could type "help" to get the usage.

Record Devices Nearby

This could be the first step you use the program. Make sure you have the unprovisioned device placed in the direct radio range to the provisioner and they are sending the unprovisioned device beacon. Then you can do the below steps to record them.

1. Start the program.
2. Type freemode on to start recording. If any unprovisioned device beacon is received, it will store the device information to the backlog of the node configuration file.
3. Type freemode off when all the devices are recorded to the backlog.

Move Devices from Backlog to Primary Subnet

As mentioned above, the nearby devices recorded by freemode will be added to backlog. You need to cherry pick those you want to add to your network from the backlog to the primary subnet field.

1. Open the nodes configuration file.
2. Move the nodes you want to operate onto the first item of "Subnets"
3. Change the "Template ID" field of each node based on what configuration you want to apply to the node. Certainly, you could change the configuration as well.

Adding/Configuring Device(s)

1. Make sure you have properly set the configuration to all the nodes in the node configuration file.
2. Start the program if not yet.
3. Type "sync" to start adding them to the network and configuring them.

Blacklisting Node(s)

Assuming that you have established a network because we cannot blacklist nodes if they are not in the network yet.

1. Open the nodes configuration file.
2. Find the node(s) you want to blacklist from the netowkr and change the "RM_Blacklist" field to "0x01". Note, the address of the node SHALL NOT be 0, in which case the node is not yet added to the network. Then save it.
3. Make sure 'b' is in the sequence, you could optionally set it as the first priority action by "seqset" command.
4. Type "sync", once it finishes, you will get the result in your terminal.

Removing Nodes(s)

This procedure is very similar to the last one - Blacklisting Node(s), the only difference is to modify the "RM_Blacklist" Field to "0x10"

Change Configuration to Node(s)

The "Done" field indicates if the node has been configured properly, to change the configuration of nodes, follow the below steps.

1. Open the nodes configuration file.
2. Find the node(s) you want to configure and modify the configuration fields, then change the "Done" field to 0x00.
3. type "sync", the program will load the new configuration and apply to the nodes.

Lighting Control

Once you have the network and the nodes configured, the node functionality is stored in the configuration file respectively. Then you can use the CLI commands to control the light status.

• To set a single node or nodes on, type the command "onoff on 0x000x...", where 0x000x are the unicast address of the nodes.
• To set a group nodes on, type the command "onoff on 0x000x...", where 0x000x are the group address that the group subscribe from.

Project Repo

Available on Github - https://github.com/fuzhen011/nwmng