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.
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
l2cap_remove_event_handler
void l2cap_remove_event_handler(btstack_packet_callback_registration_t * callback_handler);
Remove event packet handler.
l2cap_max_mtu
uint16_t l2cap_max_mtu(void);
Get max MTU for Classic connections based on btstack configuration
Returns
- uint16_t
l2cap_max_le_mtu
uint16_t l2cap_max_le_mtu(void);
Get max MTU for LE connections based on btstack configuration
Returns
- uint16_t
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.
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
- packet_handler
- address
- psm
- mtu
- local_cid
Returns
- uint8_t: status
l2cap_disconnect
uint8_t l2cap_disconnect(uint16_t local_cid);
Disconnects L2CAP channel with given identifier.
Parameters
- local_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS if successful or L2CAP_LOCAL_CID_DOES_NOT_EXIST
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
- uint16_t
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
- local_cid
- enabled
Returns
- uint8_t: status
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
- local_cid
- data: to send
- len: of data
Returns
- uint8_t: status
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
- packet_handler
- psm
- mtu
- security_level
Returns
- uint8_t: status ERROR_CODE_SUCCESS if successful, otherwise L2CAP_SERVICE_ALREADY_REGISTERED or BTSTACK_MEMORY_ALLOC_FAILED
l2cap_unregister_service
uint8_t l2cap_unregister_service(uint16_t psm);
Unregisters L2CAP service with given PSM.
Returns
- uint8_t
l2cap_accept_connection
void l2cap_accept_connection(uint16_t local_cid);
Accepts incoming L2CAP connection.
l2cap_decline_connection
void l2cap_decline_connection(uint16_t local_cid);
Deny incoming L2CAP connection.
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
- bool: true if packet can be sent
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
- local_cid
Returns
- uint8_t: status
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
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
- uint8_t *
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
- uint8_t
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
//
// 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
- enabled
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
- packet_handler
- address
- psm
- ertm_config
- buffer: to store ERTM state, reassembled rx packet, out-of-order packets and unacknowledged outgoing packets
- size: of buffer
- local_cid
Returns
- uint8_t: status
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
- local_cid
- ertm_config
- buffer: to store ERTM state, reassembled rx packet, out-of-order packets and unacknowledged outgoing packets
- size: of buffer
Returns
- uint8_t: status
l2cap_ertm_decline_connection
uint8_t l2cap_ertm_decline_connection(uint16_t local_cid);
Deny incoming incoming L2CAP connection for Enhanced Retransmission Mode
Parameters
- local_cid
Returns
- uint8_t: status
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
- local_cid
Returns
- uint8_t: status
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
- local_cid
Returns
- uint8_t: status
//
// 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
- packet_handler
- psm
- security_level
Returns
- uint8_t
l2cap_cbm_unregister_service
uint8_t l2cap_cbm_unregister_service(uint16_t psm);
Unregister L2CAP service in LE Credit-Based Flow-Control Mode
Parameters
- psm
Returns
- uint8_t
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
- psm /
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
- uint8_t
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
- local_cid: L2CAP Channel Identifier
- result: result, see L2CAP_CBM_CONNECTION_RESULT_SUCCESS in bluetooth.h
Returns
- uint8_t
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
- packet_handler: Packet handler for this connection
- con_handle: HCI Connection Handle, LE transport
- psm: Service PSM to connect to
- 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
- security_level: Minimum required security level
- out_local_cid: L2CAP LE Channel Identifier is stored here
Returns
- uint8_t
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
- local_cid: L2CAP Channel Identifier
- credits: Number additional credits for peer
Returns
- uint8_t
l2cap_cbm_available_credits
uint16_t l2cap_cbm_available_credits(uint16_t local_cid);
Returns the number of credits provided by peer
Parameters
- local_cid
Returns
- uint16_t: number of credits
//
// 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
- packet_handler
- psm
- min_remote_mtu
- security_level
Returns
- uint8_t: status
l2cap_ecbm_unregister_service
uint8_t l2cap_ecbm_unregister_service(uint16_t psm);
Unregister L2CAP service in Enhanced Credit-Based Flow-Control Mode
Parameters
- psm
Returns
- uint8_t: status
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
- mps_min
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
- mps_max
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
- packet_handler: Packet handler for this connection
- con_handle: HCI Connection Handle
- security_level: Minimum required security level
- psm: Service PSM to connect to
- num_channels: number of channels to create
- initial_credits: Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits
- receive_buffer_size: buffer size equals MTU
- receive_buffers: Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU
- out_local_cids: Array of L2CAP Channel Identifiers is stored here on success
Returns
- uint8_t: status
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
- local_cid: from L2CAP_EVENT_INCOMING_DATA_CONNECTION
- num_channels
- initial_credits: Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits
- receive_buffer_size
- receive_buffers: Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU
- out_local_cids: Array of L2CAP Channel Identifiers is stored here on success
Returns
- uint8_t: status
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
- local_cid: from L2CAP_EVENT_INCOMING_DATA_CONNECTION
- result: See L2CAP_ECBM_CONNECTION_RESULT_ALL_SUCCESS in bluetooth.h
Returns
- uint8_t: status
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
- local_cid: L2CAP Channel Identifier
- credits: Number additional credits for peer
Returns
- uint8_t: status
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
- local_cid: L2CAP Channel Identifier
Returns
- uint8_t: status
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
- num_cids
- local_cids: array of local_cids to reconfigure
- receive_buffer_size: buffer size equals MTU
- receive_buffers: Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU
Returns
- uint8_t: status
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
- con_handle
l2cap_ecbm_available_credits
uint16_t l2cap_ecbm_available_credits(uint16_t local_cid);
Returns the number of outgoing credits provided by peer
Parameters
- local_cid
Returns
- uint16_t: number of credits
l2cap_deinit
void l2cap_deinit(void);
De-Init L2CAP