nRF5 SDK for Mesh v4.1.0
Examples

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, mesh models, and certain features that will help you get started on new mesh-based projects.

Table of contents

  • Read before testing
  • Available examples
  • Common example modules
  • Provisioning bearers in the nRF5 SDK for Mesh examples
  • Evaluating examples with the nRF Mesh mobile app

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


Read before testing @anchor read-before-testing

All examples are guaranteed to work with fully compatible device configurations. Some of the examples are not compatible with nRF52810.

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 @anchor available-examples

The following examples are provided with this SDK:


Common example modules @anchor common-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,
  • 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 @anchor example_provisioning_bearers

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 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 -
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 @anchor nrf-mesh-mobile-app

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

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

Check the section about evaluating the example using the nRF Mesh mobile application on the documentation pages of these examples for example-specific information, like the name of the nodes in the application.

Note
The following procedures related to the nRF Mesh mobile application are referring to:
  • The nRF Mesh application on Android. However, there are no major differences in the UI of the iOS version.
  • The documentation page of the corresponding example. The model instances you need to bind can be different for your example – check the documentation pages of recommended example. Moreover, for Low Power node example, setting publication requires a different procedure.

Provisioning with nRF Mesh @anchor nrf-mesh-mobile-app-provisioning

To provision Mesh examples with the nRF Mesh mobile app, 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 client firmware on individual boards and the server firmware on other board or boards.
  2. Open the nRF Mesh mobile app. The main application window appears.
  3. 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.
  4. 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.
  5. 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 @anchor nrf-mesh-mobile-app-binding

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

  1. 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.
  2. Repeat step 1 for each server board node.
  3. 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 @anchor nrf-mesh-mobile-app-publication

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

  1. On the client node, in the publication section of the client model instance menu, tap Set Publication.
  2. Tap the publication address field. A dropdown menu appears.
  3. 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.
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