nRF5 SDK v14.0.0
Migration guide

Table of Contents

If you built an application based on nRF5 SDK v13.0.0, complete the actions listed in the following sections to migrate your application to nRF5 SDK v14.0.0.

Note that this migration guide does not list all changes, but it covers the most important changes that require you to update your code. See the release notes for further information on changes that were made in this release.

Bluetooth low energy (BLE)

SoftDevice handler

The SoftDevice handler library has been reworked. The name of the library has changed from softdevice_handler to nrf_sdh and most of the API has changed accordingly.

The most commonly used functions have changed in the following way:

Old API New API
SOFTDEVICE_HANDLER_INIT nrf_sdh_enable_request()
softdevice_handler_sd_disable() nrf_sdh_disable_request()
softdevice_enable(uint32_t * ram_start) nrf_sdh_ble_enable(uint32_t * ram_start)
softdevice_app_ram_start_get(uint32_t * ram_start) nrf_sdh_ble_app_ram_start_get(uint32_t * ram_start)
N/A nrf_sdh_ble_default_cfg_set(uint8_t conn_cfg_tag, uint32_t * p_ram_start)

In all BLE examples, the ble_stack_init function was updated to reflect the required changes.

Action: Search and replace the occurences.

The stack configuration parameters are now part of the SoftDevice handler module configuration: SoftDevice BLE event handler configuration for BLE and SoftDevice ANT event handler configuration for ANT.

A new API call (nrf_sdh_ble_default_cfg_set) has been introduced to set up the stack with the configuration set in sdk_config. In all BLE examples, the ble_stack_init function was updated to reflect the required changes.

There are two schemes to configure the BLE stack:

nrf_sdh_enable_request(); /* Enable the SoftDevice. */
uint32_t ram_start;
/* Configure the stack using the SoftDevice API (@ref sd_ble_cfg_set). */
nrf_sdh_ble_enable(&ram_start); /* Enable the BLE stack. */

Alternatively:

nrf_sdh_enable_request(); /* Enable the SoftDevice. */
uint32_t const conn_cfg_tag = 1; /* A tag that identifies the BLE stack configuration. */
uint32_t ram_start;
nrf_sdh_ble_default_cfg_set(conn_cfg_tag, &ram_start); /* Configure the BLE stack with the settings specified in sdk_config. */
/* Optionally, configure any additional parameters using the SoftDevice API. */
nrf_sdh_ble_enable(&ram_start); /* Enable the BLE stack. */

Action: Update the stack configuration parameters in sdk_config.h as necessary, and update your stack initialization code.

The scheme for dispatching events from the SoftDevice to the libraries and services has changed: the ble_evt_dispatch and sys_evt_dispatch functions have been removed, in favor of registering BLE and SoC event observers using the NRF_SDH_BLE_OBSERVER and NRF_SDH_SOC_OBSERVER macros, respectively.

The following is an example of how an application previously used the ble_evt_dispatch function, dispatching BLE events to the HRS service and the application BLE event handler:

static void ble_evt_dispatch(ble_evt_t * p_ble_evt)
{
ble_hrs_on_ble_evt(&m_hrs, p_ble_evt);
on_ble_evt(p_ble_evt);
}

Using the new SoftDevice handler implementation, the service and the application receive BLE events automatically by registering themselves as BLE stack event observers, as shown below:

/* The following macro defines a Heart Rate service instance and registers it
to listen to relevant events coming from the SoftDevice. */
BLE_HRS_DEF(m_hrs); /* HRS instance. */
/* The BLE_HRS_DEF macro above is equivalent to the following pattern: */
ble_hrs_t m_hrs; /* HRS instance. */
m_hrs_ble_observer,
m_hrs
);
/* Manually register the application as a BLE observer. */
m_app_ble_observer, /* Name of the observer. */
APP_BLE_OBSERVER_PRIO, /* Priority of the observer. */
on_ble_evt, /* Handler function. */
NULL /* Optional parameter to the handler. */
);

All examples using the SoftDevice have been updated to reflect these changes. A similar mechanism is in place for ANT examples as well.

Action: Update your application as shown in the examples.

Advertising Module (ble_advertising)

Memory for the advertising module has been moved to the new struct ble_advertising_t. The struct must be passed as a reference when the module is used. All APIs to the advertising module have been modified to reflect this change.

