Bluetooth mesh devices are broadly categorized into two roles: a provisioner role and a node role. The nRF5 SDK for Mesh provides several example projects to demonstrate these roles, Bluetooth mesh models, and certain features that will help you get started on new mesh-based projects.

Table of contents

Check the official Bluetooth mesh glossary for definitions of the most important mesh-related terms used in this documentation.

Read before testing

All examples are guaranteed to work with fully compatible device configurations. Some of the examples are not compatible with nRF52810 and nRF52820 or not compatible with the nRF52840 dongle, or both.

Before you start using the examples, see the following pages:

You can also quickly run an example without going through the complete toolchain installation. See Running a first example for details.

Available examples

The following examples are provided with this SDK:

Light switch example is a Bluetooth mesh ecosystem example that contains some smaller examples: client, server, and proxy-server.
EnOcean switch translator client example demonstrates how to implement a third party device in Bluetooth mesh ecosystem, namely an EnOcean-to-Mesh translator. The EnOcean switches send the button status using BLE advertising packets. These packets can be captured and can be used to generate equivalent Bluetooth mesh messages for controlling other Bluetooth mesh nodes.
Beaconing example implements custom beacon advertising and shows how to send and receive custom packets using the nRF5 SDK for Mesh.
Coexistence examples demonstrate how the nRF5 SDK features can be simultaneously used with nRF5 SDK for Mesh.
DFU example shows how to use the proprietary mesh DFU framework to update the firmware of a device over Bluetooth mesh.
Dimming examples demonstrate how to use Generic Level model APIs in an application to implement dimming light and corresponding dimmer switch.
Light lightness example demonstrates how to use the Light Lightness model.
Light LC server model example demonstrates how to use the Light LC Setup Server model.
Light CTL example demonstrates how to use the Light CTL models.
Low Power node example demonstrates the Low Power node feature.
Provisioner example demonstrates the provisioning process and can be extended by other functionalities.
Remote provisioning example demonstrates the use of remote provisioning to provision devices outside of the provisioner's radio range.
Scene example demonstrates how to use the Scene models.
Sensor example demonstrates how to use the Sensor model.
Serial example demonstrates how to use the serial interface to create a Bluetooth mesh connectivity device.

Common example modules

The examples implement common functionalities through several common modules, including among others:

simple hardware abstraction layer,
RTT input functionality that uses the nRF5 SDK App timer and enables the examples to poll RTT for input characters,
Bluetooth mesh stack and SoftDevice initialization helper modules,
behaviors for several generic models.

For full overview of all common modules and detailed information, check the Application support modules API section.

Provisioning bearers in the nRF5 SDK for Mesh examples

The nRF5 SDK for Mesh examples can be provisioned using both of the provided provisioning bearers, without the OOB authentication method or with the static OOB authentication method. See the following table for an overview of which example works with PB-ADV or PB-GATT, or both.

Example / Bearer	PB-ADV	PB-GATT
Beaconing example	X	-
DFU example	X	-
Dimming examples	X	X
EnOcean switch translator client example	X	X
Light switch example	X	X
Light lightness example	X	X
Light LC server model example	X	X
Light CTL example	X	X
Low Power node example	-	X
Provisioner example	n/a	n/a
Coexistence examples	X	-
Remote provisioning example*	X	-
Scene example	X	X
Sensor example	X	X
Serial example*	X	-

All these examples use the 16-byte static OOB value. The static OOB value is stored in STATIC_AUTH_DATA, which is defined in example_common.h.

Note

The following examples marked with (*) in the table are exceptions:

Remote provisioning example – uses PB-ADV with the static OOB authentication method. However, it uses a different 16-byte static OOB value than other examples. The reason is to prevent provisioning all devices around using the PB remote client.
Serial example – uses PB-ADV. However, it can be provisioned through the static provisioner if the same 16-byte static OOB value is used to initialize the provisioner role.

For more information about provisioning, see the following pages:

Evaluating examples using the nRF Mesh mobile application

You can use nRF Mesh mobile app (available for iOS and Android) with almost all of the Bluetooth mesh examples for provisioning and configuring the boards. The only example that does not support the mobile application is the Bluetooth mesh provisioner.

This said, the nRF Mesh mobile application is recommended for use with the following examples:

The model instances you need to bind can be different for your example – check the documentation pages of recommended examples. For Low Power node example, setting publication requires a different procedure. For Sensor example, configure publication also for the server node.

To start evaluating examples using the nRF Mesh mobile application, complete the following three configuration stages:

These stages are discussed in the following sections for the nRF Mesh application on Android. There are no major differences in the iOS version functionalities.

Provisioning with nRF Mesh

To provision Bluetooth mesh examples with the nRF Mesh mobile app, complete the following steps:

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 client firmware on individual boards and the server firmware on other board or boards.
Open the nRF Mesh mobile app. The main application window appears.
Add a new node. The application starts looking for unprovisioned nodes and lists them on the screen.
- See the example pages for information about the node naming conventions:
Provision each node by completing the following steps for each of them:
1. Tap the node name to connect to it.
2. Identify the node.
3. Provision the node and select the desired OOB option. The application starts the provisioning process. When it is complete, you receive a notification.
When all nodes are provisioned, note the addresses of the server nodes. You need them when setting the publication address.

Note: If the automatic configuration is broken, manually get the composition data, add application keys, and only then go to the following procedure.

Binding nodes with nRF Mesh

To bind Bluetooth mesh nodes with the nRF Mesh mobile app, complete the following steps:

On the server nodes, bind the server model instance specified in the corresponding example with the same application key:
1. Tap the server node name. The node configuration menu opens.
2. In the expanded Elements section, tap the model instance name.
3. In the section with bound application keys, tap the button for binding the application key and then tap the application key field. The key is now bound.
Repeat step 1 for each server board node.
On the client node, bind the client model instance specified in the corresponding example with the same application key:
1. On the list of provisioned nodes, tap the client node name. The configuration menu opens.
2. In the expanded Elements section, tap the first client model instance name.
3. In the section with bound application keys, tap the button for binding the application key and then tap the application key field. The key is now bound. The application goes back to the model instance menu.

Setting publication and subscription with nRF Mesh

To set publication rules between nodes with the nRF Mesh mobile application, complete the following steps:

On the client node, in the publication section of the client model instance menu, tap Set Publication.
Tap the publication address field. A dropdown menu appears.
Choose one of the following address types to set the publication addresses of the client model:
- Unicast Address – You need to complete the following steps:
  1. Provide the address of any server node noted at the end of the provisioning procedure.
  2. Apply the changes.
- Groups – You need to complete the following steps:
  1. Select an existing group to subscribe or create a new one.
  2. Apply the changes for the client node.
  3. On the server nodes, set the Subscription Address of the server model instance menu to the selected group address.
  4. Apply the changes for the server nodes.
If you are evaluating the sensor example, configure also publication for the server node, as described on the sensor example page. The configuration procedure for the server node is the same as described in steps 1-3 for the client node (switch the server and client roles).

Note: If applicable for the chosen example, you can also configure the publish address of the second client model instance. To do this, bind the model instance with the same application key and set the model instance's publish address to the Unicast Address of any server node.

Any unhandled error is indicated by all LEDs on the board turning on in steady state. You will need to restart the application by resetting the board. To do this, switch the board on and off or use the following command:

nrfjprog -f nrf52 --reset

Once you finish setting publication and subscription with nRF Mesh, you can start interacting with the boards, as described in the relevant section on each example page.