Migration guide

Table of Contents

• Bluetooth low energy (BLE)
  • GATT Queue
  • Advertising Module
    • Removed unused API
    • Modified API
  • Database Discovery Module
    • New structures
    • Modified structures
    • Modified API
  • Peer Manager
• DFU and Bootloader
  • DFU
  • Bootloader
• Libraries
  • Libuarte
  • Timer library (app_timer)

If you built an application based on nRF5 SDK v15.3.0, complete the actions listed in the following sections to migrate your application to nRF5 SDK v16.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)

GATT Queue

The BLE GATT Queue module has been introduced in nRF5 SDK v16.0.0. To use it in your project, do the following:

1. Include the GATT Queue module into your project. It can be found in the components/ble/nrf_ble_gq directory. The module depends on the following components:
   • Queue library (nrf_queue)
   • Memory object library (nrf_memobj)
   • SoftDevice Handler library (nrf_sdh_ble)
2. Set the NRF_BLE_GQ_ENABLED configuration option in the sdk_config.h file. Make sure that the module's dependencies are enabled as well.
3. At the application level, define the BLE GATT Queue instance with the following macro:

   NRF_BLE_GQ_DEF(m_ble_gatt_queue,
    NRF_SDH_BLE_CENTRAL_LINK_COUNT,
    NRF_BLE_GQ_QUEUE_SIZE);

4. Identify the BLE components that depend on the BLE GATT Queue module. Refer to the BLE components using GATT Queue module for the list of components.
5. Populate the appropriate field of their initialization structure. The following code snippet shows how it is done for the BAS Client module:

    /**
    @brief Battery level collector initialization.
    */
   static void bas_c_init(void)
   {
    ble_bas_c_init_t bas_c_init_obj;
    
    bas_c_init_obj.evt_handler = bas_c_evt_handler;
    bas_c_init_obj.p_gatt_queue = &m_ble_gatt_queue;
    
    ret_code_t err_code = ble_bas_c_init(&m_bas_c, &bas_c_init_obj);
    APP_ERROR_CHECK(err_code);
   }

BLE components using GATT Queue module:

• Database Discovery
• Alert Notification Service Client
• Apple Notification Service Client
• Battery Service Client
• Blood Pressure Service
• Current Time Service Client
• Device Information Service Client
• Heart Rate Service Client
• Health Thermometer Service
• Immediate Alert Service Client
• LED Button Service Client
• Nordic UART Service Client
• Running Speed and Cadence Service Client
• Location and Navigation Service
• Object Transfer Service
• Object Transfer Service Client
• GATT Service Client
• Continuous Glucose Meter Service

Advertising Module

Removed unused API

The following API has been removed:

void ble_advertising_on_sys_evt(uint32_t sys_evt, void * p_adv);

Modified API

Modified the ble_advertising_advdata_update API, such that no additional buffer is required - the module uses its internal swap buffer.

Old:

ret_code_t ble_advertising_advdata_update(ble_advertising_t * const p_advertising,
 ble_gap_adv_data_t * const p_new_advdata_buf,
 bool permanent);

New:

ret_code_t ble_advertising_advdata_update(ble_advertising_t * const p_advertising,
 ble_advdata_t const * const p_advdata,
 ble_advdata_t const * const p_srdata);

Database Discovery Module

New structures

The following new structures have been defined:

• ble_db_discovery_user_evt_t
• ble_db_discovery_init_t

Modified structures

The following structures have been modified:

• ble_db_discovery_t
• ble_db_discovery_evt_t
• ble_db_discovery_evt_handler_t

Modified API

The following API has been modified:

• ble_db_discovery_init()

Old:

/**@brief Function for initializing the DB Discovery module.
 
 @param[in] evt_handler Event handler to be called by the DB discovery module when any event
 related to discovery of the registered service occurs.
 
 @retval NRF_SUCCESS On successful initialization.
 @retval NRF_ERROR_NULL If the handler was NULL.
 */
uint32_t ble_db_discovery_init(ble_db_discovery_evt_handler_t evt_handler);

