| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Connection Parameters Negotiation
This information applies to the following SoftDevices: S130, S132, S332

Module for initiating and executing a connection parameters negotiation procedure.

Most use cases require what is referred to as Fast Connection Parameters as soon as a connection is established in order to ensure that service discovery and connection procedures happen quickly. However, continuing with these parameters through out the connection may be unnecessary drain of battery since many applications require a less frequent data exchange. Therefore, it is recommended that the peripheral applications request the master to update connection parameters. The Connection parameters negotiation library of the SDK provides the functionality to do so.

# Overview

On initialization, the library can be provided with the desired connection parameters to be used for the link along with when the negotiation of connection parameters should start, how many times negotiation is to be attempted and what action to take if action if negotiation fails.

# Initialization and Set-up

The library must be set up for negotiating the connection parameters on the link. This is done by calling the ble_conn_params_init API. The application should indicate when the first connection parameter request should be sent to the peer, how many times the library should attempt negotiating the parameters and what should be the time interval between each attempt. The application can also indicate if the library should initiate disconnection in case connection parameters could not be negotiated as desired by the application. Additionally, application can register with the library to be notified of events and errors.

#define FIRST_CONN_PARAMS_UPDATE_DELAY 5000 // 5 seconds delay before negotiation is initiated.
#define NEXT_CONN_PARAMS_UPDATE_DELAY 30000 // 30 seconds delay for subsequent request to be sent in case parameters are not updated as requested.
#define MAX_CONN_PARAMS_UPDATE_COUNT 3 // Number of times negotiation is attempted.
#define MIN_CONN_INTERVAL MSEC_TO_UNITS(7.5, UNIT_1_25_MS) // Minimum connection interval (7.5 ms).
#define MAX_CONN_INTERVAL MSEC_TO_UNITS(30, UNIT_1_25_MS) // Maximum connection interval (30 ms).
#define SLAVE_LATENCY 6 // Slave latency.
#define CONN_SUP_TIMEOUT MSEC_TO_UNITS(300, UNIT_10_MS) // Connection supervisory timeout (300 ms).
.
.
.
ble_conn_params_init_t cnxn_param_init;
ble_gap_conn_params_t preferred_cnxn_param;
uint32_t retval;
memset(&cp_init, 0, sizeof(ble_conn_params_init_t));
// Connection parameters preferred by the application.
preferred_cnxn_param.min_conn_interval = MIN_CONN_INTERVAL;
preferred_cnxn_param.max_conn_interval = MAX_CONN_INTERVAL;
preferred_cnxn_param.slave_latency = SLAVE_LATENCY;
preferred_cnxn_param.conn_sup_timeout = CONN_SUP_TIMEOUT;
cnxn_param_init.p_conn_params = &preferred_cnxn_param;
cnxn_param_init.first_conn_params_update_delay = FIRST_CONN_PARAMS_UPDATE_DELAY;
cnxn_param_init.next_conn_params_update_delay = NEXT_CONN_PARAMS_UPDATE_DELAY;
cnxn_param_init.max_conn_params_update_count = MAX_CONN_PARAMS_UPDATE_COUNT;
cnxn_param_init.start_on_notify_cccd_handle = BLE_GATT_HANDLE_INVALID;
cnxn_param_init.disconnect_on_fail = false;
cnxn_param_init.evt_handler = conn_params_event_handler;
cnxn_param_init.error_handler = conn_params_error_handler;
// Initialize and set-up connection parameter negotiation module.
retval = ble_conn_params_init(&cp_init);
if(retval == NRF_SUCCESS)
{
// Procedure request succeeded. Connection parameters will be negotiated as requested.
// BLE_CONN_PARAMS_EVT_SUCCEEDED or BLE_CONN_PARAMS_EVT_FAILED
// will be notified if parameter negotiation is successful or not.
}
else
{
// Procedure request failed.
}

# Shutdown

This routine must be called when the application is disabling the SoftDevice or the application does not want the parameters to be negotiated any longer. This must be called to ensure the timers used by the library are not longer active.

uint32_t retval;
// Stop connection parameter update negotiation.
retval = ble_conn_params_stop();
if(retval == NRF_SUCCESS)
{
// Procedure successful!
}
else
{
// Procedure failed. Take recovery action.
}

# Change/Update Connection Parameters Negotiated

In case application needs to renegotiate the connection parameters, it can do so using the ble_conn_params_change_conn_params API. This API could be requested multiple times when in connection. This procedure should not be initiated if a negotiation is already ongoing.

#define MIN_CONN_INTERVAL MSEC_TO_UNITS(75, UNIT_1_25_MS) // Minimum connection interval (75 ms).
#define MAX_CONN_INTERVAL MSEC_TO_UNITS(300, UNIT_1_25_MS) // Maximum connection interval (300 ms).
#define SLAVE_LATENCY 6 // Slave latency.
#define CONN_SUP_TIMEOUT MSEC_TO_UNITS(3000, UNIT_10_MS) // Connection supervisory time-out (3 s).
.
.
.
ble_gap_conn_params_t updated_cnxn_param;
uint32_t retval;
// Update in Connection parameters preferred by the application.
updated_cnxn_param.min_conn_interval = MIN_CONN_INTERVAL;
updated_cnxn_param.max_conn_interval = MAX_CONN_INTERVAL;
updated_cnxn_param.slave_latency = SLAVE_LATENCY;
updated_cnxn_param.conn_sup_timeout = CONN_SUP_TIMEOUT;
// Initialize and set-up connection parameter negotiation module.
retval = ble_conn_params_change_conn_params(&updated_cnxn_param);
if(retval == NRF_SUCCESS)
{
// Procedure request succeeded. Connection parameters will be negotiated as requested.
// BLE_CONN_PARAMS_EVT_SUCCEEDED will be notified if parameter negotiation is successful.
}
else
{
// Procedure request failed.
}