Profile

Kevin_Fu

Profile Data

Screen Name: Kevin_Fu

Screen Name*

Title

First Name

Address:

Last Name

URL (i.e. Company, Github, LinkedIn)

LinkedIn account

Company

Phone number

Country

Bio

Indicates required field*

My Activities
Following

Member

Action

Date

Kevin_Fu

Updated KBA_BT_0513: IV Update & Recovery Procedure and Sequence Number Storing Strategy on Knowledge Base

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 Index	IV Update Flag	IV Update Procedure State	IV Index Accepted	IV Index used when transmitting
n	0	Normal	n-1, n	n
m (m=n+1)	1	In Progress	m-1, m	m-1
m	0	Normal	m-1, m	m

Table 1: IV Update procedure summary

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

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.
Replace the main.c file of the iv_update project with the main.c in the ${extract_folder}/iv_update folder.
Replace the app.c file of the iv_recovery project with the app.c in the ${extract_folder}/iv_recovery folder.
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.
Build both projects and flash them to 2 boards respectively.
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

System boots, node Sequence number is 0x30000.
Short press the PB0 once, the sequence number increments to 0x30001.
The same as step 2. After that, reset the device.
System boots, node sequence number is 0x40000. After that, directly reset the device without letting it send any packet.
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:

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

Sep 05 2019, 6:22 AM

Kevin_Fu

Updated KBA_BT_0509: Bluetooth Mesh Host Provisioner on Knowledge Base

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, but it has some limitations

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

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

Make it as automatic as possible so that it can be used for any 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 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.

Note: the SoC provisioner has the full implementation of provisioning and configuring a device into a network, which is easier to understand and more suitable for beginners.

Capabilities

The host provisioner 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
Blacklist devices from a network

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. For more information, you can go through KBA_BT_0510: Blacklisting Nodes From Bluetooth Mesh Network.

	Remove	Blacklist
Network key change	No	Yes
Node state	Unprovisioned	Provisioned, but not in the previous network anymore
Target needs to work normally	Yes	No

Table 1. Comparison between removing and blacklisting

Configuration File

The example supports 2 configuration file format - XML or JSON. Examples of both file formats are available in the config folder of the project.

NOTE: XML is NOT PLANNED TO MAINTAIN after this article is out, it doesn't make a lot sense to maintain 2 parsers to do the same thing. The current XML related stuff can be a reference, but JSON will be used for further development.

Dependencies

Hardware & SDK

IDE – Simplicity Studio 4
SDK – Bluetooth Mesh SDK 1.4.0 GA or newer, the latest version is always recommended.
NCP target – At least 1 Bluetooth Mesh compatible boards - EFR32xG12, EFR32xG13 or EFR32MG21 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
NCP host - POSIX compatiable machine to run the host application. Running the application on Windows may need some porting afford, THIS HAS ONLY BEEN TESTED ON Linux and Cygwin.

Library

This project uses the open source library for parsing the XML and JSON files, by setting the symbols XML_SUP or JSON_SUP to 1 to include the corresponding parser source file to the project, as well as below library.

libxml2 - Download and install it from xmlsoft.org or https://github.com/GNOME/libxml2. It's a XML parser and used for parsering the xml configuration files.
json-c - Download and install it from https://github.com/json-c/json-c. It's used for parsing the JSON configuration files.

Architecture

Figure 1. Functional Diagram

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

Event dispenser - read events from NCP target and dispense them to all modules.
Config generic parser - Abstract layer for parsing different types of config files, provides the configuration to all other modules.
Main Loop - Coordinates all the other modules, has below main tasks.
- Loads configuration via Config generic parser
- Executes the loaded action callbacks.
- Sends data to Config generic parser to synchronize with the configuration files if any configuration changes, e.g. any device gets provisioned.
- Sends data to logging.
- Reads project configuration via project config, write back on changes.
Action Loader
- Decides which action (adding, configuring, removing or blacklisting) to take according to the configuration passed from Config generic parser.
Logging - Receives data from other layers and writes to the log file.
Console - Receives user input.
Project config - Loads the project configurations from the Project config file.
Add/Configure/Remove/Blacklist Devices - Main loop loads the action and execute the action callbacks in these modules.

