Hi,

It is a known issue that the property get doesn't work. We have fixed it but the fix will only be available in the next SDK release.

I won't say which one you should choose, but if I have to recommend, I would like to use vendor model. It will be simpler to use vendor model than using property models, and it will also be more flexible for you. Another reason could be that you can't get the next release now.

Thanks,

Kevin

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

Hi,

I will try to explain why this happens but I'm not able to help you to figure out what the data structure is shown in the Android application log. Maybe my colleagues on the mobile side could help you.

When you press the PB1 in the switch board, it will send the light ctl set (unacknowledge) commands to its publish group, all the nodes within the range of its TTL will probably receive the message. If another switch receives, then it may relay the message to the proxy client which is the smartphone. This is why you see the message on Android side.

Thanks,

Kevin

Updated the attachment to work with the latest 1.5.1 SDK, if works with older one, replacement of the stack headers may be needed.

Thanks,

Kevin

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.

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.

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.

Nodes

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

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

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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. All the nodes should have been added to the node configuration file, type 'g' to start adding and configuring them. This takes time.
7. 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.
8. 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

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.

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.

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.

Nodes

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

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

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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. All the nodes should have been added to the node configuration file, type 'g' to start adding and configuring them. This takes time.
7. 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.
8. 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

Added new KBA:

KBA_BT_0513: IV Update & Recovery Procedure and Sequence Number Storing Strategy

Introduction

This Knowledge Base Article (KBA) aims to act as a “master” KBA which keeps a curated index of all the Bluetooth related KBAs divided into logical categories for an easier and more convenient look-up. It may also include non-KBA content which is relevant for designing your Bluetooth application (e.g. app notes or web pages).

If you are just getting started with Silicon Labs Bluetooth solutions then your starting point should be QSG139: Getting Started with Bluetooth® Software Development. At the end of that document you are presented with the flowchart below which shows what documents should be read and in which order. Additionally you can check out our Bluetooth Training page for more training material.

Knowledge Base Articles List

The content listed below is grouped together into categories to make it easier for you to find what you are looking for. Want to know more about security, or looking for a peripheral example, then head down to the right section and see what KBAs or other relevant content has been created under those topics.

Each category has an associated index number and each individual KBA has its own index number within the category. The KBA's are prefixed with KBA_BT_AABB where AA is the category index and BB is the KBA index within that category. The category index numbers are as follows:

• [01] Bluetooth - General
• [02] Bluetooth - Advertising
• [03] Bluetooth - Stack features
• [04] Bluetooth - Performance
• [05] Bluetooth - Bluetooth Mesh
• [06] Bootloading - General
• [07] Bootloading - UART DFU
• [08] Bootloading - OTA DFU
• [09] Application Examples
• [10] Peripheral Examples
• [11] Security
• [12] Tools
• [13] Hardware
• [14] Migration
• [15] Mobile
• [16] NCP

Note: Do you want to get automatic notifications when new content is added to the list? Just click the Follow button in upper right corner to subscribe to email notifications. We will make comments when new content is created to trigger those notifications.

[01] Bluetooth General

• KBA_BT_0101: Selecting Your Blue Gecko SoC/Module
• KBA_BT_0102: BLE Basics (master/slave, GATT client/server, data RX/TX)
• KBA_BT_0103: Understanding the Bluetooth Connection Process
• KBA_BT_0104: Acknowledged vs Unacknowledged GATT operations 
• KBA_BT_0105: Bluetooth 5 Features 
• KBA_BT_0106: Bluetooth SIG Resources 
• KBA_BT_0107: Bluetooth Stack Operations Flowcharts

[02] Bluetooth - Advertising

• KBA_BT_0201: Bluetooth advertising data basics 
• KBA_BT_0202: Bluetooth advertising using manufacturer specific data 
• KBA_BT_0203: Providing Extra Data by Scan Response 
• KBA_BT_0204: Using scan request reporting
• KBA_BT_0205: Advertisement Constructor 
• KBA_BT_0206: Extended Advertising Example 
• KBA_BT_0207: Periodic Advertising

[03] Bluetooth - Stack features

• KBA_BT_0301: LE Coded PHY on EFR32xG13
• KBA_BT_0302: Advertising and Scanning with LE Coded PHY 
• KBA_BT_0304: Different characteristic value types 
• KBA_BT_0305: Handling GPIO Interrupts using External Signals 
• KBA_BT_0306: Using the lazy soft timer
• KBA_BT_0307: Enabling TX/RX activity indicator pins in BLE SDK 2.4.0 and later 
• KBA_BT_0308: Polymorphic GATT 
• KBA_BT_0309: How to save float values (or any arbitrary data) in PS keys
• KBA_BT_0310: Changes to the le_gap class of API functions
• KBA_BT_0311: Whitelisting
• KBA_BT_0312: Service Change Indications 
• KBA_BT_0313: GATT Caching

