s13x_nrf5x migration document
Introduction to the s13x_nrf5x migration document
About the document
This document describes how to migrate to new versions of the s130_nrf51 and s132_nrf52 SoftDevices. The s130_nrf51 and s132_nrf52
release notes should be read in conjunction with this document.
For each version, we have the following sections:
"Required changes" describes how an application would have used the previous version of the SoftDevice and how it must now use
this version for the given change.
"New functionality" describes how to use new features and functionality offered by this version of the SoftDevice. Not all new Note:
functionality may be covered; the release notes will contain a full list of new features and functionality.
Each section describes how to migrate to a given version from the previous version. If you are migrating to the current version from the
previous version, follow the instructions in that section. To migrate between versions that are more than one version apart, follow the
migration steps for all intermediate versions in order.
Example: To migrate from version 5.0.0 to version 5.2.0, first follow the instructions to migrate to version 5.1.0 from version 5.0.0, then
follow the instructions to migrate to version 5.2.0 from version 5.1.0.
Copyright (c) Nordic Semiconductor ASA. All rights reserved.
s132_nrf52_6.0.0
This section describes how to migrate to s132_nrf52_6.0.0 from s132_nrf52_5.1.0.
Notes:
s132_nrf52_6.0.0 has changed the API compared to s132_nrf52_5.1.0 which requires applications to be recompiled.
s132_nrf52_6.0.0 includes some features that are not Bluetooth qualified. For more information, see the release notes.
New functionality
Quality of Service (QoS) channel survey
This feature provides measurements of the energy levels on the Bluetooth Low Energy channels to the application. The application can use
this information to determine the noise floor on a per channel basis and set an adapted channel map to avoid busy channels.
When the feature is enabled, events will periodically report the measured energy levels BLE_GAP_EVT_QOS_CHANNEL_SURVEY_REPORT
for each channel. The channel energy is reported in ble_gap_evt_qos_channel_survey_report_t::channel_energy
, indexed by the Channel Index. The SoftDevice will attempt to measure energy levels and deliver reports [BLE_GAP_CHANNEL_COUNT]
with the average interval specified in .interval_us
Note: To make the channel survey feature available to the application, ble_gap_cfg_role_count_t::
must be set. This is done using the API.qos_channel_survey_role_available sd_ble_cfg_set()
The event structures for and have been changed to provide the application BLE_GAP_EVT_RSSI_CHANGED BLE_GAP_EVT_ADV_REPORT
the channel number for reported Received Signal Strength Indication (RSSI) measurements. For more information, see Updated RSSI API in
the Required changes section.
API Updates
A new Boolean flag, ,ble_gap_cfg_role_count_t::qos_channel_survey_role_available must be set in the SoftDevice
role configuration API to make the channel survey available for the application.
Two new SV calls have been added to start and stop the channel survey:
sd_ble_gap_qos_channel_survey_start()
sd_ble_gap_qos_channel_survey_stop()
Usage
/* Make Channel Survey feature available to the application */
ble_cfg_t cfg;
cfg.role_count.qos_channel_survey_role_available = 1;
sd_ble_cfg_set(..., &cfg, ...);
/* Start receiving channel survey continuously. */
uint32_t errcode;
errcode = sd_ble_gap_qos_channel_survey_start
(BLE_GAP_QOS_CHANNEL_SURVEY_INTERVAL_CONTINUOUS);
int8_t rssi;
/* A new measurement is ready. */
case BLE_GAP_EVT_QOS_CHANNEL_SURVEY_REPORT:
{
for (i = 0; i < BLE_GAP_CHANNEL_COUNT; i++)
{
rssi = p_ble_evt->evt.gap_evt.params.qos_channel_survey_report.
channel_energy[i];
}
}
/* Stop receiving channel survey. */
errcode = sd_ble_gap_qos_channel_survey_stop()
Advertising Extensions
The LE Advertising Extensions feature has limited support in this SoftDevice that can be enabled with the new advertiser and scanner API.
The feature may not function as specified, and may contain issues. For more information, see the release notes.
Extended Advertiser
Extended advertising can be enabled by assigning an advertising type to the _EXTENDED_ ble_gap_adv_params_t::properties::
.type
The extended advertising types are:
BLE_GAP_ADV_TYPE_EXTENDED_CONNECTABLE_NONSCANNABLE_UNDIRECTED
BLE_GAP_ADV_TYPE_EXTENDED_CONNECTABLE_NONSCANNABLE_DIRECTED
BLE_GAP_ADV_TYPE_EXTENDED_NONCONNECTABLE_SCANNABLE_UNDIRECTED
BLE_GAP_ADV_TYPE_EXTENDED_NONCONNECTABLE_SCANNABLE_DIRECTED
BLE_GAP_ADV_TYPE_EXTENDED_NONCONNECTABLE_NONSCANNABLE_UNDIRECTED
BLE_GAP_ADV_TYPE_EXTENDED_NONCONNECTABLE_NONSCANNABLE_DIRECTED
New parameters in the API that are relevant for extended advertising:
ble_gap_adv_params_t::properties::anonymous
If this flag is set to 1, the advertiser's address will be omitted from all PDUs. This is only available for extended advertising
event types.
ble_gap_adv_params_t::primary_phy
Indicates the PHY on which the primary advertising channel packets are transmitted.
For extended advertising event types, this can be set to , , or BLE_GAP_PHY_AUTO BLE_GAP_PHY_1MBIT BLE_GAP_PHY_C
if supported by the SoftDevice.ODED
ble_gap_adv_params_t::secondary_phy
Indicates the PHY on which the auxiliary PDUs will be sent.
Can be set to , , , or if BLE_GAP_PHY_AUTO BLE_GAP_PHY_1MBPS BLE_GAP_PHY_2MBPS BLE_GAP_PHY_CODED
supported by the SoftDevice.
ble_gap_adv_params_t::set_id
This value is used as the Advertising Set ID in the AdvDataInfo field of the PDU.
Extended Scanner
Scanning of extended advertising PDUs can be enabled by setting the flag to 1 for the scan ble_gap_scan_params_t::extended
parameters provided to . If set to 1, both legacy and extended advertising PDUs will be scanned. If the flag is sd_ble_gap_scan_start()
set to 0, all extended advertising PDUs will be ignored by the scanner. Correspondingly, to connect to a peer that is advertising with
extended advertising PDUs, set the flag to 1 for the scan parameters provided to ble_gap_scan_params_t::extended sd_ble_gap_c
.onnect()
New parameters in the API that are relevant for extended scanning:
ble_gap_scan_params_t::report_incomplete_evts
This option is currently not supported.
ble_gap_evt_adv_report_t::type::extended_pdu
Will be set to 1 if an extended advertising set is received.
ble_gap_evt_adv_report_t::tx_power
The transmit power reported by the advertising in the last packet header received. The TX power field is present only in
some extended advertising PDUs.
ble_gap_evt_adv_report_t::aux_pointer
The offset and PHY of the next advertising packet in this extended advertising set.
This field will only be set if is set to ble_gap_evt_adv_report_t::type::status BLE_GAP_ADV_DATA_STATUS_INC
.OMPLETE_MORE_DATA
ble_gap_evt_adv_report_t::set_id
Set ID of the received advertising data. This is only present in some extended advertising PDUs.
ble_gap_evt_adv_report_t::data_id
Data ID of the received advertising data. This is only present in some extended advertising PDUs.
Write to SoftDevice protected registers
A new API, sd_protected_register_write(), has been added to give the application the possibility to write to a register that is write-
protected by the SoftDevice. A write-protected peripheral shall only be accessed through the SoftDevice API when the SoftDevice is enabled.
The new API supports writing to the Block Protection ( ) peripheral.BPROT The application can use sd_protected_register_write() ins
tead of sd_flash_protect() to set the flash protection configuration registers.
Usage
/* Old API: */
errcode = sd_flash_protect(value0, value1, value2, value3)
/* New API: */
errcode = sd_protected_register_write(&(NRF_BPROT->CONFIG0), value0)
errcode = sd_protected_register_write(&(NRF_BPROT->CONFIG1), value1)
errcode = sd_protected_register_write(&(NRF_BPROT->CONFIG2), value2)
errcode = sd_protected_register_write(&(NRF_BPROT->CONFIG3), value3)
Required changes
Updated advertiser API
sd_ble_gap_adv_data_set() has been removed.
A new API, , has been added with the following functionalities:sd_ble_gap_adv_set_configure()
Configuring and updating the advertising parameters of an advertising set.
Setting, clearing, or updating advertising and scan response data.
Note: The a dvertising data must be kept alive in memory until advertising is terminated. Not doing so will lead to undefined behavior.
Note: Updating advertising data while advertising can only be done by providing new advertising data buffers.
Configuring and updating an advertising set
is a term introduced in Bluetooth Core Specification v5.0.
Advertising Set
Each advertising set is identified by an advertising handle. To configure a new advertising set and obtain a new advertising handle, sd_ble_
should be called with a pointer pointing to an advertising handle setgap_adv_set_configure() p_adv_handle to BLE_GAP_ADV_SET_
HANDLE_NOT_SET.
To update an existing advertising set, with a previously configured advertising sd_ble_gap_adv_set_configure() should be called
handle.
Note: Currently only one advertising set can be configured in the SoftDevice.
Configuring advertising parameters for an advertising set
Setting advertising parameters has been moved from to .sd_ble_gap_adv_start() sd_ble_gap_adv_set_configure()
has changed:The content of ble_gap_adv_params_t
ble_gap_adv_params_t::type has been removed.
A new parameter, of the new type properties, ble_gap_adv_properties_t has been added.
The advertising type must now be set through _ble_gap_adv_properties t::type.
.The advertising type definitions ( ) have changed, and new types have been addedBLE_GAP_ADV_TYPES The mapping
from old to new advertising types is shown below. These advertising types are referred to as advertising types:
legacy
type = BLE_GAP_ADV_TYPE_ADV_IND -> properties.type =
BLE_GAP_ADV_TYPE_CONNECTABLE_SCANNABLE_UNDIRECTED
BLE_GAP_ADV_TYPE_ADV_DIRECT_INDtype = -> properties.type =
BLE_GAP_ADV_TYPE_CONNECTABLE_NONSCANNABLE_DIRECTED_HIGH_DUTY_CYCLE or BLE_GAP_ADV_TYP
E_CONNECTABLE_NONSCANNABLE_DIRECTED
BLE_GAP_ADV_TYPE_ADV_SCAN_INDtype = -> properties.type = BLE_GAP_ADV_TYPE_NONCONN
ECTABLE_SCANNABLE_UNDIRECTED
BLE_GAP_ADV_TYPE_ADV_NONCONN_INDtype = -> properties.type =
BLE_GAP_ADV_TYPE_NONCONNECTABLE_NONSCANNABLE_UNDIRECTED
fpble_gap_adv_params_t:: has been renamed .filter_policyble_gap_adv_params_t::
has been renamed timeoutble_gap_adv_params_t:: ble_gap_adv_params_t::duration and is now measured in 10 ms
.units
ble_gap_adv_params_t::channel_mask type has been changed from to the new type ble_gap_adv_ch_mask_t ble_gap_
.ch_mask_t
Note: At least one of the primary channels that is channel index 37-39 must be set to 0.
Note: Masking away secondary channels is currently not supported.
The mapping from old type ble_gap_adv_ch_mask_t to the new type ble_gap_ch_mask_t is shown below:
channel_mask.ch_37_off = 1 -> = 0x2000000000channel_mask
channel_mask.ch_38_off = 1 -> = 0x4000000000channel_mask
channel_mask.ch_39_off = 1 -> = 0x8000000000channel_mask
has several new parameters:ble_gap_adv_params_t
has been added to allow the application to advertise for a given number of advertising events.max_adv_evts
scan_req_notification flag has been added to give the application the possibility to receive events of type ble_gap_e
. This replaces vt_scan_req_report_t BLE_GAP_OPT_SCAN_REQ_REPORT.
and allow the application to select PHYs primary_phy secondary_phy for primary and secondary advertising channels.
should be set to or for legacy advertising types. primary_phy BLE_GAP_PHY_AUTO BLE_GAP_PHY_1MBPS For
it should be set to or extended advertising types, BLE_GAP_PHY_1MBPS BLE_GAP_PHY_CODED if supported by the
.SoftDevice
can be ignored for legacy advertising. For extended advertising types, it should be set to secondary_phy BLE_GA
or .P_PHY_1MBPS, BLE_GAP_PHY_2MBPS, BLE_GAP_PHY_CODED if supported by the SoftDevice
has been added to allow the application to choose the set ID of an extended advertiserset_id .
Other Advertising API changes
BLE_GAP_TIMEOUT_SRC_ADVERTISING has been removed.
A new event, structure BLE_GAP_EVT_ADVERTISING_SET_TERMINATED with ble_gap_evt_adv_set_terminated_t,
has been introduced to let the application know when and why an advertising set has terminated.
A new configuration parameter, ,ble_gap_cfg_role_count_t::adv_set_count has been introduced to set the maximum
number of advertising sets. Note: The maximum number of advertising sets is supported .BLE_GAP_ADV_SET_COUNT_MAX
BLE_GAP_ADV_MAX_SIZE has been replaced with BLE_GAP_ADV_SET_DATA_SIZE_MAX.
now includesble_gap_evt_connected_t and adv_handle adv_data of the new type ble_gap_adv_data_t These are .
set when the device connects as a peripheral.
now includes .ble_gap_evt_scan_req_report_t adv_handle
has been removed.BLE_GAP_OPT_SCAN_REQ_REPORT
has been changed from 180 to 18000 as is BLE_GAP_ADV_TIMEOUT_LIMITED_MAX sd_ble_gap_adv_params_t::duration
now measured in 10 ms units.
Usage
static uint8_t raw_adv_data_buffer1[BLE_GAP_ADV_SET_DATA_SIZE_MAX];