Example of a change in ble_advertising.h:

Old:

uint32_t ble_advertising_start(ble_adv_mode_t advertising_mode);

New:

uint32_t ble_advertising_start(ble_advertising_t * const p_advertising, ble_adv_mode_t advertising_mode);

Action: Declare ble_advertising_t in your application code. Modify all calls to ble_advertising to take this struct as the first parameter.

ble_advertising_init

A new struct ble_advertising_init_t is used to initialize the advertising module. This makes the module consistent with other BLE modules. The struct contains the same parameters that are already being passed to ble_advertising_init.

Old:

uint32_t ble_advertising_init(ble_advdata_t const * p_advdata, ble_advdata_t const * p_srdata, ble_adv_modes_config_t const * p_config, ble_adv_evt_handler_t const evt_handler, ble_adv_error_handler_t const error_handler);

New:

uint32_t ble_advertising_init(ble_advertising_t * const p_advertising, ble_advertising_init_t const * const p_init);

Action: Modify your code so that the old init parameters are now part of the init struct instead.

Advertising Encoder (ble_advdata)

For consistency, the name of adv_data_encode() was changed to ble_advdata_encode(). This matches the naming scheme of ble_advdata.c There is no functional change.

Renamed API:

Old: adv_data_encode()

New: ble_advdata_encode()

Action: Update to use the new name.

Connection Parameters Module (ble_conn_params)

This module has been updated to support multiple concurrent peripheral roles. It will negotiate connection parameters independently on each peripheral link. As a consequence, the API has the following changes:

In addition, the following minor API changes have been made for consistency and correctness:

Flash Data Storage (FDS)

FDS record chunks removed

Note
This feature is distinct from the 'chunks' in nrf_fstorage.

Old API:

fds_record_chunk_t rec_chunk;
// Prepare chunk.
rec_chunk.p_data = p_data;
rec_chunk.length_words = length_words;
// Prepare the record to be stored in flash.
rec.file_id = file_id;
rec.key = key;
rec.data.p_chunks = &rec_chunk;
rec.data.num_chunks = 1;
fds_record_write(&rec_desc, &rec);

New API:

// Prepare the record to be stored in flash.
rec.file_id = file_id;
rec.key = key;
rec.data.p_data = p_data;
rec.data.length_words = length_words;
fds_record_write(&rec_desc, &rec);

The FDS_CHUNK_QUEUE_SIZE configuration option was removed.

fds_header_t

The fds_ic_t and fds_tl_t structs have been removed. The fds_header_t struct has changed.

Note
This change does not modify the FDS record format in flash.

Old API:

