Provisioner example

The provisoner example is the default Bluetooth mesh network configurator. It works in a fixed, predefined way and can be used as the static provisioner with the following examples:

• Dimming examples
• EnOcean switch translator client example
• Light switch example
• Light lightness example
• Light LC server example
• Light CTL example
• Scene example
• Sensor example

Table of contents

• Network configuration and address assignment
  • Node address assignments
  • Publish subscribe configuration
  • Provisioner state machine
• Usage of Bluetooth mesh APIs
• Hardware requirements
• Setup
  • LED and button assignments
• Testing the example
  • Specifying the maximum number of provisionee devices
  • Provisioning examples without Scene Setup Server model
  • Evaluating examples using the static provisioner

Because of the asynchronous nature of the provisioning and configuration process, the provisioner is implemented as a multi-layered state machine. The application provisions and configures devices when it receives unprovisioned beacons from them.

Every supported example has a unique Uniform Resource Identifier (URI) included in the beacons. The provisioner example uses URI hash to understand the type of example being provisioned and to select the suitable configuration to be applied to the node after provisioning. For this reason, this provisioner can provision devices only with the known URI. The list of URIs is predefined.

The static provisioner has its own limitations and is provided as a tool to evaluate SDK examples without the need to use a mobile application provisioner. If you are using a mobile application for provisioning, you can see the models present on the device and configure the nodes accordingly. Moreover, you can also use more sophisticated automated provisioners that can use the UUID, URI, and the device composition data to understand which devices are being provisioned and configure them automatically.

Network configuration and address assignment

The following diagram shows how the provisioner configures Bluetooth mesh examples.

Typical configuration of Bluetooth mesh examples by the provisioner

Node address assignments

During the provisioning procedure, the client boards are provisioned at random and their elements are assigned addresses starting in the following manner:

On each client example, the two instances of the client models are instantiated on separate secondary elements to communicate with the Odd and Even server groups. Each subsequent secondary element gets a consecutive address starting from the address of the primary element. The provisioner configures the client model instantiated on an element with the Odd address to communicate with the Odd group, and the client model instantiated on an element with the Even address to communicate with the Even group.

If you have multiple client boards in the network, their primary elements will receive a consecutive even address after the address of the last element on a previously provisioned client node.

The following table shows the list of client examples.

The provisioner also provisions and configures the servers at random. It assigns them addresses and adds them to Odd and Even groups.

The starting addresses are different for each server example. Subsequently provisioned server boards get the next consecutive Odd and Even addresses.

Publish subscribe configuration

After getting provisioned, the device is configured depending on whether it is running a client example or a server example:

• For client, two instances of the models are instantiated on different elements. The first model instance is configured to publish to the odd group address (0xc003), and the second one is configured to publish to the even group address (0xc002). Similarly, these model instances are subscribed to the addresses of 0xc005 and 0xc004 respectively.
• For server, the subscription and publication addresses are set depending on whether the unicast address of the node is even or odd. Models on the nodes with even address publish to 0xc004 and are subscribed to the address 0xc002. Models on the nodes with odd address publish to 0xc005 and are subscribed to the address 0xc003. (Light LC server is additionally subscribed to receive sensor server statuses on 0xc004 and 0xc005, respectively).

Provisioner state machine

The following diagram shows the typical state transitions of the provisioner while provisioning and configuring a light switch client.

Light switch client state diagram

For more information on how a provisioning process works, see the provisioning guide.

Usage of Mesh APIs

The provisioner uses the following set of APIs:

• Application support API modules
• Management API module
• Core mesh stack API
• Provisioning API
• Configuration client API

The provisioner role is much more complex than the provisionee role, both in terms of resource requirements and application complexity. For these reasons, there is no simple API for the provisioning and configuration process.

However, for a specific use case, the API usage can be reduced into a set of simple steps, as implemented in the provisioner example:

1. Initialize:
   1. Core Bluetooth mesh stack.
   2. Device state manager.
   3. Access layer.
   4. Load provisioner persistent data.
2. Listen for unprovisioned beacons.
3. Provision the device.
4. Configure the device.
5. If more devices should join the network, go back to step 2.

Note

If the provisioner is not able to configure a device, you will receive a notification and can press a button to provision the next device or to try configuration one more time.

In the example code, this behavior is split between the following modules:

• examples/provisioner/src/main.c – deals with the initialization and setup of the Bluetooth mesh stack.
• examples/provisioner/src/provisioner_helper.c – deals with the provisioning process.
• examples/provisioner/src/node_setup.c – deals with the configuration process of the node once the provisioning is completed.

The following figure shows the details of how provisioning and configuration are implemented with the provided APIs. Note that the figure may simplify some API calls to provide a clearer picture. See the relevant source files for details.

Provisioning and configuring devices

Hardware requirements

You need one of the compatible development kits for the provisioner, in addition to the development kits required by the example you are using the provisioner with.

See Compatibility for information about the compatible development kits.

Setup

You can find the source code of the Bluetooth mesh provisioner in the following folder: <InstallFolder>/examples/provisioner

LED and button assignments

The buttons (1 to 4) are used to initiate certain actions, and the LEDs (1 to 4) are used to reflect the status of actions as follows:

• Button 1: Start provisioning.
• Button 4: Clear all the states and reset the node.
• LED 1: Reflects the state of the provisioning.
  • LED ON: Provisioning of the node is in progress.
  • LED OFF: No ongoing provisioning process.
• LED 2: Reflects the state of the configuration.
  • LED ON: Configuration of the node is in progress.
  • LED OFF: No ongoing configuration process.

Testing the example

There is no standalone testing procedure for the provisioner example. You need to use this example together with one of the examples that requires the static provisioner example. These examples are listed at the beginning of this page. Make sure to check their documentation pages, especially the section about testing the example.

Specifying the maximum number of provisionee devices

If you have more than 40 servers and clients in the example you want to use the provisioner with, make sure to set MAX_PROVISIONEE_NUMBER. This define specifies the maximum number of provisionee devices that the provisioner is able to introduce in the network.

Defining this value is important for setting key device array and TTL value, so that the network can work properly. This is because the provisioner keeps the device key for every provisioned device. Updating this define is also useful for calculating the replay cache size, which must be equal or higher to MAX_PROVISIONEE_NUMBER. Otherwise, the transport layer will reject all incoming traffic from new devices, because it cannot guarantee protection from a replay attack.

Complete the following steps:

1. In example_network_config.h, set MAX_PROVISIONEE_NUMBER to the total number of servers and clients available, if it is higher than 40.
2. If the value of MAX_PROVISIONEE_NUMBER increases, also scale up the replay protection list size (REPLAY_CACHE_ENTRIES).
3. Rebuild the provisioner example.
4. Set MAX_AVAILABLE_SERVER_NODE_NUMBER in nrf_mesh_config_app.h of the client example to the value set for MAX_PROVISIONEE_NUMBER.

Provisioning examples without Scene Setup Server model

Scene Setup Server model does not have a corresponding server example of its own and is instead showcased by several examples:

• Dimming examples
• Light switch example
• Light lightness example
• Light LC server example
• Light CTL example

You can exclude this model for these examples. If you decide to do so, you will also need to exclude the Scene Setup Server model from the static provisioner to be able to provision the server example. Complete the following steps:

1. Open the file examples/provisioner/include/nrf_mesh_config_app.h.
2. Locate the SCENE_SETUP_SERVER_INSTANCES_MAX define. By default, its value is set to 1.
3. Set the value to 0 and recompile.

Evaluating examples using the static provisioner

After building the examples (the provisioner example and the examples you want to evaluate) by following the instructions in Building the Bluetooth mesh stack, complete the following steps:

1. Flash the examples by following the instructions in Running examples, including:
   1. Erase the flash of your development boards and program the SoftDevice.
   2. Flash the provisioner firmware on one board and the client or the server example firmware (or both) on other boards.
2. After all boards are flashed, press Button 1 on the provisioner board to start the provisioning process. See the Network configuration and address assignment section for details.
   • The sequence of provisioned devices depends on the sequence of received unprovisioned beacons.
   • You can use RTT viewer to view the RTT output generated by the provisioner. The provisioner prints details about the provisioning and the configuration process in the RTT log.
3. Observe that the LED 1 on the provisioner board is turned ON when the provisioner is scanning and provisioning a device.
4. Observe that the LED 2 on the provisioner board is turned on when the configuration procedure is in progress.
5. Wait until LED 1 on the provisioner board remains lit steadily for a few seconds, which indicates that all available boards have been provisioned and configured.

If the provisioner encounters an error during the provisioning or configuration process for a certain node, you can reset the provisioner to restart this process for that node.