[04] Bluetooth - Performance

• KBA_BT_0401: Optimizing Current Consumption in Bluetooth Low Energy Devices 
• KBA_BT_0402: EM3 and EM4S for non-connectable advertising 
• KBA_BT_0403: Using Energy Modes with Bluetooth Stack 
• KBA_BT_0404: Throughput with Bluetooth Low Energy technology
• KBA_BT_0405: Bluetooth Tx power settings
• KBA_BT_0406: Adaptive Frequency Hopping
• KBA_BT_0407: Bluetooth Radio Task Priorities
• KBA_BT_0408: Current consumption during advertising with different Tx power setting
• KBA_BT_0409: Using the PLFRCO as low-frequency clock source
• KBA_BT_0410: TX power limitations for regulatory compliance (ETSI, FCC)

[05] Bluetooth - Bluetooth Mesh

• KBA_BT_0501: BT Mesh embedded provisioner example 
• KBA_BT_0502: Bluetooth Mesh Vendor Specific Model Example 
• KBA_BT_0503: Advertising Sets Used by the Bluetooth Mesh Stack
• KBA_BT_0504: Adding custom advertising to the Bluetooth mesh examples
• KBA_BT_0505: Bluetooth Mesh Training resources
• KBA_BT_0506: Minimalistic OnOff client for testing Bluetooth Mesh on custom board
• KBA_BT_0507: Bluetooth Mesh Host Switch Example
• KBA_BT_0508: Scanning BLE beacons in Bluetooth Mesh mode 
• KBA_BT_0509: Bluetooth Mesh Host Provisioner
• KBA_BT_0510: Blacklisting Nodes From Bluetooth Mesh Network
• KBA_BT_0512: Bluetooth Mesh Proxy Client Example
• KBA_BT_0513: IV Update & Recovery Procedure and Sequence Number Storing Strategy

[06] Bootloading - General

• KBA_BT_0601: Why Doesn't My Sample Application Run?
• KBA_BT_0602: Bootloader changes in BLE SDK
• KBA_BT_0603: Adding Gecko Bootloader to Bluetooth projects
• KBA_BT_0604: Switching between firmware images using Internal Storage Bootloader
• KBA_BT_0605: Upgrading Gecko Bootloader
• KBA_BT_0606: Upgrading Gecko Bootloader with Slot address change
• KBA_BT_0607: Adding metadata to GBL files 
• KBA_BT_0608: Factory programmed firmware of Bluetooth devices

[07] Bootloading - UART DFU

• KBA_BT_0701: Upgrading from factory firmware (v2.0.0) and from Bluetooth SDK v2.1.x with UART DFU type legacy bootloader
• KBA_BT_0702: UART DFU - Upgrading BGM111 by EFM32PG example 

[08] Bootloading - OTA DFU

• KBA_BT_0801: Using Blue Gecko app OTA
• KBA_BT_0802: Uploading images to internal/external flash using OTA DFU 
• KBA_BT_0803: Bluetooth OTA updates using customized advertising data
• KBA_BT_0804: Secure OTA DFU
• KBA_BT_0805: Setting Bluetooth Address as device name in OTA 
• KBA_BT_0806: Using BLED112 to do Over-the-Air update of BGMxxx 
• KBA_BT_0807: Implementing OTA firmware update in the user application
• KBA_BT_0808: OTA options for NCP-based designs 

[09] Application Examples

• KBA_BT_0901: Bluetooth SoC-Empty example
• KBA_BT_0902: How to use Voice over Bluetooth Low Energy example for Thunderboard Sense
• KBA_BT_0903: SPP-over-BLE example 
• KBA_BT_0904: Creating an Eddystone-URL Beacon 
• KBA_BT_0905: SPP client example using BLED112 dongle 
• KBA_BT_0906: Multi-Slave Multi-Master Dual-Topology example 
• KBA_BT_0907: Parallel handling of multiple slaves with Bluetooth stack 
• KBA_BT_0908: Using RTCC as Timer or Calendar while running BLE stack 
• KBA_BT_0909: Scheduling application tasks while running BLE stack
• KBA_BT_0910: Using the UD flash in the Bluetooth C SDK 
• KBA_BT_0911: Midi over BLE 
• KBA_BT_0912: Control LEDs on a Wireless Starter Kit from a Mobile App 
• KBA_BT_0913: BLE Central and GATT client example - working with an Android app 
• KBA_BT_0914: ANCS 
• KBA_BT_0915: Throughput Tester Example 
• KBA_BT_0916: Working with Long Characteristic Values 
• KBA_BT_0917: Implementing wireless direct test mode (DTM) 
• KBA_BT_0919: Using EM3 or EM4 energy mode in a Bluetooth beacon app 
• KBA_BT_0920: Bluetooth Device Tracking with Tile 

