Functions

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_handle	Connection Handle.
[in]	local_cid	Local Channel ID of the L2CAP channel or BLE_L2CAP_CID_INVALID to set the value that will be used for newly created channels.
[in]	credits	Number 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_credits	NULL 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_SUCCESS	Flow control parameters accepted.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid State to perform operation (Setup or release is in progress for an L2CAP channel).
NRF_ERROR_NOT_FOUND	CID not found.

Release an L2CAP channel.

This sends a Disconnection Request packet to a peer.

Events generated

BLE_L2CAP_EVT_CH_RELEASED

Release complete.

Relevant Message Sequence Charts

L2CAP Channel Release

Parameters

[in]	conn_handle	Connection Handle.
[in]	local_cid	Local Channel ID of the L2CAP channel.

Return values

NRF_SUCCESS	Successfully queued request for transmission.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid State to perform operation (Setup or release is in progress for the L2CAP channel).
NRF_ERROR_NOT_FOUND	CID not found.

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_RX

The SDU is received.

Relevant Message Sequence Charts

L2CAP Channel SDU Receive

Parameters

[in]	conn_handle	Connection Handle.
[in]	local_cid	Local Channel ID of the L2CAP channel.
[in]	p_sdu_buf	Pointer to the SDU data buffer.

Return values

NRF_SUCCESS	Buffer accepted.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid State to perform operation (Setup or release is in progress for an L2CAP channel).
NRF_ERROR_NOT_FOUND	CID not found.
NRF_ERROR_RESOURCES	Too many SDU data buffers supplied. Wait for a BLE_L2CAP_EVT_CH_RX event and retry.

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_SETUP	Setup successful.
BLE_L2CAP_EVT_CH_SETUP_REFUSED	Setup failed.

Relevant Message Sequence Charts

L2CAP Channel Setup

Parameters

[in]	conn_handle	Connection Handle.
[in,out]	p_local_cid	Pointer to a uint16_t containing Local Channel ID of the L2CAP channel: As input: BLE_L2CAP_CID_INVALID when requesting setup of an L2CAP channel or local_cid provided in the BLE_L2CAP_EVT_CH_SETUP_REQUEST event when replying to a setup request of an L2CAP channel. As output: local_cid for this channel.
[in]	p_params	L2CAP channel parameters.

Return values

NRF_SUCCESS	Successfully queued request or response for transmission.
NRF_ERROR_BUSY	The stack is busy, process pending events and retry.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
NRF_ERROR_INVALID_LENGTH	Supplied higher rx_mps than has been configured on this link.
NRF_ERROR_INVALID_STATE	Invalid State to perform operation (L2CAP channel already set up).
NRF_ERROR_NOT_FOUND	CID not found.
NRF_ERROR_RESOURCES	The limit has been reached for available L2CAP channels, see ble_l2cap_conn_cfg_t::ch_count .

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_TX

The SDU is transmitted.

Relevant Message Sequence Charts

L2CAP Channel SDU Transmit

Parameters

[in]	conn_handle	Connection Handle.
[in]	local_cid	Local Channel ID of the L2CAP channel.
[in]	p_sdu_buf	Pointer to the SDU data buffer.

Return values

NRF_SUCCESS	Successfully queued L2CAP SDU for transmission.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid State to perform operation (Setup or release is in progress for the L2CAP channel).
NRF_ERROR_NOT_FOUND	CID not found.
NRF_ERROR_DATA_SIZE	Invalid 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_RESOURCES	Too many SDUs queued for transmission. Wait for a BLE_L2CAP_EVT_CH_TX event and retry.