Note: 1. The dashed boxes are not implemented, it's reserved for further development. 2. JSON and XML are the only supported file format by now.

Configuration Files

The host provisioner takes 2 configuration files as input - template file and node configuration file. The template file contains the templates that could be referenced by the node, it's like a group configuration. For example, there are 100 nodes using the same configuration, all the 100 nodes can reference to the same template to avoid the same configuration duplicates for 100 times. The node configuration file includes all the configuration information to each node which will be configured later. For the configurations both present in the the node configuration file and the template file, the ones in the node configuration will be useLibraryd.

Template File

Below are the fields may present in the template file.

Name	Description
Id	Reference identifier of this template, referenced by the node configuration
TTL	Default "Time to live" value
Features	Indicates if the feature is supported (1) or not (0) or keep it as it is now (Not presenting)
SNB	Enable or disable the secure network beacons
Net_Retransmit	Network transmission settings, including count and interval
Pub	Publication settings, including address and bound application key index
Bind	Appkey indexes to be bound to all the models
Sub	Subscription address list

Table 2. Template Fields

Node Configuration FileTemplate File

Keys

When it comes to Bluetooth Mesh, there are 3 types of key which are used and known by users - Network key, application key and device key. Network and application key can be assigned by the user application, and the device key is automatically generated.

Note: Currently, only one subnet, meaning one network key, is supported by the example.

Name	Description
RefID	Reference identifier for other fields to reference
Id	The network/application key index
Value	16 bytes key value
Done	The LSB indicates if the key is configured properly

Table 3. Keys Fields of Node Configuration

Nodes

All the fields defined in table 1 can present in the node configuration file.

Name	Description
UUID	16 bytes device UUID of the node
Addr	unicast address of the primary element of the node, 0 for unprovisioned/unassigned node
Err	error bit masks to record where the last failure is
Tmpl	template identified by ID to load to the node
Blacklist	The 4 LSB bits indicate if to blacklist the node, the 4 MSB bits indicate if to remove the node
Done	The 4 LSB bits indicate if the node is provisioned, the 4 MSB bits indicate if the node is configured

Table 4. Nodes Fields of Node Configuration

Truth table and behaviors:

blacklist(4 MSB bits)	blacklist(4 LSB bits)	done(4 LSB bits)	done(4 MSB bits)	Action	Note
0	0	0	should always be 0	To be added	Initial state of a node that is not in the network
1	0	0	should always be 0	None	Not in the network (either has been removed or never added)
0	1	0	should always be 0	None	Not in the network (either has been blacklisted or never added)
0	1	1	doesn't matter	To be blacklisted	The node is in the network and the provisioner will soon blacklist it
0	0	1	0	None	Already in the network, but configuration wasn't successful or need reconfiguring
1	0	1	doesn't matter	To be removed	The node is in the network and the provisioner will soon remove it
0	0	1	1	None	Already in the network and configuration done

Table 5. True Table and Behaviors

Features

There are some features available from this example, showing as below. Be aware that the more features and the example is, the more complex the code is.

Provision & Configure Devices Simultaneously

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 maybe 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 15-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 6 minutes
Asynchronous way - around 1 minute

Console

A simple console is implemented to receive commands from user. Users can add any customized command by adding an new item to CMDs array in console_callback.c and corresponding callback in the console_callbacks.c.

Command	Usage	Description
fr	fr [1/0]	1 - Factory Reset, 0 - normal reset (default)
h	h	Print usage
g	g [1/0]	Starts/Stops operations, will reload the configuration file, any check if any devices need to be added/configured/removed/blacklisted, executes if yes
p	p [node index]	Pass the operations for the indexed node
s	s	Switch the action priority (if there are devices to be added/blacklisted/removed, which should be done firstly)
list	list	List all the devices in the provisioner device database, including UUID, Device key etc.
set	set option [value]	Set the option to value
get	get [option]	Get the option value, default to get all
exit	exit	Exit program

