This migration guide is complementary to the Release Notes. It describes practical actions you must take to update your code to a newer version of the nRF5 SDK for Mesh.

Table of contents

Added and removed files

The following files have been added in the v3.0.0 release:

LPN feature:
- mesh/core/src/core_tx_lpn.c
- mesh/core/src/lpn.c
- mesh/core/src/mesh_lpn_subman.c
Core:
- mesh/core/src/mesh_mem_stdlib.c
- mesh/core/src/timeslot_timer.c
- external/app_timer/app_timer_mesh.c (details below)
Common example files:
- examples/common/src/app_level.c
- examples/common/src/ble_softdevice_support.c (details below)

The following files have been removed in the v3.0.0 release:

examples/common/src/mesh_softdevice_init.c (details below)

Required actions

Update your projects accordingly to include or remove these files.

IRQ priority level change

The integration with the nRF5 SDK v15.2 caused the following changes:

The function softdevice_irq_priority_checker() has been removed from mesh_app_utils.h.
NRF_MESH_IRQ_PRIORITY_LOWEST has been changed from 7 to 6, which corresponds to APP_IRQ_PRIORITY_LOW.
The nrf_sdh.c replacement has been removed.

Required actions

Go back to using nrf_sdh.c in the nRF5 SDK, as the IRQ level fix was upstreamed.
Make sure that mesh API is called at the same IRQ priority level as it is specified in the configuration.

Stack separation on high frequency and low frequency time domains

Stack has been divided into two time frequency domains:

High-frequency domain, which is based on the timeslot structure of Soft Device. Low layers of the stack (advertiser, scanner, bearer etc) are based in this domain to be able to fit their activities within the provided timeslot.
Low frequency domain, which is based on app_timer functionality. app_timer is based on RTC with low frequency source clock (which works independently from MCU clock). All components above bearer are based in this domain. The reason for this change is that low-power nodes need to put the MCU to sleep for long periods of time between actions. The slower clock can then wake up the MCU right before it is needed.

Additionally, app_timer API can be used in an application as-is. However, the SDK app_timer abilities are not sufficient for managing the stack functionality. Extended app_timer with modifications has been added in external/app_timer. Modified version will be compiled and linked to applications (based on stack build system) instead of SDK app_timer. SDK app_timer API header file should be used as well.

Required actions

The following define that turns on app_timer in the building process must be added to app_config.h to make these changes work:

    #define APP_TIMER_ENABLED 1

Initialization and start phase changes

In the initialization phase of the examples, the mesh_softdevice_init module has been replaced with the BLE SoftDevice support module.

In the start phase of the examples, the execution_start() function has been removed.

Required actions

Use the function ble_stack_init() to initialize the SoftDevice Handler and the BLE stack, and to register the Mesh handler for SoC events.

Make sure the function mesh_stack_start() is called at the end of the start phase (see start() function in the Light Switch Server code as an example). After calling mesh_stack_start(), all mesh API interaction must happen at the IRQ priority level specified in the call to mesh_stack_init(). Calling mesh functions at wrong IRQ priority levels after enabling the stack can cause unpredictable behavior (see Interrupt priority levels for details).

Only one segmented message from an element to a destination address at a time

The nRF Mesh SDK is now enforcing the Mesh Profile Specification v1.0 rule that disallows multiple simulatneous segmented messages from a source address to the same destination.

This change means that models must wait until their previous segmented message is finished sending before they can send another. If multiple models on the same element have the same publish address, they have to coordinate their publishing as well.

If the application attempts to publish two simultaneous segmented messages with the same source and destination, the second publish call gets rejected with error code NRF_ERROR_INVALID_STATE.

Required actions

Models that previously scheduled multiple segmented messages in the same context must instead subscribe to NRF_MESH_EVT_TX_COMPLETE events or set up timers for sending to avoid the error code.

Note: This change only affects segmented messages, that is messages with access_message_tx_t::force_segmented set to true or messages that are longer than NRF_MESH_UNSEG_PAYLOAD_SIZE_MAX. Unsegmented messages can be interleaved with both segmented and unsegmented messages of any source and destination.

Device compile time configuration changes

Compile time configuration for supported features of the device changed, which makes DEVICE_FEATURES, MESH_FEATURE_GATT, GATT_PROXY macros outdated.

Required actions

Make sure you apply the following changes to your code:

Use MESH_FEATURE_PB_GATT_ENABLED macro instead of MESH_FEATURE_GATT.
Use MESH_FEATURE_GATT_PROXY_ENABLED macro instead of GATT_PROXY.
Use MESH_FEATURE_RELAY_ENABLED, MESH_FEATURE_LPN_ENABLED and MESH_FEATURE_GATT_PROXY_ENABLED macros to enable or disable required feature instead of DEVICE_FEATURES.

New provisioning parameter

There is a new parameter attention_duration_s for the nrf_mesh_prov_provision() function in mesh/prov/api/nrf_mesh_prov.h. This parameter is required in the provisioning process.

Required actions

Update all uses of the nrf_mesh_prov_provision() function with the additional attention_duration_s argument.