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;
       
         nrf_sdh_ble_app_ram_start_get
        
        (&ram_start);
       
         /* Configure the stack using the SoftDevice API (@ref sd_ble_cfg_set). */
        
        nrf_sdh_ble_enabled(&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. */
        
        NRF_BLE_OBSERVER(m_hrs_ble_observer,
        
         BLE_HRS_BLE_OBSERVER_PRIO
        
        ,
        
         ble_hrs_on_ble_evt
        
        , m_hrs);
       
        */
       
         /* Manually register the application as a BLE observer. */
        
        NRF_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:

The function ble_conn_params_change_conn_params() now takes an additional parameter, conn_handle , which specifies for which link to update the connection parameters.
The event structure now contains an additional member, conn_handle , which specifies to which link the event pertains.

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

The return code type has been changed from uint32_t to ret_code_t , requiring the sdk_errors.h header file.
The parameter of ble_conn_params_on_ble_evt has been made const .
The existing parameter of ble_conn_params_change_conn_params() has been renamed from new_params to p_new_params .

Flash Data Storage (FDS)

FDS record chunks removed

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

Old API :

        
         fds_record_t
        
        rec;
       
         fds_record_desc_t
        
        rec_desc;
       
        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 :

        
         fds_record_t
        
        rec;
       
         fds_record_desc_t
        
        rec_desc;
       
         // 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;
       
        }
        
         fds_header_t
        
        ;

New API :

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

CRC configuration options

CRC configuration options have changed.

FDS_CRC_ENABLED has been split into:
1. FDS_CRC_CHECK_ON_READ: If enabled, perform a CRC check upon opening a record.
2. FDS_CRC_CHECK_ON_WRITE: If enabled, perform a CRC check upon writing a record.
fds_crc_check_on_write(bool) has been removed.

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_WORDS	NRF_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

Changes in logger configuration for a module.
- The NRF_LOG_MODULE_NAME define must contain the module name without quotation marks.
- Each logger module must be registered using the NRF_LOG_MODULE_REGISTER() macro (defined in nrf_log.h ).

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_MODULE_REGISTER
        
        ();

A new line is appended to every log entry.

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

NRF_LOG_INIT() initializes only the logger frontend.

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

With initialized backend, call nrf_log_backend_add() .
Use the nrf_log_default_backends module. Call the NRF_LOG_DEFAULT_BACKENDS_INIT() macro after NRF_LOG_INIT() . Make sure that at least one of default backends is enabled in sdk_config.h ( NRF_LOG_BACKEND_RTT_ENABLED or NRF_LOG_BACKEND_UART_ENABLED ).
Use an instance of nrf_cli as the logger backend. See one of the examples ( examples/ble_peripheral/ble_app_cli or examples/peripheral/cli )

Configuration changes

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

Module and file names have changed.

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.

The following functions have changed.

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

The following data types have changed.

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

ret_code_t nfc_ble_pair_init ( nfc_pairing_mode_t mode);

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.

BLE_DFU_EVT_INDICATION_ENABLED
BLE_DFU_EVT_INDICATION_DISABLED

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.

Migration guide

nRF5 SDK v14.0.0

Table of Contents