nRF5 SDK for Mesh v5.0.0
Integrating Bluetooth mesh into nRF5 SDK examples

The nRF5 SDK for Mesh is compatible with Nordic's nRF5 SDK. This allows you to either include resources from nRF5 SDK in an existing Bluetooth mesh project or include nRF5 SDK for Mesh functionalities in an nRF5 SDK example.

See Building the stack and examples for information on how to download and install the nRF5 SDK. Check Coexistence examples to see how the nRF5 SDK features can be simultaneously used with nRF5 SDK for Mesh.

  • The integration with nRF5 SDK is tested only with the nRF5 SDK v17.0.2.
  • The nRF5 SDK v17.0.2 does not support devices of the nRF51 series.

Table of contents

Dynamic memory

While using nRF5 SDK features along with nRF5 Mesh SDK features (as shown in coexistent examples) you may encounter situation where the application considerations may require changes to how dynamic memory is allocated and the amount of dynamic memory available for allocation. The Bluetooth mesh stack uses the Mesh memory manager interface for dynamic memory allocation. The default backend, mesh_mem_stdlib.c, uses the standard library malloc(), which requires a sufficiently large heap size to be defined. This behavior can be changed by replacing the backend with another memory manager.

If you are using Segger Embedded Studio for building the application set the Heap Size to 8192 bytes in the Project Options> Code> Runtime Memory Area settings.

Concurrent SoftDevice and Bluetooth mesh activity

The largest performance issues when running the SoftDevice and the Bluetooth mesh concurrently usually comes from radio time contention. While the SoftDevice usually operates in short, scheduled bursts, the Bluetooth mesh attempts to use the radio for as much time as possible. As long as the SoftDevice has no radio activity, the Bluetooth mesh will be scanning and advertising continuously. The SoftDevice activity will reduce the amount of time the Bluetooth mesh gets on-air, and to maintain a consistently good Bluetooth mesh performance, the SoftDevice radio parameters must be set as conservatively as possible, without breaking the user experience.

When advertising with the SoftDevice, try using the highest advertising interval your usage scenario can tolerate. If possible, turn off the SoftDevice advertiser when it is not needed, and activate it only when you expect to receive a connection request. If you only need to send non-connectable, non-scannable advertisements (for example, for third party beacon protocols), use the Bluetooth mesh Advertiser API, as it is optimized for minimal context switching when used together with the Bluetooth mesh.

When the SoftDevice operates in a connection:

SoftDevice-based scanning has the biggest impact on the mesh network performance of all the SoftDevice activity. The Bluetooth mesh stack is not able to receive packets while the SoftDevice is scanning, so every SoftDevice scan window replaces Bluetooth mesh scanning. SoftDevice scanning should only be used when trying to establish connections or when active scanning is required. If general passive BLE scanning is required (for listening for beacons or other third party activity), hook into the Bluetooth mesh scanner by setting an RX callback with the nrf_mesh_rx_cb_set function. If your application requires active scanning or needs to initiate a connection, the scan parameters should be set as conservatively as possible. Long scan intervals with short scan windows will give the Bluetooth mesh as much time as possible for its own radio activity. Similarly, it might be beneficial to perform continuous scanning for a short period of time when establishing connections, instead of performing long running, duty cycled scanning, as the context switching would cause a lot of unnecessary overhead. Finally, setting a timeout for SoftDevice connection initiation calls to avoid idle scanning for long periods of time is highly recommended.

As the Bluetooth mesh does not actively block SoftDevice radio activity, reducing Bluetooth mesh activity on the device that runs SoftDevice activity concurrently does not directly affect the SoftDevice performance. However, other Bluetooth mesh devices nearby will interfere with SoftDevice activity in the advertisement channels, which could make connection initiation take longer.

Generally, the Bluetooth mesh has to perform all its radio operations between the SoftDevice activity, so if a device is sending a lot of Bluetooth mesh packets while performing SoftDevice radio operations, it will spend most of its mesh network time on this, instead of receiving incoming data. To combat this, reduce the Bluetooth mesh packet sending by scaling the number of outgoing packets according to the radio time available. If possible, suspend Bluetooth mesh packet relaying during time-consuming SoftDevice operations by calling the mesh_opt_core_adv_set on the CORE_TX_ROLE_RELAY role.

Including nRF5 SDK in an nRF5 SDK for Mesh example

Depending on your toolchain:

The Bluetooth mesh example projects already include an sdk_config.h file in their include/ directory. These files are copies of the default SDK configuration files, and all changes required by the Bluetooth mesh example are contained in the include/app_config.h file in the example's directory.

Some SDK features must be explicitly enabled in the SDK configuration file before they can be used. See the SDK documentation page SDK configuration header file for details.

Including nRF5 SDK for Mesh functionality in an nRF5 SDK example

  1. Include the following source files from nRF5 SDK for Mesh in the nRF5 SDK example's project file:
    • All C files in mesh/core/src
    • All C files in mesh/bearer/src
    • All C files in mesh/prov/src except nrf_mesh_prov_bearer_gatt.c
    • All C files in mesh/access/src
    • All C files in mesh/dfu/src
    • All C files in mesh/stack/src
    • models/foundation/config/src/config_server.c
    • models/foundation/config/src/composition_data.c
    • models/foundation/config/src/packed_index_list.c
    • models/foundation/health/src/health_server.c
    • Any other Bluetooth mesh models that are used in your application
    • external/micro-ecc/uECC.c
    • examples/common/src/assertion_handler_weak.c
    • examples/common/src/mesh_provisionee.c
      If various Bluetooth mesh features are not needed (for example, DFU), the corresponding files may simply be omitted from the project file. However, add examples/common/src/nrf_mesh_weak.c in their place to provide stubs for the missing API functions.
  2. Add the following folders to the project include path of the nRF5 SDK example:
    • mesh/core/api
    • mesh/core/include
    • mesh/bearer/api
    • mesh/bearer/include
    • mesh/prov/api
    • mesh/prov/include
    • mesh/access/api
    • mesh/access/include
    • mesh/dfu/api
    • mesh/dfu/include
    • mesh/stack/api
    • models/foundation/config/include
    • models/foundation/health/include
    • Path to include folder of any other Bluetooth mesh models that are used in your application
    • external/micro-ecc
    • examples/common/include
    • Path to any other resources in the Bluetooth mesh examples that are used in your application
  3. Add the following preprocessor symbols to the project file of the nRF5 SDK example:
    • NRF52_SERIES
    • NRF_MESH_LOG_ENABLE=NRF_LOG_USES_RTT (because logging in the Bluetooth mesh stack relies on RTT)

Optional changes

Additionally, you might need to apply one or more of the following changes:

Flash placement project files

The Segger Embedded Studio projects all have a flash_placement.xml file next to them, which acts as input to the linker. In the flash_placement.xml file, the nRF5 SDK configures a set of ProgramSection listings, which are used to place certain variables. In addition to all the ProgramSections required by the nRF5 SDK components, the Bluetooth mesh requires two additional sections, nrf_mesh_flash and nrf_mesh_ram.

The additional Bluetooth-mesh-related sections must be added to the flash_placement.xml file:

  1. Add the following line to the memory segment marked <MemorySegment name="FLASH" ...>:
    <ProgramSection alignment="4" keep="Yes" load="Yes" name=".nrf_mesh_flash" inputsections="*(SORT(.nrf_mesh_flash.*))" address_symbol="__start_nrf_mesh_flash" end_symbol="__stop_nrf_mesh_flash"/>
  2. Add the following line to the memory segment marked <MemorySegment name="RAM" ...>:
    <ProgramSection alignment="4" keep="Yes" load="No" name=".nrf_mesh_ram" inputsections="*(SORT(.nrf_mesh_ram.*))" address_symbol="__start_nrf_mesh_ram" end_symbol="__stop_nrf_mesh_ram"/>
This change has already been made for the Coexistence examples. You can use the flash_placement.xml files in these examples as a reference when editing flash placement files of any of the existing nRF5 SDK examples.

nRF5 SDK NVM storage modules

Using nRF5 SDK modules such as fstorage, pstorage, or ble_flash for writing to flash may be problematic due to long timeslot events occupied by the Bluetooth mesh stack. Use the Flash manager module provided by the Bluetooth mesh stack instead.

Furthermore, when writing to flash, ensure not to write or erase areas utilized by the Bluetooth mesh stack modules and the bootloader (if present). The flash area used by the Bluetooth mesh stack is returned by mesh_stack_persistence_flash_usage. This will work even when the stack is built with the legacy persistence mode enabled. Note, however, that if any of the flash areas have been specified manually by ACCESS_FLASH_AREA_LOCATION, NET_FLASH_AREA_LOCATION, or DSM_FLASH_AREA_LOCATION, these pages will not be included in the flash usage count.

Documentation feedback | Developer Zone | Subscribe | Updated