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.
Table of contents
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.
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.
Depending on your toolchain:
CMakeLists.txt
in the Light Switch server example).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.
mesh/core/src
mesh/bearer/src
mesh/prov/src
except nrf_mesh_prov_bearer_gatt.cmesh/access/src
mesh/dfu/src
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
external/micro-ecc/uECC.c
examples/common/src/assertion_handler_weak.c
examples/common/src/mesh_provisionee.c
examples/common/src/nrf_mesh_weak.c
in their place to provide stubs for the missing API functions.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
external/micro-ecc
examples/common/include
NRF52_SERIES
NRF_MESH_LOG_ENABLE=NRF_LOG_USES_RTT
(because logging in the Bluetooth mesh stack relies on RTT)CONFIG_APP_IN_CORE
Additionally, you might need to apply one or more of the following changes:
simple_hal
module in the Bluetooth mesh stack may need to be updated to use the Nordic nRF5 SDK bsp
module if integrated with the nRF5 SDK. It is possible to use both, but in this case GPIOTE_IRQHandler
must be removed from one of them, and only one of the modules may register callback functions.fstorage
in the Nordic nRF5 SDK, add the following code block to nrf_mesh_config_app.h
: nrf_mesh_config_app.h
. Copy it from the examples/templates
folder in Bluetooth mesh stack repository into your project folder, and remove #error
message at the top of the file. Make other appropriate changes to the file content, like adjusting ACCESS_ELEMENT_COUNT
and ACCESS_MODEL_COUNT
to the required number of elements and models.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 ProgramSection
s 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:
<MemorySegment name="FLASH" ...>
: <MemorySegment name="RAM" ...>
: 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.