Table 6. Supported Commands

Action Loader

The action loader will read the node configurations and decides which action (adding, configuring, removing or blacklisting) to take. The action loader will use the truth table and the priority action to determine the next action that the main loop should handle. Note, configuring devices can happen together with adding devices or alone, but not with blacklisting/removing devices.

Secure & Insecure NCP support

The provisioner supports both secure NCP and the insecure NCP. 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.

Retry

To increase the robustness, retry has been implemented. Given that retry probably won't solve the error other than timeout and out of memory, so the current implementation will only retry on timeout and out of memory events received. For other errors, it will end the current operation immediately and record the failure status to the node configuration file. 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.

Free Mode

When enable the free mode, the provisioner will scan for nearby unprovisioned device beacons, and create one item for each in the node configuration XML file with UUID recorded and tmpl field to be 0xFF which is used to identify if the node template is valid (not 0xFF) or not. The next time provisioner loads the XML file, it will pass all the tmpl=0xFF items and gives a warning to users to configure them. Typical procedure to configure a 2-light and 1-switch network.

type 'set fm' to enable free mode
open the xml file and find them in the xml file to configure the recorded items
type 'g' to provision and configure them

Logging

If turn on the symbol DEBUG_PRINT, all the log will be written to the file log/prov.log with the format - FILE:LINE -> Real log. Log Level, it supports any levels of logging, currently 3 are used - log (highest level), message and error (lowest), with setting the log level to a specific value, the logging equals to or less than it will take affect.

Symbols in Makefile

There are some symbols in the makefile, which affect how the project is compiled. Below are the description for them.

DBG - Possible value 1 and 0.
- 1 - Use the parameters defined in config.h.
- 0 - Parameters need to pass when run the application.
DBGP - As mentioned above in section Logging
PLVL - Print level, there are some levels (Error, Message, Log) defined in config.h, if the value is less than the defined level, the defined level print will not be out to terminal.
JSON_SUP - 1 to support Json configuration file, 0 to disable.
XML_SUP - 1 to support XML configuration file, 0 to disable.

It's recommended to enable all levels of print for debugging, and you may need to modify the implementation to fit your own requirements. The provided implementation is just an example.

Use It

The config/template.[xml|json] files in the project is an example to get started with a scenario that 5 rooms, each room has light and switch, there is a master switch to control all the lights in all rooms. The config/conf_xxx.xml files in the project are examples of the node configuration files.

Follow below steps to run it:

Create a ncp-empty-target example based on the board you use, build and program the board. If using a WSTK, you can flash the pre-built image directly.
Check if Max Prov Sessions >= MAX_PROV_SESSIONS and Max Foundation Client Cmds >= MAX_CONCURRENT_CONFIG_NODES. If you want more nodes can be configured at the same time, modify the Max Prov Sessions and Max Foundation Client Cmds and do the 1st step again.
Connect the NCP target and host UART interface, it uses hardware flow control by default. If you want to disable it, you should modify both sides.
Unzip the attachment, then build the host application, e.g. "make". NOTE: You may need to specify where the json-c or xml2 path and the corresponding header files path because we may have different settings on installation of the libraries.
If want to use the secure NCP, you need to run the ncp daemon which is located in ${SDK_FOLDER}//app/bluetooth/examples_ncp_host/ncp_daemon firstly.
Run the application, e.g. "sudo ./build/asyncprov -m u -p /dev/ttyACM0 -b 115200 -f config/conf_full.xml" if _DBG is 0, "sudo ./build/asyncprov" if _DBG is 1.
If everything is OK, you will soon see "Ready" on the terminal. Then you can interact with the application by typing commands.

Some Usage Examples:

Here are some typical operations:

To add a node, modify both blacklist and done to "00"
To blacklist a node from a network, modify the 4 LSB bits of blacklist to 1 - "01"
To remote a node from a network, modify the 4 MSB bits of blacklist to 1 - "10"
To re-add a blacklisted/removed node, after the node is blacklisted, its blacklist field should not equal to "00" and done field should be "00", modify the blacklist to "00". NOTE: Make sure the node is in unprovisioned state and sending unprovisioned beacon.
To retry configure nodes which are failed previously, type "g" command.
To change the configuration to a node, change the configuration in the config file, then modify the done flag of the node to 01 and type "g" command.

