Classic Bluetooth® L2CAP API

Application Examples

bluetooth/bluedroid/classic_bt/bt_l2cap_server demonstrates how to use Logical Link Control and Adaptation Layer Protocol (L2CAP) APIs to create an L2CAP server, and wait to be discovered and connected by a remote device L2CAP client.
bluetooth/bluedroid/classic_bt/bt_l2cap_client demonstrates how to use L2CAP APIs to create an L2CAP client.

API Reference

Header File

components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
This header file can be included with:
#include "esp_l2cap_bt_api.h"
This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:
REQUIRES bt
or
PRIV_REQUIRES bt

Functions

esp_err_t esp_bt_l2cap_register_callback(esp_bt_l2cap_cb_t callback)

This function is called to init callbacks with L2CAP module.

Parameters

callback -- [in] pointer to the init callback function.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_init(void)

This function is called to init L2CAP module. When the operation is completed, the callback function will be called with ESP_BT_L2CAP_INIT_EVT. This function should be called after esp_bluedroid_enable() completes successfully.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_deinit(void)

This function is called to uninit l2cap module. The operation will close all active L2CAP connection first, then the callback function will be called with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback function will be called with ESP_BT_L2CAP_UNINIT_EVT. This function should be called after esp_bt_l2cap_init() completes successfully.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_connect(esp_bt_l2cap_cntl_flags_t cntl_flag, uint16_t remote_psm, esp_bd_addr_t peer_bd_addr)

This function makes an L2CAP connection to a remote BD Address. When the connection is initiated or failed to initiate, the callback is called with ESP_BT_L2CAP_CL_INIT_EVT. When the connection is established or failed, the callback is called with ESP_BT_L2CAP_OPEN_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Parameters

cntl_flag -- [in] Lower 16-bit security settings mask.
remote_psm -- [in] Remote device bluetooth Profile PSM.
peer_bd_addr -- [in] Remote device bluetooth device address.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_start_srv(esp_bt_l2cap_cntl_flags_t cntl_flag, uint16_t local_psm)

This function create a L2CAP server and starts listening for an L2CAP connection request from a remote Bluetooth device. When the server is started successfully, the callback is called with ESP_BT_L2CAP_START_EVT. When the connection is established, the callback is called with ESP_BT_L2CAP_OPEN_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Parameters

cntl_flag -- [in] Lower 16-bit security settings mask.
local_psm -- [in] Dynamic PSM.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_stop_all_srv(void)

This function stops all L2CAP servers. The operation will close all active L2CAP connection first, then the callback function will be called with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback is called with ESP_BT_L2CAP_SRV_STOP_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_stop_srv(uint16_t local_psm)

This function stops a specific L2CAP server. The operation will close all active L2CAP connection first on the specific L2CAP server, then the callback function will be called with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback is called with ESP_BT_L2CAP_SRV_STOP_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Parameters

local_psm -- [in] Dynamic PSM.

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_vfs_register(void)

This function is used to register VFS. Only supports write, read and close. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Returns

ESP_OK: success
other: failed

esp_err_t esp_bt_l2cap_vfs_unregister(void)

This function is used to unregister VFS. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

Returns

ESP_OK: success
other: failed

Unions

union esp_bt_l2cap_cb_param_t

#include <esp_l2cap_bt_api.h>

L2CAP callback parameters union.

Public Members

struct esp_bt_l2cap_cb_param_t::l2cap_init_evt_param init: L2CAP callback param of ESP_BT_L2CAP_INIT_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_uninit_evt_param uninit: L2CAP callback param of ESP_BT_L2CAP_UNINIT_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_open_evt_param open: L2CAP callback param of ESP_BT_L2CAP_OPEN_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_close_evt_param close: L2CAP callback param of ESP_BT_L2CAP_CLOSE_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_start_evt_param start: L2CAP callback param of ESP_BT_L2CAP_START_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_cl_init_evt_param cl_init: L2CAP callback param of ESP_BT_L2CAP_CL_INIT_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_srv_stop_evt_param srv_stop: L2CAP callback param of ESP_BT_L2CAP_SRV_STOP_EVT

