S113 SoftDevice v7.2.0
Functions

Functions

uint32_t sd_ble_l2cap_ch_setup (uint16_t conn_handle, uint16_t *p_local_cid, ble_l2cap_ch_setup_params_t const *p_params)
 Set up an L2CAP channel. More...
 
uint32_t sd_ble_l2cap_ch_release (uint16_t conn_handle, uint16_t local_cid)
 Release an L2CAP channel. More...
 
uint32_t sd_ble_l2cap_ch_rx (uint16_t conn_handle, uint16_t local_cid, ble_data_t const *p_sdu_buf)
 Receive an SDU on an L2CAP channel. More...
 
uint32_t sd_ble_l2cap_ch_tx (uint16_t conn_handle, uint16_t local_cid, ble_data_t const *p_sdu_buf)
 Transmit an SDU on an L2CAP channel. More...
 
uint32_t sd_ble_l2cap_ch_flow_control (uint16_t conn_handle, uint16_t local_cid, uint16_t credits, uint16_t *p_credits)
 Advanced SDU reception flow control. More...
 

Detailed Description

Function Documentation

uint32_t sd_ble_l2cap_ch_flow_control ( uint16_t  conn_handle,
uint16_t  local_cid,
uint16_t  credits,
uint16_t *  p_credits 
)

Advanced SDU reception flow control.

Adjust the way the SoftDevice issues credits to the peer. This may issue additional credits to the peer using an LE Flow Control Credit packet.

Relevant Message Sequence Charts
L2CAP Channel advanced SDU reception flow control
Parameters
[in]conn_handleConnection Handle.
[in]local_cidLocal Channel ID of the L2CAP channel or BLE_L2CAP_CID_INVALID to set the value that will be used for newly created channels.
[in]creditsNumber of credits that the SoftDevice will make sure the peer has every time it starts using a new reception buffer.
  • BLE_L2CAP_CREDITS_DEFAULT is the default value the SoftDevice will use if this function is not called.
  • If set to zero, the SoftDevice will stop issuing credits for new reception buffers the application provides or has provided. SDU reception that is currently ongoing will be allowed to complete.
[out]p_creditsNULL or pointer to a uint16_t. If a valid pointer is provided, it will be written by the SoftDevice with the number of credits that is or will be available to the peer. If the value written by the SoftDevice is 0 when credits parameter was set to 0, the peer will not be able to send more data until more credits are provided by calling this function again with credits > 0. This parameter is ignored when local_cid is set to BLE_L2CAP_CID_INVALID.
Note
Application should take care when setting number of credits higher than default value. In this case the application must make sure that the SoftDevice always has reception buffers available (see sd_ble_l2cap_ch_rx) for that channel. If the SoftDevice does not have such buffers available, packets may be NACKed on the Link Layer and all Bluetooth traffic on the connection handle may be stalled until the SoftDevice again has an available reception buffer. This applies even if the application has used this call to set the credits back to default, or zero.
Return values
NRF_SUCCESSFlow control parameters accepted.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid State to perform operation (Setup or release is in progress for an L2CAP channel).
NRF_ERROR_NOT_FOUNDCID not found.
uint32_t sd_ble_l2cap_ch_release ( uint16_t  conn_handle,
uint16_t  local_cid 
)

Release an L2CAP channel.

This sends a Disconnection Request packet to a peer.

Events generated
BLE_L2CAP_EVT_CH_RELEASEDRelease complete.
Relevant Message Sequence Charts
L2CAP Channel Release
Parameters
[in]conn_handleConnection Handle.
[in]local_cidLocal Channel ID of the L2CAP channel.
Return values
NRF_SUCCESSSuccessfully queued request for transmission.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid State to perform operation (Setup or release is in progress for the L2CAP channel).
NRF_ERROR_NOT_FOUNDCID not found.
uint32_t sd_ble_l2cap_ch_rx ( uint16_t  conn_handle,
uint16_t  local_cid,
ble_data_t const *  p_sdu_buf 
)

Receive an SDU on an L2CAP channel.

This may issue additional credits to the peer using an LE Flow Control Credit packet.