Below is the flow to configure a network from scratch, which contains 50 lights and 6 switches. Each 10 of the 50 nodes are assigned to room 1-5 configuration in the template, and 6 switches are assigned to room 1-5 switch and the master switch.

Make sure that there is no device other than the 50+6 devices is sending unprovisioned device beacons. This is based on the assumption that you don't have a way to get the UUID from a device. If you could get the UUID of devices, this step doesn't matter.
Run the application with a non-existing config file as the parameter, the application will create a basic node configuration file. E.g. sudo ./provisioner -m u -p /dev/ttyACM0 -b 115200 -f config/confnew.json, then the conf_new.json will be created automatically, if _DBG is set to 0, you need to specify the file name in config.h file.
Turn off all the lights and switches. Type "set fm [1]" to the application console so that it will start to scan for unprovisioned device beacons and record them if found.
Turn on the switches one by one after you see "Found an unprovisioned device, recorded it into the config file", because the application will always add the newly found device before all the nodes so you will know the real device and UUID pair. Modify the 'tmpl' fields in the node configuration file to reference them to the specific room switch template.
Do the same to record all the lights, because each 10 lights will have the same configuration, so each time turn on 10 lights to record. Also modify the 'tmpl' feild of each node to the specific room light template.
All the nodes should have been added to the node configuration file, type 'g' to start adding and configuring them. This takes time.
Ideally, all nodes should be added and configured properly. Press the buttons on the switches to verify. If any configuration fails, type 'g' to start reconfigure those failed nodes.
Then you can start to try other functionalities, e.g. removing the room 1 lights, blacklist the 2 lights from room 2, move all the lights in room 3 to room 4.

Figure 2. 50 lights all off

Figure 3. 50 lights all on

Sep 03 2019, 8:51 AM

Kevin_Fu

Updated KBA_BT_0509: Bluetooth Mesh Host Provisioner on Knowledge Base

Prior to this example, we have the SoC mode provisioner example introduced in KBA_BT_0501: BT Mesh embedded provisioner example, but it has some limitations

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

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

Make it as automatic as possible so that it can be used for any 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 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.

Note: the SoC provisioner has the full implementation of provisioning and configuring a device into a network, which is easier to understand and more suitable for beginners.

Capabilities

The host provisioner 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
Blacklist devices from a network

	Remove	Blacklist
Network key change	No	Yes
Node state	Unprovisioned	Provisioned, but not in the previous network anymore
Target needs to work normally	Yes	No

Table 1. Comparison between removing and blacklisting

Configuration File

The example supports 2 configuration file format - XML or JSON. Examples of both file formats are available in the config folder of the project.

Dependencies

Hardware & SDK

IDE – Simplicity Studio 4
SDK – Bluetooth Mesh SDK 1.4.0 GA or newer, the latest version is always recommended.
NCP target – At least 1 Bluetooth Mesh compatible boards - EFR32xG12, EFR32xG13 or EFR32MG21 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
NCP host - POSIX compatiable machine to run the host application. Running the application on Windows may need some porting afford, THIS HAS ONLY BEEN TESTED ON Linux and Cygwin.

Library

libxml2 - Download and install it from xmlsoft.org or https://github.com/GNOME/libxml2. It's a XML parser and used for parsering the xml configuration files.
json-c - Download and install it from https://github.com/json-c/json-c. It's used for parsing the JSON configuration files.

Architecture

Figure 1. Functional Diagram

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