New:

/**@brief Function for initializing the DB Discovery module.
 
 @param[in] p_db_init Pointer to DB discovery initialization structure.
 
 @retval NRF_SUCCESS On successful initialization.
 @retval NRF_ERROR_NULL If the initialization structure was NULL or
 the structure content is empty.
 */
uint32_t ble_db_discovery_init(ble_db_discovery_init_t * p_db_init);

• ble_db_discovery_close()

Old:

/*
 @retval NRF_SUCCESS Operation success.
*/
uint32_t ble_db_discovery_close(void);

New:

/**@brief Function for closing the DB Discovery module.
 
 @details This function will clear up any internal variables and states maintained by the
 module. To re-use the module after calling this function, the function @ref
 ble_db_discovery_init must be called again. When using more than one DB Discovery
 instance, this function should be called for each instance.
 
 @param[out] p_db_discovery Pointer to the DB discovery structure.
 
 @retval NRF_SUCCESS Operation success.
 */
uint32_t ble_db_discovery_close(ble_db_discovery_t * const p_db_discovery);

• The library now uses the BLE GATT Queue module.

Peer Manager

1. The len and p_len parameters to pm_peer_data_store() and pm_peer_data_load() as well as their derived functions have had their types changed from uint16_t to uint32_t.
2. Because of the disambiguation of FDS error codes, the fds_error member in pm_evt_t is no longer needed and has been removed. Code that accesses this member can be deleted since only a check against the actual error code value is now needed.
3. The slave_security_req event structure has had its type changed to the type used by the SoftDevice: ble_gap_evt_sec_request_t (defined in ble_gap.h). No change to the existing code should be needed.
   Old:

   /**@brief Events parameters specific to the @ref PM_EVT_SLAVE_SECURITY_REQ event.
    */
   typedef struct
   {
    bool bond; /**< @brief Whether the peripheral requested bonding. */
    bool mitm; /**< @brief Whether the peripheral requested man-in-the-middle protection. */
   } pm_evt_slave_security_req_t;

   
   New:

   /**@brief Event structure for @ref BLE_GAP_EVT_SEC_REQUEST. */
   typedef struct
   {
    uint8_t bond : 1; /**< Perform bonding. */
    uint8_t mitm : 1; /**< Man In The Middle protection requested. */
    uint8_t lesc : 1; /**< LE Secure Connections requested. */
    uint8_t keypress : 1; /**< Generation of keypress notifications requested. */
   } ble_gap_evt_sec_request_t;

4. The pm_conn_sec_status_t structure has gained a new flag lesc. Also, the unused flags have been made accessible via the member reserved, which should be set to 0.

DFU and Bootloader

DFU

• Updating from one SoftDevice family to another is now not allowed (for example from S113 to S140).

Bootloader

1. A new delay has been added immediately before each reset. It can be configured in sdk_config.h as NRF_BL_DELAY_MS (default 0). You can use this functionality in situations when, for example, your bootloader cannot disconnect or cannot finish printing logs in time for the reset. Previously a static delay of 100 ms was added in debug projects, but this has been removed.
2. nrf_bootloader_app_start() can no longer be called from interrupt context. If this functionality is needed, copy the code from a previous SDK release.
3. The bootloader settings page is no longer writable from the app, unless either NRF_BL_DFU_ALLOW_UPDATE_FROM_APP or NRF_BL_DFU_ENTER_METHOD_BUTTONLESS is enabled.

Libraries

Libuarte

Lower layer (the driver) for libuarte has been renamed from nrf_libuarte to nrf_libuarte_drv. Renaming includes changing of both file names and API prefixes (from nrf_libuarte_* to nrf_libuarte_drv_*).

Timer library (app_timer)

App Timer v2 is moved out of experimental. It is updated and API-compatible with the old implementation making it easy to replace.

To replace app_timer v1 with app_timer v2 in your existing project, you must add files app_timer2.c and drv_rtc.c in place of the app_timer.c file. You must also add an APP_TIMER_V2 define to the project.