If you built an application based on nRF5 SDK v12.2.0, complete the actions listed in the following sections to migrate your application to nRF5 SDK v13.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.
SDK v13.0.0 supports the BLE SoftDevices S132 v4.0.2 and S140 v5.0.0-2.alpha. The SDK was adapted to the newest SoftDevice API.
For additional details about the SoftDevices, see s132_nrf52_4.0.2_migration-document.pdf and s132_nrf52_4.0.2_releasenotes.pdf located in components\softdevice\s132\doc and s140_nrf52840_5.0.0-2.alpha_migration-document.pdf and s140_nrf52840_5.0.0-2.alpha_release-notes-update-1.pdf located in components\softdevice\s140\doc.
Action: If you use direct SoftDevice calls, follow the steps outlined in the SoftDevice migration documents to update your application to the newest API.
The following changes were done to the API of the SoftDevice handler library:
Changed API: softdevice_enable(uint32_t * ram_start) (before: softdevice_enable(ble_enable_params_t * ble_enable_params))
Previously, the RAM start address was used only internally in softdevice_enable. Now, it is needed in the new SoftDevice call sd_ble_cfg_set, which may be called several times before softdevice_enable.
Action: Make sure to call softdevice_app_ram_start_get before calling sd_ble_cfg_set and softdevice_enable, and update your calls to softdevice_enable.
Removed API: softdevice_enable_get_default_config
sd_ble_cfg_set along with new default values supplied by the SoftDevice has eliminated the old scheme of fetching an SDK-defined default from softdevice_enable_get_default_config.
Action: Remove all calls to softdevice_enable_get_default_config.
For all BLE examples, the ble_stack_init function was updated to reflect the required changes. Function calls preceding sd_ble_enable have changed to reflect the new SoftDevice.
Action: Update your application as shown in the BLE examples.
The following API was added to the Advertising Module:
This function sets the configuration tag that is used for a connection in the advertising module. Any connection that is made uses the connection configuration tag that is currently set. If the new API function is not called, a default connection tag is used.
ble_advertising_conn_cfg_tag_set must be called after ble_advertising_init, but before ble_advertising_start.
The connection configuration tag is the tag used in sd_ble_cfg_set. In the SDK examples, the tag is set up during ble_stack_init.
Action: Use this function if you want to use non-default settings for an upcoming connection.
In the Nordic UART Service and Nordic UART Service Client, the terminology use of RX and TX was inverted compared to the apps that can interact with the service (for example, the nRF Toolbox UART app). This mismatch has been corrected in this release. As a result, the names of a few of the functions in the Nordic UART Service have changed.
Action: Update your function calls from ble_nus_c_rx_notif_enable (old) to ble_nus_c_tx_notif_enable (new).
The UART/Serial Port Emulation over BLE example was changed to not check for a '\r' character when parsing input from UART, because it would send empty packets over the air when "\r\n" was together. Therefore, UART terminals used with the ble_app_uart example must send '\n' as newline. Sending '\r' alone is not sufficient.
Action: Update your terminals to use '\n' as newline when interacting with the ble_app_uart example.
The following changes were done to the Experimental: GATT Module:
The library now handles BLE_GAP_EVT_DATA_LENGTH_UPDATE_REQUEST and BLE_GAP_EVT_DATA_LENGTH_UPDATE events from the SoftDevice. Note that the library currently supports only symmetric data length RX/TX values.
Action: If you handled these two events manually in your application, you can now use the GATT module instead.
The structure nrf_ble_gatt_evt_t was changed to include the event type and parameters (as a union):
Old:
New:
Action: Update your event handlers to handle the changed nrf_ble_gatt_evt_t.
The Experimental: GATT Module (nrf_ble_gatt) was included in all BLE example applications. ATT_MTU exchange and data length update procedures are handled by the library and need not be handled manually by the application anymore.
Action: Update your application as shown in the BLE examples.
SDK v13.0.0 supports the ANT SoftDevice S212 v4.0.0. The ANT channel configuration was adapted to the newest SoftDevice API.
For additional details about the ANT SoftDevices, see thisisant.com.
Action: The new S212 SoftDevice API is an extension of the v2.0.0, so no updates are required unless you want to use added functionality.
The following BLE/NFC examples were refactored to use the NFC BLE pairing library:
Action: For the above examples, select the desired pairing mode in the sdk_config.h file:
Extended error codes is a new set of error codes that the DFU target may send as a response to the DFU controller. When the DFU controller receives an error code "0x0B", this indicates that the next byte of the packet contains more detailed information about the cause of the error.
Action: If you have an implementation of, for example, a mobile app for performing DFU, update it to handle the new "0x0B" error code.
On nRF52840 devices, the bootloader is now located at the end of the device's flash area (0xF8000). This allows for larger applications to coexist with the bootloader.
Action: Make sure that the bootloader settings page is at the correct location. nrfutil accepts "--family NRF52840" to generate a bootloader settings page that is compatible with nRF52840 devices.
The Buttonless DFU Service now uses the Nordic proprietary 16-bit UUID reserved for Nordic Secure DFU (0xFE59).
The Buttonless DFU characteristic has a new UUID: 0x8EC90003-F315-4F60-9FB8-838830DAEA50. It has been changed from notification to indication.
Action: Update your application that interacts with the Buttonless DFU Service to use the new UUID and to handle incoming indications instead of notifications on the Buttonless DFU characteristic.
Changed API: The ticks_per_100ms parameter was removed from the Board Support Package (BSP) initialization function bsp_init.
Action: Remove the ticks_per_100ms parameter from the function call.
The API functions of the POWER driver now return error codes. The driver must be initialized before the SoftDevice is enabled.
Action: Handle the return codes in your application.
The nrf_drv_pwm_simple_playback and nrf_drv_pwm_simple_playback functions of the PWM driver now return error codes. However, they will always return NRF_SUCCESS unless PPI is used to trigger playback.
Action: If you are using PPI to trigger playback, handle the return codes in your application. Otherwise, ignore the return codes.
Changed API: The nrf_drv_spi_init function and the event handler of the SPI master driver require a new parameter p_context. This parameter is returned in the event handler.
Action: Update your function calls. If you do not want to use the new feature, pass p_context=NULL.
The Capacitive Sensor low-level library can use COMP or SAADC. However, COMP is not recommended because of Anomaly 84.
Action: Update sdk_config.h and configure the module to use SAADC.
Changed API: The ticks_per_1s parameter was removed from the Power Management library initialization function nrf_pwr_mgmt_init.
Action: Remove the ticks_per_1s parameter from the function call.
The following changes were done to the Timer library:
The static configuration of the library (prescaler, queue size, use of app_scheduler) was moved to sdk_config.h.
Action: Update your sdk_config.h file with the new parameters.
Removed API: APP_TIMER_INIT
Action: Replace calls to the APP_TIMER_INIT macro with calls to the app_timer_init function.
Changed API: The PRESCALER parameter of the APP_TIMER_TICKS macro was removed.
Action: Remove the PRESCALER parameter from the macro call.
The app_timer_appsh module was removed.
Action: If you used the app_timer_appsh module, replace calls to APP_TIMER_APPSH_INIT with calls to app_timer_init and enable the APP_TIMER_CONFIG_USE_SCHEDULER option in sdk_config.h.
The following changes were done to the TWI transaction manager:
Removed API: APP_TWI_INIT
Action: Replace calls to APP_TWI_INIT(&m_app_twi, &config, QUEUE_SIZE, err_code) with calls to app_twi_init(&m_app_twi, &config).
New API: APP_TWI_DEF
Action: Replace the code app_twi_t m_app_twi = APP_TWI_INSTANCE(TWI_IDX) with APP_TWI_DEF(m_app_twi, QUEUE_SIZE, TWI_IDX).