Event dispenser - read events from NCP target and dispense them to all modules.
Config generic parser - Abstract layer for parsing different types of config files, provides the configuration to all other modules.
Main Loop - Coordinates all the other modules, has below main tasks.
- Loads configuration via Config generic parser
- Executes the loaded action callbacks.
- Sends data to Config generic parser to synchronize with the configuration files if any configuration changes, e.g. any device gets provisioned.
- Sends data to logging.
- Reads project configuration via project config, write back on changes.
Action Loader
- Decides which action (adding, configuring, removing or blacklisting) to take according to the configuration passed from Config generic parser.
Logging - Receives data from other layers and writes to the log file.
Console - Receives user input.
Project config - Loads the project configurations from the Project config file.
Add/Configure/Remove/Blacklist Devices - Main loop loads the action and execute the action callbacks in these modules.

Note: 1. The dashed boxes are not implemented, it's reserved for further development. 2. JSON and XML are the only supported file format by now.

Configuration Files

Template File

Below are the fields may present in the template file.

Name	Description
Id	Reference identifier of this template, referenced by the node configuration
TTL	Default "Time to live" value
Features	Indicates if the feature is supported (1) or not (0) or keep it as it is now (Not presenting)
SNB	Enable or disable the secure network beacons
Net_Retransmit	Network transmission settings, including count and interval
Pub	Publication settings, including address and bound application key index
Bind	Appkey indexes to be bound to all the models
Sub	Subscription address list

Table 2. Template Fields

Node Configuration FileTemplate File

Keys

Note: Currently, only one subnet, meaning one network key, is supported by the example.

Name	Description
RefID	Reference identifier for other fields to reference
Id	The network/application key index
Value	16 bytes key value
Done	The LSB indicates if the key is configured properly

Table 3. Keys Fields of Node Configuration

Nodes

All the fields defined in table 1 can present in the node configuration file.

Name	Description
UUID	16 bytes device UUID of the node
Addr	unicast address of the primary element of the node, 0 for unprovisioned/unassigned node
Err	error bit masks to record where the last failure is
Tmpl	template identified by ID to load to the node
Blacklist	The 4 LSB bits indicate if to blacklist the node, the 4 MSB bits indicate if to remove the node
Done	The 4 LSB bits indicate if the node is provisioned, the 4 MSB bits indicate if the node is configured

Table 4. Nodes Fields of Node Configuration

Truth table and behaviors:

blacklist(4 MSB bits)	blacklist(4 LSB bits)	done(4 LSB bits)	done(4 MSB bits)	Action	Note
0	0	0	should always be 0	To be added	Initial state of a node that is not in the network
1	0	0	should always be 0	None	Not in the network (either has been removed or never added)
0	1	0	should always be 0	None	Not in the network (either has been blacklisted or never added)
0	1	1	doesn't matter	To be blacklisted	The node is in the network and the provisioner will soon blacklist it
0	0	1	0	None	Already in the network, but configuration wasn't successful or need reconfiguring
1	0	1	doesn't matter	To be removed	The node is in the network and the provisioner will soon remove it
0	0	1	1	None	Already in the network and configuration done

Table 5. True Table and Behaviors

Features

There are some features available from this example, showing as below. Be aware that the more features and the example is, the more complex the code is.

Provision & Configure Devices Simultaneously

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.

'Single thread' way - around 6 minutes
Asynchronous way - around 1 minute

Console

Command	Usage	Description
fr	fr [1/0]	1 - Factory Reset, 0 - normal reset (default)
h	h	Print usage
g	g [1/0]	Starts/Stops operations, will reload the configuration file, any check if any devices need to be added/configured/removed/blacklisted, executes if yes
p	p [node index]	Pass the operations for the indexed node
s	s	Switch the action priority (if there are devices to be added/blacklisted/removed, which should be done firstly)
list	list	List all the devices in the provisioner device database, including UUID, Device key etc.
set	set option [value]	Set the option to value
get	get [option]	Get the option value, default to get all
exit	exit	Exit program

Table 6. Supported Commands

Action Loader

Secure & Insecure NCP support

Retry

Free Mode

type 'set fm' to enable free mode
open the xml file and find them in the xml file to configure the recorded items
type 'g' to provision and configure them

Logging

Symbols in Makefile

There are some symbols in the makefile, which affect how the project is compiled. Below are the description for them.