struct l2cap_cl_init_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_CL_INIT_EVT.

Public Members

esp_bt_l2cap_status_t status: status

uint32_t handle: The connection handle

uint8_t sec_id: security ID used by this server

struct l2cap_close_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_CLOSE_EVT.

Public Members

esp_bt_l2cap_status_t status: status

uint32_t handle: The connection handle

bool async: FALSE, if local initiates disconnect

struct l2cap_init_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_INIT_EVT.

Public Members

esp_bt_l2cap_status_t status: status

struct l2cap_open_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_OPEN_EVT.

Public Members

esp_bt_l2cap_status_t status: status

uint32_t handle: The connection handle

int fd: File descriptor

esp_bd_addr_t rem_bda: The peer address

int32_t tx_mtu: The transmit MTU

struct l2cap_srv_stop_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_SRV_STOP_EVT.

Public Members

esp_bt_l2cap_status_t status: status

uint8_t psm: local psm

struct l2cap_start_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_START_EVT.

Public Members

esp_bt_l2cap_status_t status: status

uint32_t handle: The connection handle

uint8_t sec_id: security ID used by this server

struct l2cap_uninit_evt_param

#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_UNINIT_EVT.

Public Members

esp_bt_l2cap_status_t status: status

Macros

ESP_BT_L2CAP_SEC_NONE

Security Setting Mask. Use these three mask mode:

ESP_BT_L2CAP_SEC_NONE
ESP_BT_L2CAP_SEC_AUTHENTICATE
(ESP_BT_L2CAP_SEC_ENCRYPT|ESP_BT_L2CAP_SEC_AUTHENTICATE) No security

ESP_BT_L2CAP_SEC_AUTHORIZE: Authorization required

ESP_BT_L2CAP_SEC_AUTHENTICATE: Authentication required

ESP_BT_L2CAP_SEC_ENCRYPT: Encryption required

Type Definitions

typedef uint32_t esp_bt_l2cap_cntl_flags_t

typedef void (*esp_bt_l2cap_cb_t)(esp_bt_l2cap_cb_event_t event, esp_bt_l2cap_cb_param_t *param)

L2CAP callback function type.

Param event: Event type
Param param: Point to callback parameter, currently is union type

Enumerations

enum esp_bt_l2cap_status_t

L2CAP operation success and failure codes.

Values:

enumerator ESP_BT_L2CAP_SUCCESS: Successful operation.

enumerator ESP_BT_L2CAP_FAILURE: Generic failure.

enumerator ESP_BT_L2CAP_BUSY: Temporarily can not handle this request.

enumerator ESP_BT_L2CAP_NO_RESOURCE: No more resource

enumerator ESP_BT_L2CAP_NEED_INIT: L2CAP module shall init first

enumerator ESP_BT_L2CAP_NEED_DEINIT: L2CAP module shall deinit first

enumerator ESP_BT_L2CAP_NO_CONNECTION: Connection may have been closed

enumerator ESP_BT_L2CAP_NO_SERVER: No server

enum esp_bt_l2cap_cb_event_t

L2CAP callback function events.

Values:

enumerator ESP_BT_L2CAP_INIT_EVT: When L2CAP is initialized, the event comes

enumerator ESP_BT_L2CAP_UNINIT_EVT: When L2CAP is deinitialized, the event comes

enumerator ESP_BT_L2CAP_OPEN_EVT: When L2CAP Client connection open, the event comes

enumerator ESP_BT_L2CAP_CLOSE_EVT: When L2CAP connection closed, the event comes

enumerator ESP_BT_L2CAP_START_EVT: When L2CAP server started, the event comes

enumerator ESP_BT_L2CAP_CL_INIT_EVT: When L2CAP client initiated a connection, the event comes

enumerator ESP_BT_L2CAP_SRV_STOP_EVT: When L2CAP server stopped, the event comes

Was this page helpful?

Thank you! We received your feedback.
If you have any comments, fill in Espressif Documentation Feedback Form.

We value your feedback.
Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.