# Classic Bluetooth® L2CAP API

## Application Example

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)

  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:

  1. ESP_BT_L2CAP_SEC_NONE

  2. ESP_BT_L2CAP_SEC_AUTHENTICATE

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

Provide feedback about this document