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
Read this migration guide together with the nRF5 SDK for Mesh v5.0.0 release notes.
app_timer_id_t with a timer for each supported property in the application for handling the min interval timing. This is required in addition to the similar array needed for handling cadence timing in the Sensor Server API in v4.2.0. The new parameter for the macro is _min_interval_timer_ids.app_timer_id_ts to APP_SENSOR_SERVER_DEF (parameter _min_interval_timer_ids).ID_START and ID_END in model_common.h have been revised to grant more space for model instances. This was done because Light LC models and Light CTL models required a lot more space for stored values when the Scene models were added.ID_START and ID_END to values from the nRF5 SDK for Mesh v4.2.0.MemorySegment section in the SES project files for the Coexistence examples has been renamed from RAM to RAM1. This is done due to migration to the nRF5 SDK v17.0.2. See the nRF5 SDK v17.0.2 release notes for details. The SES project files for the coexistence examples have been updated.MemorySegment accordingly.model_common_init has been replaced by model_config_file_init.model_common_config_apply has been replaced by model_config_file_config_apply.${MODEL_CONFIG_FILE_SOURCE_FILES} to add_executable(${target} in the application CMakeLists.txt file.generic_ponoff_setup_server_status_publish was removed because the publication support was removed, as per Bluetooth Mesh Model Specification (MshMDLv1.0.1).Read this migration guide together with the nRF5 SDK for Mesh v4.2.0 release notes.
mesh_config_clear() was changed in nRF5 SDK for Mesh v4.2.0. It now cleans up all the files instead of cleaning individual entries. Due to this change, if the new v4.2.0 applications are making use of this function, they have new mesh configuration files present (such as MESH_OPT_MODEL_FILE_ID), and the device configuration change is detected post-DFU, the use of this function during boot-up will cause an assertion.NRF_ERROR_INVALID_DATA is detected during mesh_init(), call mesh_config_clear() once after the NRF_MESH_EVT_CONFIG_STABLE event is received.mesh_dfu branch in the pc-nrfutil GitHub repository has been updated.Read this migration guide together with the nRF5 SDK for Mesh v4.1.0 release notes.
nrf_mesh_configure_device_uuid_reset() API, so that the raw output is aligned with the format from the UUID version 4. This update changes the auto-generated UUID value for the device.Read this migration guide together with the nRF5 SDK for Mesh v4.0.0 release notes.
ACCESS_FLASH_PAGE_COUNT, DSM_FLASH_PAGE_COUNT or NET_FLASH_PAGE_COUNT in new projects, as Mesh configuration now takes care of computing the required page counts.CONFIG_SERVER_EVT_NODE_RESET event in the user application and erase the desired application specific data before calling node_reset() API.ACCESS_FLASH_PAGE_COUNT, DSM_FLASH_PAGE_COUNT and NET_FLASH_PAGE_COUNT, as well as definitions of ACCESS_FLASH_AREA_LOCATION, DSM_FLASH_AREA_LOCATION and NET_FLASH_AREA_LOCATION. This will cause the Mesh configuration backend to locate the pages according to the flash layout of the old persistence system.CONFIG_SERVER_EVT_NODE_RESET event in the user application and erase the data specific to the application before calling mesh_stack_device_reset() API.nrf_mesh_config_bearer.h header file.nrf_mesh_config_app.h to make the mesh stack use the SWI0 IRQ for post processing.Read this migration guide together with the nRF5 SDK for Mesh v3.2.0 release notes.
nrf_mesh_config_app.h.nrf_mesh_config_app.h.access_flash_config_load() API is called successfully, the configuration of the access layer will now be considered as frozen. Once frozen, it is not allowed to add new models or change the configurations of the model subscription list (allocation, de-allocation, or sharing).access_flash_config_store() will now not store any access layer model configuration in non-volatile memory until the configuration of the access layer becomes frozen.models_init_cb() callback in the application. The mesh stack calls the callback before access_flash_config_load().SDK_ROOT path in SEGGER Embedded Studio.SDK_ROOT path to the nRF5 SDK v15.3.0 location in SEGGER Embedded Studio. To set SDK_ROOT path, see the First time setup page.nrf_mesh_is_address_rx function.nrf_mesh_is_address_rx function instead of dsm_address_is_rx if you need to check whether the device will process packets received on the given destination address.Read this migration guide together with the nRF5 SDK for Mesh v3.1.0 release notes.
Table of contents
mesh_app_uuid_gen() API to prevent use of non RFC4122 compliant UUIDs.nrf_mesh_configure_device_uuid_reset() API to make generated UUID compliant with UUID version 4 as per RFC4122.The MESH_PROVISIONEE_BEARER_ADV_ENABLED define has been replaced by MESH_FEATURE_PB_ADV_ENABLED. Setting MESH_FEATURE_PB_ADV_ENABLED=1 (which replaces MESH_PROVISIONEE_BEARER_ADV_ENABLED=1) will no longer cause compilation error.
Make sure that your code reflects this change to avoid errors.
The interface for providing provisioning authentication data nrf_mesh_prov_auth_data_provide() will now do stricter error checking on OOB input data. This ensures that the inputs are better tested and sanitized.
Make sure that your usage of the API is still valid.
The API of Generic Power OnOff client initialization has been simplified. The generic_ponoff_client_init function doesn't call generic_onoff_client_init anymore.
Manually extend the Generic Power OnOff Client with the Generic OnOff model. To do this, call the generic_onoff_client_init function and share subscription list between Generic OnOff and Generic Power OnOff clients by calling the access_model_subscription_lists_share function.
Read this migration guide together with the nRF5 SDK for Mesh v3.0.0 release notes.
Table of contents
The following files have been added in the v3.0.0 release:
mesh/core/src/core_tx_lpn.cmesh/core/src/lpn.cmesh/core/src/mesh_lpn_subman.cmesh/core/src/mesh_mem_stdlib.cmesh/core/src/timeslot_timer.cexternal/app_timer/app_timer_mesh.c (details below)examples/common/src/app_level.cexamples/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)Update your projects accordingly to include or remove these files.
The integration with the nRF5 SDK v15.2 caused the following changes:
softdevice_irq_priority_checker() has been removed from mesh_app_utils.h.nrf_sdh.c replacement has been removed.nrf_sdh.c in the nRF5 SDK, as the IRQ level fix was upstreamed.Stack has been divided into two time frequency domains:
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.
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
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.
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 Setting interrupt priority levels for details).
The nRF Mesh SDK is now enforcing the Bluetooth Mesh Profile Specification (MshPRFv1.0.1) 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.
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.
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.Compile time configuration for supported features of the device changed, which makes DEVICE_FEATURES, MESH_FEATURE_GATT, GATT_PROXY macros outdated.
Make sure you apply the following changes to your code:
MESH_FEATURE_GATT.GATT_PROXY.DEVICE_FEATURES.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.
Update all uses of the nrf_mesh_prov_provision() function with the additional attention_duration_s argument.
The following source files have been added in this release:
The following source files have been removed in this release:
models/config to models/foundation/configmodels/health to models/foundation/healthmodels/model_spec/commonmodels/model_spec/generic_dttmodels/model_spec/generic_levelmodels/model_spec/generic_onoffmodels/simple_on_off to models/vendor/simple_on_offmodels/pb_remote to models/experimental/pb_remotelight_switch examples and enocean example have been updated to use Generic OnOff models.SIMPLE_ON_OFF_CLIENT_ACKED_TRANSACTION_TIMEOUT macro definition added.PB_REMOTE_CLIENT_ACKED_TRANSACTION_TIMEOUT macro definition added.PB_REMOTE_SERVER_ACKED_TRANSACTION_TIMEOUT macro definition added.HEALTH_CLIENT_ACKED_TRANSACTION_TIMEOUT macro definition added.CONFIG_CLIENT_ACKED_TRANSACTION_TIMEOUT macro definition added.As of v2.2.0, the nRF5 SDK for Mesh makes use of the nRF5 SDK's section variable module Section variables.
The required changes for supporting section variables are already in place in the example applications, but any user applications carried over from the previous release might require modifications to work correctly, depending on the toolchain used:
The Segger Embedded Studio projects base their section placement on the bundled flash_placement.xml file. The example projects in version 2.2.0 contain updated flash_placement files. If you did not do any modifications to this file in your migrated project, you can safely replace the existing flash_placement file with the one in CMake/SES/flash_placement.xml.
If you modified the file, perform the migration manually by adding the following ProgramSection to the FLASH MemorySegment:
and the following ProgramSection to the RAM MemorySegment:
Restart Segger Embedded Studio after saving your changes and clean the solution before rebuilding (Build->Clean Solution).
When building with GCC, the section variables must be registered in the application's linker script so that they end up in the right memory area.
All section variables used by mesh go into two new memory sections (one in RAM and one in flash). These memory sections must be added to the linker script.
The nrf_mesh_ram-section must be added to the sections marked with INSERT AFTER .data:
The nrf_mesh_flash-section must be added to the sections marked with INSERT AFTER .text:
When building with ARMCC, no further action is required.
The mesh runtime options API (Mesh options) has been deprecated in favor of Mesh options API. The new API uses the new mesh_config module to store options persistently, so once set, the options do not have to be reset for the lifetime of the device.
The following options have been migrated to the new API:
| Old option | New option |
|---|---|
NRF_MESH_OPT_PROV_ECDH_OFFLOADING | mesh_opt_prov_ecdh_offloading_set |
NRF_MESH_OPT_NET_RELAY_ENABLE | mesh_opt_core_adv_set |
NRF_MESH_OPT_NET_RELAY_RETRANSMIT_COUNT | mesh_opt_core_adv_set |
NRF_MESH_OPT_NET_RELAY_RETRANSMIT_INTERVAL_MS | mesh_opt_core_adv_set |
NRF_MESH_OPT_NET_RELAY_TX_POWER | mesh_opt_core_tx_power_set |
NRF_MESH_OPT_NET_NETWORK_TRANSMIT_COUNT | mesh_opt_core_adv_set |
NRF_MESH_OPT_NET_NETWORK_TRANSMIT_INTERVAL_MS | mesh_opt_core_adv_set |
NRF_MESH_OPT_NET_NETWORK_TX_POWER | mesh_opt_core_tx_power_set |
Note that the transport-layer options are still only present on the old nrf_mesh_opt API. They will be migrated in the next release.
This guide describes the migration process from nRF5 SDK for Mesh version 1.0.1 to version 2.0.0.
In v1.0.1, the nrf_mesh_sdk and nrf_mesh_node_config modules could both be used for initializing a mesh device, and they had partly overlapping functionality. They have now been replaced by a single set of non overlapping modules:
mesh_stack: Functions for initializing and starting all mesh stack modules, including the foundation models.mesh_softdevice_init: Function for initializing the SoftDevice.mesh_provisionee: Simple provisionee support module containing the provisioning related parts of the old nrf_mesh_node_config, using PB-ADV and static OOB authentication. It is mainly intended to be used by the nRF5 SDK for Mesh examples, but it can also be used as a starting point for provisioning in a user application.The initialization code of the examples has now been restructured into an initialization phase and a start phase, following the same pattern as the nRF5 SDK examples. We strongly advise user applications to do the same. We have also added an execution_start() function to avoid the risk of race conditions during the start phase.
Following the same pattern as the nRF5 SDK, weak implementations of app_error_fault_handler (in examples/common/src/app_error_weak.c) and mesh_assertion_handler (in examples/common/src/assertion_handler_weak.c) have been provided. Instead of installing error handlers as callbacks, these functions are now used directly by the nRF5 SDK for Mesh error handling. They can be overloaded by the user application if needed.
Files from the nRF5 SDK are no longer included as part of the nRF5 SDK for Mesh release. Instead, the user is supposed to download the nRF5 SDK separately and provide a link to the nRF5 SDK folder when building the mesh code. See Retrieve nRF SDK for more details.
These are API changes that will break an existing application if ignored.
access_message_tx_t has two new fields: force_segmented and transmic_size.access_message_rx_t now reports richer low-level metadata for incoming packets, replacing meta_data.timestamp and meta_data.rssi with a pointer to a nrf_mesh_rx_metadata_t structure.access_reliable_status_t: New enum value ACCESS_RELIABLE_TRANSFER_CANCELLED.dsm_beacon_secmat_get() renamed to dsm_beacon_info_get(), and type of last parameter has changed from nrf_mesh_beacon_secmat_t to nrf_mesh_beacon_info_t.nrf_mesh_init_params_t (now included in mesh_stack_init_params_t): assertion_handler field removed, p_uuid field added.nrf_mesh_sar_session_cancel_reason_t (included in nrf_mesh_evt_t): New enum value NRF_MESH_SAR_CANCEL_PEER_STARTED_ANOTHER_SESSION.nrf_mesh_prov_listen(): bearer_type parameter changed to bearer_types, which is a bitfield for the supported bearers. That means that if multiple bearers are supported, you can listen for incoming provisioning requests on all of them at the same time.nrf_mesh_prov_evt_complete_t: Contains a pointer to a nrf_mesh_prov_provisioning_data_t structure now instead of a copy of the provisioning data.config_client_event_type_t: New enum value CONFIG_CLIENT_EVENT_TYPE_CANCELLED.config_client_composition_data_get(): Parameter page_number added.health_client_evt_type_t: New enum value HEALTH_CLIENT_EVT_TYPE_CANCELLED.simple_on_off_status_t: New enum value SIMPLE_ON_OFF_STATUS_CANCELLED.mesh/app folder to the examples/templates folder.These changes are API additions that will not break an existing application if ignored.
dsm_appkey_handle_to_subnet_handle() function added.nrf_mesh_subnet_added() function added.nrf_mesh_evt_t / nrf_mesh_evt_type_t: New event types NRF_MESH_EVT_NET_BEACON_RECEIVED and NRF_MESH_EVT_FLASH_STABLE.nrf_mesh_evt_iv_update_notification_t: p_network_id field added.nrf_mesh_evt_key_refresh_notification_t: p_network_id field added.config_client_pending_msg_cancel() function added.health_client_pending_msg_cancel() function added.simple_on_off_client_t: New field timeout_cb added.simple_on_off_client_pending_msg_cancel() function added.simple_on_off_server_status_publish() function added.access_model_publication_stop() function added.access_model_publication_by_appkey_stop() function added.