L2CAP Functions

group group_ble_common_api_l2cap_functions

The L2CAP APIs allow access to the Logical link control and adaptation protocol (L2CAP) layer of the BLE Stack.

The L2CAP API names begin with Cy_BLE_L2CAP.

Functions

cy_en_ble_api_result_t Cy_BLE_L2CAP_CbfcRegisterPsm(cy_stc_ble_l2cap_cbfc_psm_info_t *param)

This function is used in L2CAP LE Credit Based Flow Control mode.

This function registers a new PSM with L2CAP module. This is a blocking function. No event is generated on calling this function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 3.4 for more details about Credit based flow control mode of operation. Refer to Bluetooth core specification, Volume 3, Part A, section 4.22 for more details about LE PSM.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

Input param is NULL or 'l2capPsm' is 0.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

Cannot register more than one PSM.

CY_BLE_ERROR_L2CAP_PSM_NOT_IN_RANGE

The PSM is not in range of 0x0001 - 0x00FF.

CY_BLE_ERROR_L2CAP_PSM_ALREADY_REGISTERED

PSM already Registered.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_CbfcUnregisterPsm(cy_stc_ble_l2cap_cbfc_psm_info_t *param)

This function de-registers previously registered PSM from the L2CAP for the L2CAP Credit Based Flow Control mode.

This is a blocking function. No event is generated on calling this function.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL for input parameter.

CY_BLE_ERROR_INVALID_OPERATION

Active CID is present with given PSM.

CY_BLE_ERROR_L2CAP_PSM_NOT_REGISTERED

PSM is not registered.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_CbfcConnectReq(cy_stc_ble_l2cap_cbfc_conn_req_info_t *param)

This function is used to send LE Credit Based Connection Request packet to create and configure an L2CAP CBFC channel between two devices.

This request is sent to the specified peer Bluetooth device, with specific peer PSM. This is a non-blocking function. Calling this function triggers CY_BLE_EVT_L2CAP_CBFC_CONN_IND event at receiver’s end if the receiver is a PSoC 6 device. Following events are generated at the sender’s end:

  • CY_BLE_EVT_L2CAP_CBFC_CONN_CNF - Generated when the receiver responds to the request. The response field in the event parameter returned along with this event indicates the status of the request; if the response is CY_BLE_L2CAP_CONNECTION_SUCCESSFUL, it indicates that the L2CAP channel was successfully created.

  • CY_BLE_EVT_L2CAP_COMMAND_REJ- Generated when the receiver rejects the connection request.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.22 for more details about this operation.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If "param" is NULL.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

Insufficient resources.

CY_BLE_ERROR_NO_DEVICE_ENTITY

'bdHandle' does not represent known device entity.

CY_BLE_ERROR_L2CAP_PSM_NOT_REGISTERED

PSM not Registered.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_CbfcConnectRsp(cy_stc_ble_l2cap_cbfc_conn_resp_info_t *param)

This function should be called by the application to send the LE Credit Based Connection Response packet to the peer Bluetooth device.

Application should call this function on receiving the L2CAP CBFC connection request indication through the CY_BLE_EVT_L2CAP_CBFC_CONN_IND event. This is a non-blocking function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.23 for more details about this operation.

If the application has set param->response as CY_BLE_L2CAP_CONNECTION_SUCCESSFUL and the return value is CY_BLE_SUCCESS, L2CAP CBFC Channel creation is successful.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If "param" is NULL.

CY_BLE_ERROR_L2CAP_CONNECTION_ENTITY_NOT_FOUND

Connection entity is not found.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_CbfcSendFlowControlCredit(cy_stc_ble_l2cap_cbfc_credit_info_t *param)

This function enables an application to send a LE Flow Control Credit packet to the peer Bluetooth device when it is capable of receiving additional LE-frames.

This is a non-blocking function.

This function is invoked when the device is expecting more data from the peer device. If the application gets CY_BLE_EVT_L2CAP_CBFC_RX_CREDIT_IND event, it indicates that the peer device is low on Credits to send more data. The application can send more Credits to the peer device by calling this function.

When a peer PSoC 6 MCU receives this packet, it generates the CY_BLE_EVT_L2CAP_CBFC_TX_CREDIT_IND event to indicate that the receiver can send more LE-frames event. It is the responsibility of the application layer of the device sending the Credit to keep track of the total number of Credits and ensure that it does not exceed 65535.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.24 for more details about this operation.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_L2CAP_CONNECTION_ENTITY_NOT_FOUND

L2CAP connection instance is not present.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

Insufficient resources.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_ChannelDataWrite(cy_stc_ble_l2cap_cbfc_tx_data_info_t *param)

This function is used to send a data packet on the L2CAP CBFC channel.

This is a blocking function. This function should be used after successful creation of L2CAP CBFC channel.

