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.
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:
Alternatively:
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:
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:
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.
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:
New:
Action: Declare ble_advertising_t in your application code. Modify all calls to ble_advertising
to take this struct as the first parameter.
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:
New:
Action: Modify your code so that the old init parameters are now part of the init struct instead.
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.
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:
conn_handle
, which specifies for which link to update the connection parameters.conn_handle
, which specifies to which link the event pertains.In addition, the following minor API changes have been made for consistency and correctness:
uint32_t
to ret_code_t
, requiring the sdk_errors.h
header file.ble_conn_params_on_ble_evt
has been made const
.new_params
to p_new_params
.Old API:
New API:
The FDS_CHUNK_QUEUE_SIZE
configuration option was removed.
The fds_ic_t
and fds_tl_t
structs have been removed. The fds_header_t
struct has changed.
Old API:
New API:
CRC configuration options have changed.
FDS_CRC_ENABLED
has been split into:FDS_CRC_CHECK_ON_READ:
If enabled, perform a CRC check upon opening a record.FDS_CRC_CHECK_ON_WRITE:
If enabled, perform a CRC check upon writing a record.fds_crc_check_on_write(bool)
has been removed.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 |
|
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 |
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.
The API of the following libraries has been changed.
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_MODULE_NAME
define must contain the module name without quotation marks.nrf_log.h
).Example:
The above code must be changed to:
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_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
).nrf_cli
as the logger backend. See one of the examples (examples/ble_peripheral/ble_app_cli
or examples/peripheral/cli
)NRF_LOG_DEFERRED_BUFSIZE renamed to NRF_LOG_BUFSIZE. Added options:
Usage of the NRF_PWR_MGMT_HANDLER_REGISTER macro has been modified.
The above code must be replaced with:
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 |
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.
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
Action: Modify your code by adding the pointer to the advertising module data as a parameter to nfc_ble_pair_init().
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:
To enable or disable the support of bonds in the Secure DFU Bootloader, modify these configuration parameters in the sdk_config
file:
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.
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.
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.
Old name | New name |
---|---|
APP_USBD_EVT_START | APP_USBD_EVT_STARTED |
APP_USBD_EVT_STOP | APP_USBD_EVT_STOPPED |
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.
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.