L2CAP API

#include "src/l2cap.h"

Logical Link Control and Adaption Protocol

//
// PSM numbers from https://www.bluetooth.com/specifications/assigned-numbers/logical-link-control 
//
#define PSM_SDP           BLUETOOTH_PROTOCOL_SDP
#define PSM_RFCOMM        BLUETOOTH_PROTOCOL_RFCOMM
#define PSM_BNEP          BLUETOOTH_PROTOCOL_BNEP
// @TODO: scrape PSMs Bluetooth SIG site and put in bluetooth_psm.h or bluetooth_l2cap.h
#define PSM_HID_CONTROL   0x11
#define PSM_HID_INTERRUPT 0x13
#define PSM_ATT           0x1f
#define PSM_IPSP          0x23

l2cap_init

void l2cap_init(void);

Set up L2CAP and register L2CAP with HCI layer.

Source


l2cap_add_event_handler

void l2cap_add_event_handler(btstack_packet_callback_registration_t * callback_handler);

Add event packet handler for LE Connection Parameter Update events

Source


l2cap_remove_event_handler

void l2cap_remove_event_handler(btstack_packet_callback_registration_t * callback_handler);

Remove event packet handler.

Source


l2cap_max_mtu

uint16_t l2cap_max_mtu(void);

Get max MTU for Classic connections based on btstack configuration

Returns

Source


l2cap_max_le_mtu

uint16_t l2cap_max_le_mtu(void);

Get max MTU for LE connections based on btstack configuration

Returns

Source


l2cap_set_max_le_mtu

void l2cap_set_max_le_mtu(uint16_t max_mtu);

Set the max MTU for LE connections, if not set l2cap_max_mtu() will be used.

Source


l2cap_create_channel

uint8_t l2cap_create_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, uint16_t mtu, uint16_t * out_local_cid);

Creates L2CAP channel to the PSM of a remote device with baseband address. A new baseband connection will be initiated if necessary.

Parameters

Returns

Source


l2cap_disconnect

uint8_t l2cap_disconnect(uint16_t local_cid);

Disconnects L2CAP channel with given identifier.

Parameters

Returns

Source


l2cap_get_remote_mtu_for_local_cid

uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid);

Queries the maximal transfer unit (MTU) for L2CAP channel with given identifier.

Returns

Source


l2cap_set_automatically_flushable

uint8_t l2cap_set_automatically_flushable(uint16_t local_cid, bool enabled);

Configure whether packets sent on a Classic Basic Mode channel are automatically flushable.

Parameters

Returns

Source


l2cap_send

uint8_t l2cap_send(uint16_t local_cid, const uint8_t *data, uint16_t len);

Sends L2CAP data packet to the channel with given identifier.

Note: For channel in credit-based flow control mode, data needs to stay valid until .. event

Parameters

Returns

Source


l2cap_register_service

uint8_t l2cap_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu, gap_security_level_t security_level);

Registers L2CAP service with given PSM and MTU, and assigns a packet handler.

Parameters

Returns

Source


l2cap_unregister_service

uint8_t l2cap_unregister_service(uint16_t psm);

Unregisters L2CAP service with given PSM.

Returns

Source


l2cap_accept_connection

void l2cap_accept_connection(uint16_t local_cid);

Accepts incoming L2CAP connection.

Source


l2cap_decline_connection

void l2cap_decline_connection(uint16_t local_cid);

Deny incoming L2CAP connection.

Source


l2cap_can_send_packet_now

bool l2cap_can_send_packet_now(uint16_t local_cid);

Check if outgoing buffer is available and that there's space on the Bluetooth module

Returns

Source


l2cap_request_can_send_now_event

uint8_t l2cap_request_can_send_now_event(uint16_t local_cid);

Request emission of L2CAP_EVENT_CAN_SEND_NOW as soon as possible

Note: L2CAP_EVENT_CAN_SEND_NOW might be emitted during call to this function so packet handler should be ready to handle it

Parameters

Returns

Source


l2cap_reserve_packet_buffer

