Bluetooth® Classic L2CAP API

Overview

Bluetooth Classic L2CAP (Logical Link Control and Adaptation Layer Protocol) API provides functions for data transmission between Bluetooth devices. It supports both client and server roles, allowing the creation of L2CAP connections for reliable, high-throughput communication.

Application Examples

Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the following application:

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.

参数

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

返回

  • 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.

返回

  • 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.

返回

  • 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().

参数

  • 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.

返回

  • 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)

Create an L2CAP server and start listening for connection requests.

备注

  • 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() and before esp_bt_l2cap_deinit().

参数

  • cntl_flag -- [in] Lower 16-bit security settings mask.

  • local_psm -- [in] Dynamic PSM.

返回

  • 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().

返回

  • 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().

参数

local_psm -- [in] Dynamic PSM.

返回

  • 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. When the operation is completed, the callback function will be called with ESP_BT_L2CAP_VFS_REGISTER_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

返回

  • ESP_OK: success

  • other: failed

esp_err_t esp_bt_l2cap_vfs_unregister(void)

This function is used to unregister VFS. When the operation is completed, the callback function will be called with ESP_BT_L2CAP_VFS_UNREGISTER_EVT. This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().

返回

  • ESP_OK: success

  • other: failed

esp_err_t esp_bt_l2cap_get_protocol_status(esp_bt_l2cap_protocol_status_t *status)

This function is used to get the status of L2CAP.

参数

status -- [out] - l2cap status

返回

  • 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 esp_bt_l2cap_cb_param_t::l2cap_vfs_register_evt_param vfs_register

L2CAP callback param of ESP_BT_L2CAP_VFS_REGISTER_EVT

struct esp_bt_l2cap_cb_param_t::l2cap_vfs_unregister_evt_param vfs_unregister

L2CAP callback param of ESP_BT_L2CAP_VFS_UNREGISTER_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

uint16_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

struct l2cap_vfs_register_evt_param
#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_VFS_REGISTER_EVT.

Public Members

esp_bt_l2cap_status_t status

status

struct l2cap_vfs_unregister_evt_param
#include <esp_l2cap_bt_api.h>

ESP_BT_L2CAP_VFS_UNREGISTER_EVT.

Public Members

esp_bt_l2cap_status_t status

status

Structures

struct esp_bt_l2cap_protocol_status_t

L2CAP status parameters.

Public Members

bool l2cap_inited

l2cap initialization

uint8_t conn_num

Number of connections

Macros

ESP_BT_L2CAP_SEC_NONE

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

L2CAP control flags type

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

[in] Event type

Param param

[in] 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

enumerator ESP_BT_L2CAP_VFS_REGISTER_EVT

When L2CAP VFS register, the event comes

enumerator ESP_BT_L2CAP_VFS_UNREGISTER_EVT

When L2CAP VFS unregister, the event comes

提供有关此文档的反馈