# 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:

- This is a BT_L2CAP demo. This demo can connect, send and receive L2CAP data bluetooth/bluedroid/classic_bt/bt_l2cap_client, bluetooth/bluedroid/classic_bt/bt_l2cap_server

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

  Create an L2CAP server and start listening for connection requests.

  Note

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

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

  Returns:

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

  Returns:

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

  Parameters:

    status -- [out] - l2cap status

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

Provide feedback about this document