void l2cap_reserve_packet_buffer(void);

Reserve outgoing buffer

Note: Only for L2CAP Basic Mode Channels

Note: Must only be called after a 'can send now' check or event

Note: Asserts if packet buffer is already reserved

Source


l2cap_get_outgoing_buffer

uint8_t *l2cap_get_outgoing_buffer(void);

Get outgoing buffer and prepare data.

Note: Only for L2CAP Basic Mode Channels

Returns

Source


l2cap_send_prepared

uint8_t l2cap_send_prepared(uint16_t local_cid, uint16_t len);

Send L2CAP packet prepared in outgoing buffer to channel

Note: Only for L2CAP Basic Mode Channels

Returns

Source


l2cap_release_packet_buffer

void l2cap_release_packet_buffer(void);

Release outgoing buffer (only needed if l2cap_send_prepared is not called)

Note: Only for L2CAP Basic Mode Channels

Source


//
// Connection-Oriented Channels in Enhanced Retransmission Mode - ERTM
//

l2cap_ertm_enable

void l2cap_ertm_enable(bool enabled);

Enable or disable L2CAP Enhanced Retransmission Mode at runtime.

Note: ERTM is enabled by default if ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE is defined.

Parameters

Source


l2cap_ertm_create_channel

uint8_t l2cap_ertm_create_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm,
l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size, uint16_t * out_local_cid);

Creates L2CAP channel to the PSM of a remote device with baseband address using Enhanced Retransmission Mode. A new baseband connection will be initiated if necessary.

Parameters

Returns

Source


l2cap_ertm_accept_connection

uint8_t l2cap_ertm_accept_connection(uint16_t local_cid, l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size);

Accepts incoming L2CAP connection for Enhanced Retransmission Mode

Parameters

Returns

Source


l2cap_ertm_decline_connection

uint8_t l2cap_ertm_decline_connection(uint16_t local_cid);

Deny incoming incoming L2CAP connection for Enhanced Retransmission Mode

Parameters

Returns

Source


l2cap_ertm_set_busy

uint8_t l2cap_ertm_set_busy(uint16_t local_cid);

ERTM Set channel as busy.

Note: Can be cleared by l2cap_ertm_set_ready

Parameters

Returns

Source


l2cap_ertm_set_ready

uint8_t l2cap_ertm_set_ready(uint16_t local_cid);

ERTM Set channel as ready

Note: Used after l2cap_ertm_set_busy

Parameters

Returns

Source


//
// L2CAP Connection-Oriented Channels in LE Credit-Based Flow-Control Mode - CBM
//

l2cap_cbm_register_service

uint8_t l2cap_cbm_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, gap_security_level_t security_level);

Register L2CAP service in LE Credit-Based Flow-Control Mode

Note: MTU and initial credits are specified in l2cap_cbm_accept_connection(..) call

Parameters

Returns

Source


l2cap_cbm_unregister_service

uint8_t l2cap_cbm_unregister_service(uint16_t psm);

Unregister L2CAP service in LE Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_cbm_accept_connection

uint8_t l2cap_cbm_accept_connection(uint16_t local_cid, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits);

Unregister L2CAP service in LE Credit-Based Flow-Control Mode

Accept incoming connection LE Credit-Based Flow-Control Mode

Parameters