Note
A call to this function will require the application to keep the memory pointed by ble_data_t::p_data alive until the SDU data buffer is returned in BLE_L2CAP_EVT_CH_RX or BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
The SoftDevice can queue up to ble_l2cap_conn_cfg_t::rx_queue_size SDU data buffers for reception per L2CAP channel.
Events generated
BLE_L2CAP_EVT_CH_RXThe SDU is received.
Relevant Message Sequence Charts
L2CAP Channel SDU Receive
Parameters
[in]conn_handleConnection Handle.
[in]local_cidLocal Channel ID of the L2CAP channel.
[in]p_sdu_bufPointer to the SDU data buffer.
Return values
NRF_SUCCESSBuffer accepted.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid State to perform operation (Setup or release is in progress for an L2CAP channel).
NRF_ERROR_NOT_FOUNDCID not found.
NRF_ERROR_RESOURCESToo many SDU data buffers supplied. Wait for a BLE_L2CAP_EVT_CH_RX event and retry.
uint32_t sd_ble_l2cap_ch_setup ( uint16_t  conn_handle,
uint16_t *  p_local_cid,
ble_l2cap_ch_setup_params_t const *  p_params 
)

Set up an L2CAP channel.

This function is used to:

  • Request setup of an L2CAP channel: sends an LE Credit Based Connection Request packet to a peer.
  • Reply to a setup request of an L2CAP channel (if called in response to a BLE_L2CAP_EVT_CH_SETUP_REQUEST event): sends an LE Credit Based Connection Response packet to a peer.
Note
A call to this function will require the application to keep the SDU data buffer alive until the SDU data buffer is returned in BLE_L2CAP_EVT_CH_RX or BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
Events generated
BLE_L2CAP_EVT_CH_SETUPSetup successful.
BLE_L2CAP_EVT_CH_SETUP_REFUSEDSetup failed.
Relevant Message Sequence Charts
L2CAP Channel Setup
Parameters
[in]conn_handleConnection Handle.
[in,out]p_local_cidPointer to a uint16_t containing Local Channel ID of the L2CAP channel:
[in]p_paramsL2CAP channel parameters.
Return values
NRF_SUCCESSSuccessfully queued request or response for transmission.
NRF_ERROR_BUSYThe stack is busy, process pending events and retry.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
NRF_ERROR_INVALID_LENGTHSupplied higher rx_mps than has been configured on this link.
NRF_ERROR_INVALID_STATEInvalid State to perform operation (L2CAP channel already set up).
NRF_ERROR_NOT_FOUNDCID not found.
NRF_ERROR_RESOURCESThe limit has been reached for available L2CAP channels, see ble_l2cap_conn_cfg_t::ch_count.
uint32_t sd_ble_l2cap_ch_tx ( uint16_t  conn_handle,
uint16_t  local_cid,
ble_data_t const *  p_sdu_buf 
)

Transmit an SDU on an L2CAP channel.

Note
A call to this function will require the application to keep the memory pointed by ble_data_t::p_data alive until the SDU data buffer is returned in BLE_L2CAP_EVT_CH_TX or BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
The SoftDevice can queue up to ble_l2cap_conn_cfg_t::tx_queue_size SDUs for transmission per L2CAP channel.
The application can keep track of the available credits for transmission by following the procedure below:
  • Store initial credits given by the peer in a variable. (Initial credits are provided in a BLE_L2CAP_EVT_CH_SETUP event.)
  • Decrement the variable, which stores the currently available credits, by ceiling((ble_data_t::len + 2) / tx_mps) when a call to this function returns NRF_SUCCESS. (tx_mps is provided in a BLE_L2CAP_EVT_CH_SETUP event.)
  • Increment the variable, which stores the currently available credits, by additional credits given by the peer in a BLE_L2CAP_EVT_CH_CREDIT event.
Events generated
BLE_L2CAP_EVT_CH_TXThe SDU is transmitted.
Relevant Message Sequence Charts
L2CAP Channel SDU Transmit
Parameters
[in]conn_handleConnection Handle.
[in]local_cidLocal Channel ID of the L2CAP channel.
[in]p_sdu_bufPointer to the SDU data buffer.
Return values
NRF_SUCCESSSuccessfully queued L2CAP SDU for transmission.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid State to perform operation (Setup or release is in progress for the L2CAP channel).
NRF_ERROR_NOT_FOUNDCID not found.
NRF_ERROR_DATA_SIZEInvalid SDU length supplied, must not be more than ble_l2cap_ch_tx_params_t::tx_mtu provided in BLE_L2CAP_EVT_CH_SETUP event.
NRF_ERROR_RESOURCESToo many SDUs queued for transmission. Wait for a BLE_L2CAP_EVT_CH_TX event and retry.

Documentation feedback | Developer Zone | Subscribe | Updated