[10] Peripheral Examples

• KBA_BT_1001: Using the LEUART 
• KBA_BT_1002: Using Low Energy Timers 
• KBA_BT_1003: Using accelerometer found in the WSTK expansion board 
• KBA_BT_1004: Hardware Timers with EFR32xG1x 
• KBA_BT_1005: Reporting Battery Voltage over BLE 
• KBA_BT_1006: Thermometer example with EFR32 internal temperature sensor 
• KBA_BT_1007: Enable LCD screen on WSTK 
• KBA_BT_1008: Watchdog on BGM111 (and other Blue Gecko modules / boards) 
• KBA_BT_1009: Waking from Deep Sleep Using RF Sense 
• KBA_BT_1010: Push buttons and interrupts in a Bluetooth project 
• KBA_BT_1011: How can I extend the Bluetooth examples with UART functionality? 
• KBA_BT_1012: Adding Watchdog in NCP Mode

Additional Resources

• MCU Peripheral Examples on GitHub (also includes EFR32)

[11] Security

• KBA_BT_1101: Using Bluetooth security features in Silicon Labs Bluetooth SDK
• KBA_BT_1102: Pairing Processes
• KBA_BT_1103: Application Layer Security 
• KBA_BT_1104: The New Bond Replacement Algorithm
• KBA_BT_1105: How to handle missing bonding keys 
• KBA_BT_1106: OOB introduction and example 
• KBA_BT_1107: Secure connection with serial communication between two BGM modules 
• KBA_BT_1108: Authenticating Bluetooth Devices with no User Interface 

[12] Tools

• KBA_BT_1201: Condensed Bluetooth SDK revision history (2.0.0 and later)
• KBA_BT_1202: Building C++ BLE projects
• KBA_BT_1203: Creating projects for EFR32BG on a custom board
• KBA_BT_1204: How to flash BGM11x or EFR32BG from command line?
• KBA_BT_1205: Programming an external BGM111 using the WSTK
• KBA_BT_1206: Log System
• KBA_BT_1207: Event and Error Checking 
• KBA_BT_1208: Using virtual COM port (VCOM)
• KBA_BT_1209: Debugging BGTool not being able to communicate with NCP target.
• KBA_BT_1210: Connect Custom board to Simplicity Studio using JTAG/SWD.

Additional Resources

• Simplicity Studio now Treats Bluetooth Modules as Parts

[13] Hardware

• KBA_BT_1301: How to find schematics and other documentation for radio boards?
• KBA_BT_1302: Supplying EFR32 PAVDD from 3.3V
• KBA_BT_1303: Enabling LNA on MGM12P for Bluetooth usage
• KBA_BT_1304: Antenna tuning for BGM12x (coin-cell usage example)
• KBA_BT_1305: Quartz Crystals, MEMS Oscillators, and Phase Noise for BLE Applications
• KBA_BT_1306: TX Power Levels 
• KBA_BT_1307: What is a STEP file and how to obtain a STEP file for Silicon Labs IOT products?
• KBA_BT_1308: Saving CTUNE value as manufacturing token
• KBA_BT_1309: Design and Assembly guidelines when using xGM parts based System in Package (SiP)

Additional Resources

• Debugging and Programming Interfaces for Custom Designs
• Production Programming Options for Silicon Labs Devices
• RF Range Calculator
• Driving FEMs (and PAs and LNAs) on EFR32

[14] Migration

• KBA_BT_1401: Updating NCP projects to SDK 2.4.x
• KBA_BT_1402: Bluetooth Smart SDK Migration Guide From V2.0.1 to V2.1.x
• KBA_BT_1403: Migrating Simplicity Studio projects from Bluetooth SDK 2.1.1 to 2.3.1
• KBA_BT_1404: Migrating Simplicity Studio projects from Bluetooth SDK 2.3.x to 2.4.x
• KBA_BT_1405: Migration guide to Bluetooth SDK 2.7.x

[15] Mobile

• KBA_BT_1501: BLE devices on iOS Bluetooth Settings page
• KBA_BT_1502: Evaluating SPP-over-BLE example using BLE1xx cable replacement app 
• KBA_BT_1503: iOS 9.1 with respect to Bluetooth LE
• KBA_BT_1504: Mobile Devices used for Interoperability Testing
• KBA_BT_1505: Selecting suitable connection parameters for iOS 
• KBA_BT_1506: How to find the Bluetooth 5 feature status of a listed device such as a smartphone

[16] NCP

• KBA_BT_1601: Custom communication over NCP 
• KBA_BT_1602: NCP Host Implementation and Example 
• KBA_BT_1603: Local Event Handling on Bluetooth NCP 

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

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