uint8_t: l2cap_cbm_unregister_service(uint16_t psm); /* - local_cid: L2CAP Channel Identifier - receive_buffer: buffer used for reassembly of L2CAP LE Information Frames into service data unit (SDU) with given MTU - receive_buffer_size: buffer size equals MTU - initial_credits: Number of initial credits provided to peer or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits

Returns

Source


l2cap_cbm_decline_connection

uint8_t l2cap_cbm_decline_connection(uint16_t local_cid, uint16_t result);

Deecline connection in LE Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_cbm_create_channel

uint8_t l2cap_cbm_create_channel(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle,
uint16_t psm, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits, gap_security_level_t security_level,
uint16_t * out_local_cid);

Create outgoing channel in LE Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_cbm_provide_credits

uint8_t l2cap_cbm_provide_credits(uint16_t local_cid, uint16_t credits);

Provide credits for channel in LE Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_cbm_available_credits

uint16_t l2cap_cbm_available_credits(uint16_t local_cid);

Returns the number of credits provided by peer

Parameters

Returns

Source


//
// L2CAP Connection-Oriented Channels in Enhanced Credit-Based Flow-Control Mode - ECBM
//

l2cap_ecbm_register_service

uint8_t l2cap_ecbm_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t min_remote_mtu,
gap_security_level_t security_level, bool authorization_required);

Register L2CAP service in Enhanced Credit-Based Flow-Control Mode

Note: MTU and initial credits are specified in l2cap_enhanced_accept_connection(..) call

@oaram: authorization_required

Parameters

Returns

Source


l2cap_ecbm_unregister_service

uint8_t l2cap_ecbm_unregister_service(uint16_t psm);

Unregister L2CAP service in Enhanced Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_ecbm_mps_set_min

void l2cap_ecbm_mps_set_min(uint16_t mps_min);

Set Minimal MPS for channel in Enhanced Credit-Based Flow-Control Mode

Parameters

Source


l2cap_ecbm_mps_set_max

void l2cap_ecbm_mps_set_max(uint16_t mps_max);

Set Minimal MPS for channel in Enhanced Credit-Based Flow-Control Mode

Parameters

Source


l2cap_ecbm_create_channels

uint8_t l2cap_ecbm_create_channels(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle,
gap_security_level_t security_level,
uint16_t psm, uint8_t num_channels, uint16_t initial_credits, uint16_t receive_buffer_size,
uint8_t ** receive_buffers, uint16_t * out_local_cids);

Create outgoing channel in Enhanced Credit-Based Flow-Control Mode

Note: receive_buffer points to an array of receive buffers with num_channels elements

Note: out_local_cid points to an array where CID is stored with num_channel elements

Parameters

Returns

Source


l2cap_ecbm_accept_channels

uint8_t l2cap_ecbm_accept_channels(uint16_t local_cid, uint8_t num_channels, uint16_t initial_credits,
uint16_t receive_buffer_size, uint8_t ** receive_buffers, uint16_t * out_local_cids);

Accept incoming connection Enhanced Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_ecbm_decline_channels

uint8_t l2cap_ecbm_decline_channels(uint16_t local_cid, uint16_t result);

Decline connection in Enhanced Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_ecbm_provide_credits

uint8_t l2cap_ecbm_provide_credits(uint16_t local_cid, uint16_t credits);

Provide credits for channel in Enhanced Credit-Based Flow-Control Mode

Parameters

Returns

Source


l2cap_ecbm_request_can_send_now_event

uint8_t l2cap_ecbm_request_can_send_now_event(uint16_t local_cid);

Request emission of L2CAP_EVENT_ECBM_CAN_SEND_NOW as soon as possible

Note: L2CAP_EVENT_ECBM_CAN_SEND_NOW might be emitted during call to this function so packet handler should be ready to handle it

Parameters

Returns

Source


l2cap_ecbm_reconfigure_channels

uint8_t l2cap_ecbm_reconfigure_channels(uint8_t num_cids, uint16_t * local_cids, uint16_t receive_buffer_size, uint8_t ** receive_buffers);

Reconfigure MPS/MTU of local channels

Parameters

Returns

Source


l2cap_ecbm_trigger_pending_connection_responses

void l2cap_ecbm_trigger_pending_connection_responses(hci_con_handle_t con_handle);

Trigger pending connection responses after pairing completed

Note: Must be called after receiving an SM_PAIRING_COMPLETE event, will be removed eventually

Parameters

Source


l2cap_ecbm_available_credits

uint16_t l2cap_ecbm_available_credits(uint16_t local_cid);

Returns the number of outgoing credits provided by peer

Parameters

Returns

Source


l2cap_deinit

void l2cap_deinit(void);

De-Init L2CAP

Source