This function generates a ‘CY_BLE_EVT_L2CAP_CBFC_DATA_WRITE_IND’ event that is kept for backward compatibility with previous Cypress’ applications and the user should handle cy_en_ble_api_result_t to determine whether the last data packet was sent properly.

If the peer device is PSoC6 device, the CY_BLE_EVT_L2CAP_CBFC_DATA_READ event is used to inform the application about the data received over the L2CAP CBFC channel.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 3.4 for more details about this operation.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If 'param' or 'buffer' is NULL.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_NO_CONNECTION

No Link Layer connection is present.

CY_BLE_ERROR_L2CAP_CONNECTION_ENTITY_NOT_FOUND

No L2CAP CBFC channel found corresponding to CID.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_DisconnectReq(cy_stc_ble_l2cap_cbfc_disconn_req_info_t *param)

This function is used to send L2CAP Disconnect Request packet to terminate the specified L2CAP CBFC channel on a peer device.

This is a non-blocking function. Upon calling this function from local device, CY_BLE_EVT_L2CAP_CBFC_DISCONN_IND event is generated on the peer side if the peer is a PSoC 6 device.

Disconnection of the L2CAP CBFC channel always succeeds - either by reception of the L2CAP Disconnect Response from the peer, or by timeout. In either case, L2CAP will confirm disconnection of the channel by generating the CY_BLE_EVT_L2CAP_CBFC_DISCONN_CNF event.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.6 for more details about this operation.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_OPERATION

No Link Layer connection is present.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_L2CAP_CONNECTION_ENTITY_NOT_FOUND

No connection entity found that can be disconnected.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

Insufficient resources.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_LeConnectionParamUpdateRequest(cy_stc_ble_gap_conn_update_param_info_t *param)

This function enables an application to send Connection Parameter Update Request packet.

This function should be used only in LE Peripheral role. This function is used to request the peer Central device to update the connection parameters.

This is a non-blocking function. If the peer Central device is PSoC6 device, then this function results in a CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_REQ event at the Peer’s end.

If peer Central device accepts and sends Connection Parameter Update Response, then CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_RSP event is generated at Peripheral side.

To update the connection parameters from the Central side use the Cy_BLE_GAPC_ConnectionParamUpdateRequest() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.20 for more details about this operation.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If "connParam" is NULL.

CY_BLE_ERROR_INVALID_OPERATION

Connection Parameter Update Request is not allowed.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_NO_CONNECTION

No Link Layer connection is present.

CY_BLE_ERROR_NO_DEVICE_ENTITY

'bdHandle' does not represent a known device entity.

Note: Please refer the function documentation of Cy_BLE_GAPC_InitConnection() for recommended Connection Interval values.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_LeConnectionParamUpdateResponse(cy_stc_ble_l2cap_conn_update_param_rsp_info_t *param)

This function is used to send Connection Parameter Update Response packet.

This function should be used in LE Central role. Application should call this function on receiving the Connection Parameter Update Request through CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_REQ event. This is a non-blocking function.

If the peer Peripheral device is PSoC6 device, this function results in CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_RSP event at the Peripheral side.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If 'result' is invalid (greater than connection parameter reject code i.e., 0x0001).

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_NO_CONNECTION

No Link Layer connection is present.

CY_BLE_ERROR_NO_DEVICE_ENTITY

'bdHandle' does not represent known device entity.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Parameters

cy_en_ble_api_result_t Cy_BLE_L2CAP_SetFlowControlLimits(cy_stc_ble_l2cap_queue_flow_control_info_t *param)

This function allows the application to set L2CAP flow control limits using high and low water marking for the L2CAP queue.

This function should be used one time after successful LE Connection with peer device.

HighWaterMark is used to configure the maximum number of L2CAP queue entries that can be used for the data (GATT, SMP, and L2CAP CBFC data) transmission.

During data transmission, when the number of available L2CAP queue entries reaches the low water mark level, Stack generates a CY_BLE_EVT_STACK_BUSY_STATUS event with status as busy, so that the application can stop queuing data and wait until Stack generates a CY_BLE_EVT_STACK_BUSY_STATUS event with free status.

Default values set by BLE Stack for better throughput are: LowWaterMark = 3, HighWaterMark = (L2CAP queue depth - 1).

Parameters

Note: If the LowWaterMark is set to less than 3, then do not initiate GATT data transmission while pairing procedure is going on.

For GATT data transmission, the difference between HighWaterMark and LowWaterMark must not be greater than number of GATT buffers provided during Stack-init to avoid receiving a memory allocation error for GATT transaction.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If 'param' is NULL or water mark levels are not proper.

CY_BLE_ERROR_NO_DEVICE_ENTITY

'bdHandle' does not represent known device entity.

Return

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.