typedef struct
{
uint16_t record_key;
uint16_t length_words;
} fds_tl_t;
typedef struct
{
uint16_t file_id;
uint16_t crc16;
} fds_ic_t;
typedef struct
{
fds_tl_t tl;
fds_ic_t ic;
uint32_t record_id;

New API:

typedef struct
{
uint16_t record_key;
uint16_t length_words;
uint16_t file_id;
uint16_t crc16;
uint32_t record_id;

CRC configuration options

CRC configuration options have changed.

fstorage

The following fstorage APIs have been changed:

Old New Remarks
fs_init nrf_fstorage_init
fs_store nrf_fstorage_write Length parameters are expressed in bytes instead of words.
fs_erase nrf_fstorage_erase
nrf_fstorage_read New API.
fs_queued_op_count_get nrf_fstorage_is_busy

The following fstorage macros have been changed:

Old New Remarks
FS_REGISTER_CFG NRF_FSTORAGE_DEF
FS_OP_QUEUE_SIZE NRF_FSTORAGE_SD_QUEUE_SIZE
FS_OP_MAX_RETRIES NRF_FSTORAGE_SD_MAX_RETRIES
FS_MAX_WRITE_SIZE_WORDSNRF_FSTORAGE_SD_MAX_WRITE_SIZE Now expressed in bytes.

The following fstorage data types have been changed:

Old New Remarks
fs_config_t nrf_fstorage_t
  • p_start_addr -> start_addr (must be manually set)
  • p_end_addr -> end_addr (must be manually set)
  • priority -> removed
  • callback -> evt_handler
fs_evt_t nrf_fstorage_evt_t Structure changed slightly.
fs_evt_id_t nrf_fstorage_evt_id_t See Events.
fs_cb_t nrf_fstorage_evt_handler_t Signature changed slightly.

The following fstorage events have been changed:

Old New
FS_EVT_STORE NRF_FSTORAGE_EVT_WRITE_RESULT
FS_EVT_ERASE NRF_FSTORAGE_EVT_ERASE_RESULT

The following fstorage return values have been changed:

Old New
FS_SUCCESS NRF_SUCCESS
FS_ERR_NOT_INITIALIZED NRF_ERROR_INVALID_STATE
FS_ERR_NULL_ARG NRF_ERROR_NULL
FS_ERR_INVALID_ARG NRF_ERROR_INVALID_LENGTH
FS_ERR_INVALID_CFG Removed
FS_ERR_INVALID_ADDR NRF_ERROR_INVALID_ADDR
FS_ERR_UNALIGNED_ADDR NRF_ERROR_INVALID_ADDR
FS_ERR_QUEUE_FULL NRF_ERROR_NO_MEM
FS_ERR_NOT_SUPPORTED NRF_ERROR_NOT_SUPPORTED
FS_ERR_INTERNAL NRF_ERROR_INTERNAL

Configuration of the BLE stack

Examples now configure the stack using the nrf_sdh function nrf_sdh_ble_default_cfg_set(). The function configures the BLE stack based on the paramenters in the nrf_sdh_ble group from the sdk_config file. Those parameters are also used by other libraries in the SDK, such as ble_conn_params and nrf_ble_gatt. Update them as necessary in your projects.

Libraries

The API of the following libraries has been changed.

nrf_cli

The command line interface has been significantly reworked and is currently in experimental state. Familiarize yourself with new documentation and example to see how to use the improved CLI module. See Experimental: Command Line Interface library and Command Line Interface (CLI) Example.

nrf_log

Example:

#define NRF_LOG_MODULE_NAME "spi"
#include "nrf_log.h"

The above code must be changed to:

#define NRF_LOG_MODULE_NAME spi
#include "nrf_log.h"

NRF_LOG_INFO("my log\r\n") must be changed to NRF_LOG_INFO("my log").

In order to get logs out, a backend must be added. You can add a backend in multiple ways.

NRF_LOG_DEFERRED_BUFSIZE renamed to NRF_LOG_BUFSIZE. Added options:

nrf_pwr_mgmt

Usage of the NRF_PWR_MGMT_HANDLER_REGISTER macro has been modified.

bool shutdown_handler(nrf_pwr_mgmt_evt_t event)
{
}
NRF_PWR_MGMT_HANDLER_REGISTER(m_unused_variable, 0) = shutdown_handler;

The above code must be replaced with:

bool shutdown_handler(nrf_pwr_mgmt_evt_t event)
{
}
NRF_PWR_MGMT_HANDLER_REGISTER(shutdown_handler, 0);

Atomic FIFO

Old name New name Remarks
app_atfifo nrf_atfifo Module renamed.
app_atfifo.h nrf_atfifo.h
app_atfifo.c nrf_atfifo.c
app_atfifo_ nrf_atfifo_ Renamed the prefix of all functions, variables, and types.
APP_ATFIFO_ NRF_ATFIFO_ Renamed the prefix of all functions, variables, and types.
Old name New name Remarks
app_atfifo_put nrf_atfifo_alloc_put
app_atfifo_get nrf_atfifo_get_free
app_atfifo_wopen nrf_atfifo_item_alloc The last argument (size) has been removed. Function always allocates the size for a single element.
app_atfifo_wcommit nrf_atfifo_item_put
app_atfifo_ropen nrf_atfifo_item_get The last argument (size) has been removed. Function always assumes that the element has the correct size of the one element.
app_atfifo_rflush nrf_atfifo_item_free
Old name New name
app_atfifo_wcontext_t nrf_atfifo_item_put_t
app_atfifo_rcontext_t nrf_atfifo_item_get_t

NFC

NDEF record and message descriptors

NDEF record and message descriptors are declared as automatic variables, which implies that the NDEF message encoding must be done in the same variable scope. Previously, all record and message descriptors were declared static.

NFC BLE pairing library

Due to updates in the advertising module, the function nfc_ble_pair_init() takes a pointer to the advertising module data p_advertising.

Old

New

ret_code_t nfc_ble_pair_init(ble_advetising_t * p_advertising, nfc_pairing_mode_t mode);

Action: Modify your code by adding the pointer to the advertising module data as a parameter to nfc_ble_pair_init().

DFU

The BLE Secure Bootloader has added configurations for requiring bonds and for unbonded switching between itself and the application. Any implementation must choose which one of these configurations to enable. No changes to the example implementation should be required, but this choice should be made in the configuration of both the Buttonless DFU Template Application and the BLE Secure DFU Bootloader.

To enable or disable the support of bonds in the Buttonless DFU Template Application, modify these configuration parameters in the sdk_config file:

sdk_config.h
#ifndef NRF_DFU_BLE_BUTTONLESS_SUPPORTS_BONDS
#define NRF_DFU_BLE_BUTTONLESS_SUPPORTS_BONDS 1
#endif

To enable or disable the support of bonds in the Secure DFU Bootloader, modify these configuration parameters in the sdk_config file:

sdk_config.h
#ifndef NRF_DFU_BLE_REQUIRES_BONDS
#define NRF_DFU_BLE_REQUIRES_BONDS 1
#endif#endif

Action: Case 1: Implementations utilizing a button to switch to DFU must be updated to utilize either bonded or unbonded switching.

Action: Case 2: With buttonless DFU, the changes are significant. It is recommended not to port the example but to just use the new implementation.

Inactivity timeout timer

Secure DFU has an added inactivity timeout timer that will automatically reset the device in case there are no new incoming command requests received by the bootloader within the configured timeout limit. The inactivity timeout can be adjusted from the default time of 2 minutes by modifying NRF_DFU_INACTIVITY_TIMEOUT_MS in the sdk_config file.

#ifndef NRF_DFU_INACTIVITY_TIMEOUT_MS
#define NRF_DFU_INACTIVITY_TIMEOUT_MS 120000
#endif

DFU API changes

The following defines have been renamed.

Old name New name
BLE_DFU_EVT_ENTERING_BOOTLOADER BLE_DFU_EVT_BOOTLOADER_ENTER
DFU_RSP_RESERVED DFU_RSP_INVALID

The following defines have been removed.

The following data types have been renamed:

Old name New name Remarks
ble_dfu_evt_type_t ble_dfu_buttonless_evt_type_t
ble_dfu_rsp_code_t ble_dfu_buttonless_rsp_code_t
ble_dfu_init_t ble_dfu_buttonless_init_t
ble_dfu_evt_handler_t ble_dfu_buttonless_evt_handler_t Parameters have changed.

The following functions have been renamed.

Old name New name Remarks
ble_dfu_init ble_dfu_buttonless_init Parameters have changed.
ble_dfu_on_ble_evt ble_dfu_buttonless_on_ble_evt Parameters have changed.

Struct ble_dfu_s has been renamed to ble_dfu_buttonless_t.

The type of evt_handler has been changed from ble_dfu_evt_handler_t to ble_dfu_buttonless_evt_handler_t and the members ctrl_point_security_req_write_perm and ctrl_point_security_req_cccd_write_perm have been deleted.

USB

USBD START and STOP events renamed

Old name New name
APP_USBD_EVT_START APP_USBD_EVT_STARTED
APP_USBD_EVT_STOP APP_USBD_EVT_STOPPED

Processing of high level events in the main loop

APP USBD now processes high level events in the main loop. Processing of high level interrupts on thread level minimizes the time the library spends in interrupt context.

Action: Option 1: Set APP_USBD_EVENT_QUEUE_ENABLE to false to let all the high level interrupts to be processed in interrupt context.

Action: Option 2: Call app_usbd_event_queue_process() in a loop on the thread context. Update your USB configuration structure. For details, see app_usbd_config_t.

USB audio class API rebuilt

The USB audio API was rebuilt to give the user more control over the timing when new data should be processed. Now, the user does not set the tx and rx buffers inside the library, but must call app_usbd_audio_class_rx_start and app_usbd_audio_class_tx_start to transfer the data. These functions may be called anytime between SOF events.


Documentation feedback | Developer Zone | Subscribe | Updated