DBG - Possible value 1 and 0.
- 1 - Use the parameters defined in config.h.
- 0 - Parameters need to pass when run the application.
DBGP - As mentioned above in section Logging
PLVL - Print level, there are some levels (Error, Message, Log) defined in config.h, if the value is less than the defined level, the defined level print will not be out to terminal.
JSON_SUP - 1 to support Json configuration file, 0 to disable.
XML_SUP - 1 to support XML configuration file, 0 to disable.

It's recommended to enable all levels of print for debugging, and you may need to modify the implementation to fit your own requirements. The provided implementation is just an example.

Use It

Follow below steps to run it:

Create a ncp-empty-target example based on the board you use, build and program the board. If using a WSTK, you can flash the pre-built image directly.
Check if Max Prov Sessions >= MAX_PROV_SESSIONS and Max Foundation Client Cmds >= MAX_CONCURRENT_CONFIG_NODES. If you want more nodes can be configured at the same time, modify the Max Prov Sessions and Max Foundation Client Cmds and do the 1st step again.
Connect the NCP target and host UART interface, it uses hardware flow control by default. If you want to disable it, you should modify both sides.
Unzip the attachment, then build the host application, e.g. "make". NOTE: You may need to specify where the json-c or xml2 path and the corresponding header files path because we may have different settings on installation of the libraries.
If want to use the secure NCP, you need to run the ncp daemon which is located in ${SDK_FOLDER}//app/bluetooth/examples_ncp_host/ncp_daemon firstly.
Run the application, e.g. "sudo ./build/asyncprov -m u -p /dev/ttyACM0 -b 115200 -f config/conf_full.xml" if _DBG is 0, "sudo ./build/asyncprov" if _DBG is 1.
If everything is OK, you will soon see "Ready" on the terminal. Then you can interact with the application by typing commands.

Some Usage Examples:

Here are some typical operations:

To add a node, modify both blacklist and done to "00"
To blacklist a node from a network, modify the 4 LSB bits of blacklist to 1 - "01"
To remote a node from a network, modify the 4 MSB bits of blacklist to 1 - "10"
To re-add a blacklisted/removed node, after the node is blacklisted, its blacklist field should not equal to "00" and done field should be "00", modify the blacklist to "00". NOTE: Make sure the node is in unprovisioned state and sending unprovisioned beacon.
To retry configure nodes which are failed previously, type "g" command.
To change the configuration to a node, change the configuration in the config file, then modify the done flag of the node to 01 and type "g" command.

Make sure that there is no device other than the 50+6 devices is sending unprovisioned device beacons. This is based on the assumption that you don't have a way to get the UUID from a device. If you could get the UUID of devices, this step doesn't matter.
Run the application with a non-existing config file as the parameter, the application will create a basic node configuration file. E.g. sudo ./provisioner -m u -p /dev/ttyACM0 -b 115200 -f config/confnew.json, then the conf_new.json will be created automatically, if _DBG is set to 0, you need to specify the file name in config.h file.
Turn off all the lights and switches. Type "set fm [1]" to the application console so that it will start to scan for unprovisioned device beacons and record them if found.
Turn on the switches one by one after you see "Found an unprovisioned device, recorded it into the config file", because the application will always add the newly found device before all the nodes so you will know the real device and UUID pair. Modify the 'tmpl' fields in the node configuration file to reference them to the specific room switch template.
Do the same to record all the lights, because each 10 lights will have the same configuration, so each time turn on 10 lights to record. Also modify the 'tmpl' feild of each node to the specific room light template.
All the nodes should have been added to the node configuration file, type 'g' to start adding and configuring them. This takes time.
Ideally, all nodes should be added and configured properly. Press the buttons on the switches to verify. If any configuration fails, type 'g' to start reconfigure those failed nodes.
Then you can start to try other functionalities, e.g. removing the room 1 lights, blacklist the 2 lights from room 2, move all the lights in room 3 to room 4.

Figure 2. 50 lights all off

Figure 3. 50 lights all on

Sep 03 2019, 8:50 AM

Level 6

Level 5

Profile Data

Following 0

Followers 0