 |
Cypress PSoC 6 Bluetooth Low Energy Middleware Library 3.60
|
|
Cypress PSoC 6 Bluetooth Low Energy Middleware Library 3.60
|
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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_psm_info_t' |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_psm_info_t' param->creditLwm : ignored |
| 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. |
| 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:
Refer to Bluetooth 5.0 core specification, Volume 3, Part A, section 4.22 for more details about this operation.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_conn_req_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_conn_resp_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_credit_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_tx_data_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_cbfc_disconn_req_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_gap_conn_update_param_info_t'. |
| 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.
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_conn_update_param_rsp_info_t'. |
| 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. |
| 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.
| param | Parameter is of type 'cy_stc_ble_l2cap_queue_flow_control_info_t'. Min HighWater mark: 1 Max HighWater mark: L2CAP queue depth Min LowWater mark: 0 Max LowWater mark: (HighWaterMark -1) |
Default values set by BLE Stack for better throughput are: LowWaterMark = 3, HighWaterMark = (L2CAP queue depth - 1).
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. |