Logical Link Control and Adaptation Protocol (L2CAP)

L2CAP layer enables connection-oriented channels which can be enable with the configuration option: CONFIG_BT_L2CAP_DYNAMIC_CHANNEL. This channels support segmentation and reassembly transparently, they also support credit based flow control making it suitable for data streams.

Channels instances are represented by the bt_l2cap_chan struct which contains the callbacks in the bt_l2cap_chan_ops struct to inform when the channel has been connected, disconnected or when the encryption has changed. In addition to that it also contains the recv callback which is called whenever an incoming data has been received. Data received this way can be marked as processed by returning 0 or using bt_l2cap_chan_recv_complete() API if processing is asynchronous.

Note

The recv callback is called directly from RX Thread thus it is not recommended to block for long periods of time.

For sending data the bt_l2cap_chan_send() API can be used noting that it may block if no credits are available, and resuming as soon as more credits are available.

Servers can be registered using bt_l2cap_server_register() API passing the bt_l2cap_server struct which informs what psm it should listen to, the required security level sec_level, and the callback accept which is called to authorize incoming connection requests and allocate channel instances.

Client channels can be initiated with use of bt_l2cap_chan_connect() API and can be disconnected with the bt_l2cap_chan_disconnect() API. Note that the later can also disconnect channel instances created by servers.

API Reference

group bt_l2cap

L2CAP.

Defines

BT_L2CAP_HDR_SIZE

BT_L2CAP_BUF_SIZE(mtu)

Helper to calculate needed outgoing buffer size, useful e.g. for creating buffer pools.

Return

Needed buffer size to match the requested L2CAP MTU.

Parameters

• mtu: Needed L2CAP MTU.

BT_L2CAP_LE_CHAN(_ch)

Helper macro getting container object of type bt_l2cap_le_chan address having the same container chan member address as object in question.

Return

Address of in memory bt_l2cap_le_chan object type containing the address of in question object.

Parameters

• _ch: Address of object of bt_l2cap_chan type

BT_L2CAP_CHAN_SEND_RESERVE

Headroom needed for outgoing buffers.

Typedefs

typedef bt_l2cap_chan_destroy_t

Channel destroy callback.

Parameters

• chan: Channel object.

typedef enum bt_l2cap_chan_state bt_l2cap_chan_state_t

Life-span states of L2CAP CoC channel. Used only by internal APIs dealing with setting channel to proper state depending on operational context.

typedef enum bt_l2cap_chan_status bt_l2cap_chan_status_t

Status of L2CAP channel.

Enums

enum bt_l2cap_chan_state

Life-span states of L2CAP CoC channel. Used only by internal APIs dealing with setting channel to proper state depending on operational context.

Values:

BT_L2CAP_DISCONNECTED

Channel disconnected

BT_L2CAP_CONNECT

Channel in connecting state

BT_L2CAP_CONFIG

Channel in config state, BR/EDR specific

BT_L2CAP_CONNECTED

Channel ready for upper layer traffic on it

BT_L2CAP_DISCONNECT

Channel in disconnecting state

enum bt_l2cap_chan_status

Status of L2CAP channel.

Values:

BT_L2CAP_STATUS_OUT

Channel output status

BT_L2CAP_STATUS_SHUTDOWN

Channel shutdown status

   Once this status is notified it means the channel will no longer be
   able to transmit or receive data.

BT_L2CAP_NUM_STATUS

Functions

int bt_l2cap_server_register(struct bt_l2cap_server *server)

Register L2CAP server.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel structure to be used by the new connection.

For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should be assigned to server->psm before calling this API. For dynamic PSMs (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value (this is however not recommended) or be left as 0, in which case upon return a newly allocated value will have been assigned to it. For dynamically allocated values the expectation is that it’s exposed through a GATT service, and that’s how L2CAP clients discover how to connect to the server.

Return

0 in case of success or negative value in case of error.

Parameters

• server: Server structure.

int bt_l2cap_br_server_register(struct bt_l2cap_server *server)

Register L2CAP server on BR/EDR oriented connection.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel structure to be used by the new connection.

Return

0 in case of success or negative value in case of error.

Parameters

• server: Server structure.

int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan, u16_t psm)

Connect L2CAP channel.

Connect L2CAP channel by PSM, once the connection is completed channel connected() callback will be called. If the connection is rejected disconnected() callback is called instead. Channel object passed (over an address of it) as second parameter shouldn’t be instantiated in application as standalone. Instead of, application should create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API the location (address) of bt_l2cap_chan type object which is a member of both transport dedicated objects.

Return

0 in case of success or negative value in case of error.

Parameters

• conn: Connection object.

• chan: Channel object.

• psm: Channel PSM to connect to.

int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan)

Disconnect L2CAP channel.

Disconnect L2CAP channel, if the connection is pending it will be canceled and as a result the channel disconnected() callback is called. Regarding to input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Return

0 in case of success or negative value in case of error.

Parameters

• chan: Channel object.

int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf)

Send data to L2CAP channel.

Send data from buffer to the channel. If credits are not available, buf will be queued and sent as and when credits are received from peer. Regarding to first input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Return

Bytes sent in case of success or negative value in case of error.

int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan, struct net_buf *buf)

Complete receiving L2CAP channel data.

Complete the reception of incoming data. This shall only be called if the channel recv callback has returned -EINPROGRESS to process some incoming data. The buffer shall contain the original user_data as that is used for storing the credits/segments used by the packet.

Return

0 in case of success or negative value in case of error.

Parameters

• chan: Channel object.

• buf: Buffer containing the data.

struct bt_l2cap_chan

#include <l2cap.h>

L2CAP Channel structure.

struct bt_l2cap_le_endpoint

#include <l2cap.h>

LE L2CAP Endpoint structure.

struct bt_l2cap_le_chan

#include <l2cap.h>

LE L2CAP Channel structure.

struct bt_l2cap_br_endpoint

#include <l2cap.h>

BREDR L2CAP Endpoint structure.

struct bt_l2cap_br_chan

#include <l2cap.h>

BREDR L2CAP Channel structure.

struct bt_l2cap_chan_ops

#include <l2cap.h>

L2CAP Channel operations structure.

struct bt_l2cap_server

#include <l2cap.h>

L2CAP Server structure.