BLE Connection Management

[中文]

Supported Socs

ESP32

ESP32-C2

ESP32-C3

ESP32-S3

The BLE connection management provides a simplified API interface for accessing the commonly used BLE functionality. It supports common scenarios like peripheral, central among others.

Application Example

esp_ble_conn_config_t config = {
    .device_name = CONFIG_EXAMPLE_BLE_ADV_NAME,
    .broadcast_data = CONFIG_EXAMPLE_BLE_SUB_ADV
};

ESP_ERROR_CHECK(esp_ble_conn_init(&config));
ESP_ERROR_CHECK(esp_ble_conn_start());

Examples

  1. BLE periodic advertiser example: bluetooth/ble_conn_mgr/ble_periodic_adv.

  2. BLE periodic sync example: bluetooth/ble_conn_mgr/ble_periodic_sync.

  3. BLE serial port profile example: bluetooth/ble_conn_mgr/ble_spp.

  4. BLE L2CAP CoC Central example: bluetooth/ble_l2cap_coc/l2cap_coc_central.

  5. BLE L2CAP CoC Peripheral example: bluetooth/ble_l2cap_coc/l2cap_coc_peripheral.

API Reference

Header File

Functions

esp_err_t esp_ble_conn_l2cap_coc_mem_init(void)

Initialize L2CAP CoC SDU memory pool.

Note

This API is thread-safe, but should be called from task context. Repeated calls are safe and return ESP_OK.

Returns

  • ESP_OK on success

  • ESP_ERR_TIMEOUT if lock acquisition times out

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_mem_release(void)

Release L2CAP CoC SDU memory pool.

Note

This API is thread-safe, but should be called from task context. It must only be called when there are no active L2CAP CoC servers or channels.

Returns

  • ESP_OK on success

  • ESP_ERR_TIMEOUT if lock acquisition times out

  • ESP_ERR_INVALID_STATE if active L2CAP CoC contexts exist

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_accept(uint16_t conn_handle, uint16_t peer_sdu_size, esp_ble_conn_l2cap_coc_chan_t chan)

Provide receive buffer for L2CAP CoC channel (accept or next SDU)

Parameters

  • conn_handle – [in] Connection handle

  • peer_sdu_size – [in] Peer SDU size from accept event

  • chan – [in] L2CAP CoC channel

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters

  • ESP_ERR_NO_MEM if memory pool not initialized or allocation failed

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_init(esp_ble_conn_config_t *config)

Initialization BLE connection management based on the configuration This function must be the first function to call, This call MUST have a corresponding call to esp_ble_conn_deinit when the operation is complete.

Parameters

config – [in] The configurations, see esp_ble_conn_config_t.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

  • ESP_FAIL on error

esp_err_t esp_ble_conn_deinit(void)

Deinitialization BLE connection management This function must be the last function to call, It is the opposite of the esp_ble_conn_init function.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong deinitialization

  • ESP_FAIL on error

esp_err_t esp_ble_conn_start(void)

Starts BLE session.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong start

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_stop(void)

Stop BLE session.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong stop

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_set_mtu(uint16_t mtu)

This api is typically used to update maximum transmission unit value.

Parameters

mtu – [in] The maximum transmission unit value to update

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong update

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_connect(void)

This api is typically used to connect actively.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong connect

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_disconnect(void)

This api is typically used to disconnect actively.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong disconnect

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_get_conn_handle(uint16_t *out_conn_handle)

Get current connection handle (read-only).

Parameters

out_conn_handle – [out] Pointer to store current connection handle. 0 if not connected.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if out_conn_handle is NULL

esp_err_t esp_ble_conn_get_mtu(uint16_t *out_mtu)

Get current negotiated GATT MTU (read-only).

Parameters

out_mtu – [out] Pointer to store current MTU. Defaults to 23 if unknown.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if out_mtu is NULL

esp_err_t esp_ble_conn_get_peer_addr(uint8_t out_addr[6])

Get current peer address (read-only).

Parameters

out_addr – [out] Pointer to store peer address (6 bytes).

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if out_addr is NULL

  • ESP_ERR_NOT_FOUND if not connected

esp_err_t esp_ble_conn_get_disconnect_reason(uint16_t *out_reason)

Get last disconnect reason (read-only).

Parameters

out_reason – [out] Pointer to store last disconnect reason.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if out_reason is NULL

  • ESP_ERR_NOT_FOUND if no disconnect reason is available

esp_err_t esp_ble_conn_update_params(uint16_t conn_handle, const esp_ble_conn_params_t *params)

Request connection parameter update.

Parameters

  • conn_handle – [in] Connection handle (use esp_ble_conn_get_conn_handle to query)

  • params – [in] Desired connection parameters

Returns

  • ESP_OK on success (request accepted)

  • ESP_ERR_INVALID_ARG on wrong parameters

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_create_server(uint16_t psm, uint16_t mtu, esp_ble_conn_l2cap_coc_event_cb_t cb, void *cb_arg)

Create an L2CAP CoC server.

Note

The callback context is persistent for this PSM and is reused across incoming connections. It is not auto-freed until the L2CAP CoC memory pool is released.

Parameters

  • psm – [in] Protocol/Service Multiplexer to listen on (must be in range 0x0001-0x00FF for LE)

  • mtu – [in] Maximum SDU size to use for the server (must be in range 23-512 bytes)

  • cb – [in] L2CAP CoC event callback

  • cb_arg – [in] Callback argument

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters (NULL callback, PSM out of range 0x0001-0x00FF, or MTU out of range)

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_connect(uint16_t conn_handle, uint16_t psm, uint16_t mtu, uint16_t sdu_size, esp_ble_conn_l2cap_coc_event_cb_t cb, void *cb_arg)

Initiate an L2CAP CoC connection.

Note

The callback context is auto-freed if the connection attempt fails (ESP_BLE_CONN_L2CAP_COC_EVENT_CONNECTED with non-zero status) and after ESP_BLE_CONN_L2CAP_COC_EVENT_DISCONNECTED.

Parameters

  • conn_handle – [in] Connection handle (must be in range 0x0001-0x0EFF)

  • psm – [in] Protocol/Service Multiplexer to connect to (must be in range 0x0001-0x00FF for LE)

  • mtu – [in] Maximum SDU size to use for the connection (must be in range 23-512 bytes)

  • sdu_size – [in] Receive buffer size for the first SDU (must be in range 23-65535 bytes). This size is used to allocate the initial RX buffer for the channel. Applications typically set it to the expected peer CoC MTU.

  • cb – [in] L2CAP CoC event callback

  • cb_arg – [in] Callback argument

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters (NULL callback, conn_handle/PSM/sdu_size out of range, or MTU out of range)

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_send(esp_ble_conn_l2cap_coc_chan_t chan, const esp_ble_conn_l2cap_coc_sdu_t *sdu)

Send an SDU over an L2CAP CoC channel.

Note

Flow control: If the channel is stalled (buffer full), this function returns ESP_ERR_NOT_FINISHED. The caller should wait for ESP_BLE_CONN_L2CAP_COC_EVENT_TX_UNSTALLED event before retrying the send operation.

Note

Memory pool: If mbuf allocation fails (ESP_ERR_NO_MEM), it indicates the memory pool is exhausted. The caller should wait and retry later, or check if there are pending operations that need to complete.

Parameters

  • chan – [in] L2CAP CoC channel

  • sdu – [in] SDU to send (data buffer is not owned by the stack, can be freed immediately after this function returns)

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters (NULL channel, NULL sdu, invalid data pointer, or zero length)

  • ESP_ERR_INVALID_STATE if memory pool not initialized or channel not connected

  • ESP_ERR_NO_MEM if mbuf allocation failed (memory pool exhausted)

  • ESP_ERR_NOT_FINISHED if channel is stalled or send would block (wait for TX_UNSTALLED event)

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_recv_ready(esp_ble_conn_l2cap_coc_chan_t chan, uint16_t sdu_size)

Provide a receive buffer for an L2CAP CoC channel.

Parameters

  • chan – [in] L2CAP CoC channel

  • sdu_size – [in] Receive buffer size for next SDU

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters

  • ESP_ERR_NO_MEM if memory pool not initialized or allocation failed

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_disconnect(esp_ble_conn_l2cap_coc_chan_t chan)

Disconnect an L2CAP CoC channel.

Parameters

chan – [in] L2CAP CoC channel

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_l2cap_coc_get_chan_info(esp_ble_conn_l2cap_coc_chan_t chan, esp_ble_conn_l2cap_coc_chan_info_t *chan_info)

Get L2CAP CoC channel information.

Parameters

  • chan – [in] L2CAP CoC channel

  • chan_info – [out] Channel info output

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters

  • ESP_ERR_NOT_SUPPORTED if L2CAP CoC is disabled

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_register_scan_callback(esp_ble_conn_scan_cb_t cb, void *cb_arg)

Register scan callback for BLE central role.

Parameters

  • cb – [in] Scan callback (can be NULL to disable)

  • cb_arg – [in] Callback argument

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on invalid parameters

esp_err_t esp_ble_conn_scan_stop(void)

Stop ongoing BLE scan (central role)

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if scan is not active

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_parse_adv_data(const uint8_t *adv_data, uint8_t adv_len, uint8_t ad_type, const uint8_t **out_data, uint8_t *out_len)

Parse AD type data from raw advertising data.

Parameters

  • adv_data – [in] Raw advertising data

  • adv_len – [in] Raw advertising data length

  • ad_type – [in] Advertising data type

  • out_data – [out] Output data pointer (points into adv_data)

  • out_len – [out] Output data length

Returns

  • ESP_OK if AD type is found

  • ESP_ERR_NOT_FOUND if AD type is not present

  • ESP_ERR_INVALID_ARG on invalid parameters

esp_err_t esp_ble_conn_notify(const esp_ble_conn_data_t *inbuff)

This api is typically used to notify actively.

Parameters

inbuff – [in] The pointer to store notify data.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong notify

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_read(esp_ble_conn_data_t *outbuf)

This api is typically used to read actively.

Parameters

outbuf – [in] The pointer to store read data.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong read

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_write(const esp_ble_conn_data_t *inbuff)

This api is typically used to write actively.

Parameters

inbuff – [in] The pointer to store write data.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong write

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_subscribe(esp_ble_conn_desc_t desc, const esp_ble_conn_data_t *inbuff)

This api is typically used to subscribe actively.

Parameters

  • desc – [in] The declarations of descriptors

  • inbuff – [in] The pointer to store subscribe data.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong subscribe

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_add_svc(const esp_ble_conn_svc_t *svc)

This api is typically used to add service actively.

Parameters

svc – [in] The pointer to store service.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong add service

  • ESP_FAIL on other error

esp_err_t esp_ble_conn_remove_svc(const esp_ble_conn_svc_t *svc)

This api is typically used to remove service actively.

Parameters

svc – [in] The pointer to store service.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG on wrong remove service

  • ESP_FAIL on other error

Unions

union esp_ble_conn_uuid_t
#include <esp_ble_conn_mgr.h>

Universal UUID, to be used for any-UUID static allocation.

Public Members

uint16_t uuid16

16 bit UUID of the service

uint32_t uuid32

32 bit UUID of the service

uint8_t uuid128[BLE_UUID128_VAL_LEN]

128 bit UUID of the service

Structures

struct esp_ble_conn_l2cap_coc_chan_info_t

L2CAP CoC channel information.

Public Members

uint16_t scid

Source Channel ID

uint16_t dcid

Destination Channel ID

uint16_t our_l2cap_mtu

Local L2CAP MTU

uint16_t peer_l2cap_mtu

Peer L2CAP MTU

uint16_t psm

Protocol/Service Multiplexer

uint16_t our_coc_mtu

Local CoC MTU

uint16_t peer_coc_mtu

Peer CoC MTU

struct esp_ble_conn_l2cap_coc_sdu_t

L2CAP CoC SDU buffer.

Public Members

uint16_t len

SDU length in bytes

uint8_t *data

SDU data buffer

struct esp_ble_conn_scan_result_t

BLE scan result data.

Public Members

uint8_t addr[6]

Peer address

uint8_t addr_type

Peer address type

int8_t rssi

RSSI in dBm

uint8_t adv_data_len

Advertising data length

uint8_t adv_data[ESP_BLE_CONN_ADV_DATA_MAX_LEN]

Advertising data

struct esp_ble_conn_l2cap_coc_event

L2CAP CoC event payload.

Public Members

esp_ble_conn_l2cap_coc_event_type_t type

Event type

int status

Connection status (0 on success)

TX status

Reconfigure status

uint16_t conn_handle

Connection handle

esp_ble_conn_l2cap_coc_chan_t chan

CoC channel

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] connect

Connected event data

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] disconnect

Disconnected event data

uint16_t peer_sdu_size

Peer SDU size

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] accept

Accept event data

esp_ble_conn_l2cap_coc_sdu_t sdu

SDU payload. Note: The sdu.data buffer is managed internally and will be freed immediately after the callback returns. The callback must not save the pointer for later use. If asynchronous processing is needed, the callback should copy the data.

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] receive

Receive event data

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] tx_unstalled

TX unstalled event data

struct esp_ble_conn_l2cap_coc_event::[anonymous]::[anonymous] reconfigured

Reconfigure event data

struct esp_ble_conn_character_t

This structure maps handler required by UUID which are used to BLE characteristics.

Public Members

const char *name

Name of the handler

uint8_t type

Type of the UUID

uint16_t flag

Flag for visiting right

esp_ble_conn_uuid_t uuid

Universal UUID, to be used for any-UUID static allocation

esp_ble_conn_cb_t uuid_fn

BLE UUID callback

struct esp_ble_conn_svc_t

This structure maps handler required by UUID which are used to BLE services.

Public Members

uint8_t type

Type of the UUID

uint16_t nu_lookup_count

Number of entries in the Name-UUID lookup table

esp_ble_conn_uuid_t uuid

Universal UUID, to be used for any-UUID static allocation

esp_ble_conn_character_t *nu_lookup

Pointer to the Name-UUID lookup table

struct esp_ble_conn_config_t

This structure maps handler required which are used to configure.

Public Members

uint8_t device_name[MAX_BLE_DEVNAME_LEN]

BLE device name being broadcast

uint8_t broadcast_data[BROADCAST_PARAM_LEN]

BLE device manufacturer being announce

uint16_t extended_adv_len

Extended advertising data length

uint16_t periodic_adv_len

Periodic advertising data length

uint16_t extended_adv_rsp_len

Extended advertising responses data length

const char *extended_adv_data

Extended advertising data

const char *periodic_adv_data

Periodic advertising data

const char *extended_adv_rsp_data

Extended advertising responses data

uint16_t include_service_uuid

If include service UUID in advertising

esp_ble_conn_uuid_type_t adv_uuid_type

UUID type: BLE_CONN_UUID_TYPE_16 or BLE_CONN_UUID_TYPE_128.

uint16_t adv_uuid16

16-bit UUID (when adv_uuid_type is BLE_CONN_UUID_TYPE_16)

uint8_t adv_uuid128[BLE_UUID128_VAL_LEN]

128-bit UUID (when adv_uuid_type is BLE_CONN_UUID_TYPE_128)

union esp_ble_conn_config_t::[anonymous] [anonymous]

Service UUID for advertising

struct esp_ble_conn_data_t

This structure maps handler required by UUID which are used to data.

Public Members

uint8_t type

Type of the UUID

uint16_t write_conn_id

Connection handle ID

esp_ble_conn_uuid_t uuid

Universal UUID, to be used for any-UUID static allocation

uint8_t *data

Data buffer

uint16_t data_len

Data size

struct esp_ble_conn_periodic_sync_t

This structure represents a periodic advertising sync established during discovery procedure.

Public Members

uint8_t status

Periodic sync status

uint16_t sync_handle

Periodic sync handle

uint8_t sid

Advertising Set ID

uint8_t adv_addr[6]

Advertiser address

uint8_t adv_phy

Advertising PHY

uint16_t per_adv_ival

Periodic advertising interval

uint8_t adv_clk_accuracy

Advertiser clock accuracy

struct esp_ble_conn_periodic_report_t

This structure represents a periodic advertising report received on established sync.

Public Members

uint16_t sync_handle

Periodic sync handle

int8_t tx_power

Advertiser transmit power in dBm (127 if unavailable)

int8_t rssi

Received signal strength indication in dBm (127 if unavailable)

uint8_t data_status

Advertising data status

uint8_t data_length

Advertising Data length

const uint8_t *data

Advertising data

struct esp_ble_conn_periodic_sync_lost_t

This structure represents a periodic advertising sync lost of established sync.

Public Members

uint16_t sync_handle

Periodic sync handle

int reason

Reason for sync lost

struct esp_ble_conn_cccd_update_t

This structure represents CCCD (Client Characteristic Configuration Descriptor) update event.

Public Members

uint16_t conn_handle

Connection handle

uint16_t char_handle

Characteristic handle

uint8_t uuid_type

UUID type

esp_ble_conn_uuid_t uuid

Characteristic UUID

bool notify_enable

Notification enabled (bit 0)

bool indicate_enable

Indication enabled (bit 1)

struct esp_ble_conn_params_t

BLE connection parameters.

Public Members

uint16_t itvl_min

Connection event interval minimum. This is in units of 1.25ms. (0x0006 = 7.5ms). Valid range: 0x0006–0x0C80

uint16_t itvl_max

Connection event interval maximum. This is in units of 1.25ms. (0x0006 = 7.5ms). Valid range: 0x0006–0x0C80

uint16_t latency

Peripheral latency. This is in units of connection events to skip. Valid range: 0x0000–0x01F3

uint16_t supervision_timeout

Supervision timeout. This is in units of 10ms. (e.g. 400 = 4s). Valid range: 0x000A–0x0C80. Must be larger than the connection interval (itvl_max * 1.25ms)

uint16_t min_ce_len

Minimum connection event length. This is in units of 0.625ms. 0 if unused.

uint16_t max_ce_len

Maximum connection event length. This is in units of 0.625ms. 0 if unused.

Macros

BLE_CONN_MGR_ADDR_STR

BLE address format string for printf-style logging.

BLE_CONN_MGR_ADDR_HEX(addr)

BLE address formatter arguments for printf-style logging.

ESP_BLE_CONN_ADV_TYPE_FLAGS

Common advertising data types

ESP_BLE_CONN_ADV_TYPE_NAME_SHORT
ESP_BLE_CONN_ADV_TYPE_NAME_COMPLETE
ESP_BLE_CONN_ADV_TYPE_TX_POWER
ESP_BLE_CONN_ADV_TYPE_UUID16_INCOMP
ESP_BLE_CONN_ADV_TYPE_UUID16_COMPLETE
ESP_BLE_CONN_ADV_TYPE_UUID32_INCOMP
ESP_BLE_CONN_ADV_TYPE_UUID32_COMPLETE
ESP_BLE_CONN_ADV_TYPE_UUID128_INCOMP
ESP_BLE_CONN_ADV_TYPE_UUID128_COMPLETE
ESP_BLE_CONN_ADV_TYPE_SERVICE_DATA16
ESP_BLE_CONN_ADV_TYPE_SERVICE_DATA32
ESP_BLE_CONN_ADV_TYPE_SERVICE_DATA128
ESP_BLE_CONN_ADV_TYPE_APPEARANCE
ESP_BLE_CONN_ADV_TYPE_MANUFACTURER
ESP_BLE_CONN_ADV_DATA_MAX_LEN
ESP_IOT_ATT_SUCCESS

Success code and error codes

ESP_IOT_ATT_INVALID_HANDLE
ESP_IOT_ATT_READ_NOT_PERMIT
ESP_IOT_ATT_WRITE_NOT_PERMIT
ESP_IOT_ATT_INVALID_PDU
ESP_IOT_ATT_INSUF_AUTHENTICATION
ESP_IOT_ATT_REQ_NOT_SUPPORTED
ESP_IOT_ATT_INVALID_OFFSET
ESP_IOT_ATT_INSUF_AUTHORIZATION
ESP_IOT_ATT_PREPARE_Q_FULL
ESP_IOT_ATT_NOT_FOUND
ESP_IOT_ATT_NOT_LONG
ESP_IOT_ATT_INSUF_KEY_SIZE
ESP_IOT_ATT_INVALID_ATTR_LEN
ESP_IOT_ATT_ERR_UNLIKELY
ESP_IOT_ATT_INSUF_ENCRYPTION
ESP_IOT_ATT_UNSUPPORT_GRP_TYPE
ESP_IOT_ATT_INSUF_RESOURCE
ESP_IOT_ATT_DATABASE_OUT_OF_SYNC
ESP_IOT_ATT_VALUE_NOT_ALLOWED
ESP_IOT_ATT_NO_RESOURCES

Application error codes

ESP_IOT_ATT_INTERNAL_ERROR
ESP_IOT_ATT_WRONG_STATE
ESP_IOT_ATT_DB_FULL
ESP_IOT_ATT_BUSY
ESP_IOT_ATT_ERROR
ESP_IOT_ATT_CMD_STARTED
ESP_IOT_ATT_ILLEGAL_PARAMETER
ESP_IOT_ATT_PENDING
ESP_IOT_ATT_AUTH_FAIL
ESP_IOT_ATT_MORE
ESP_IOT_ATT_INVALID_CFG
ESP_IOT_ATT_SERVICE_STARTED
ESP_IOT_ATT_ENCRYPED_MITM
ESP_IOT_ATT_ENCRYPED_NO_MITM
ESP_IOT_ATT_NOT_ENCRYPTED
ESP_IOT_ATT_CONGESTED
ESP_IOT_ATT_DUP_REG
ESP_IOT_ATT_ALREADY_OPEN
ESP_IOT_ATT_CANCEL
ESP_IOT_ATT_STACK_RSP

Common profile and service error codes

ESP_IOT_ATT_APP_RSP
ESP_IOT_ATT_UNKNOWN_ERROR
ESP_IOT_ATT_CCC_CFG_ERR
ESP_IOT_ATT_PRC_IN_PROGRESS
ESP_IOT_ATT_OUT_OF_RANGE
MAX_BLE_DEVNAME_LEN

BLE device name cannot be larger than this value 31 bytes (max scan response size) - 1 byte (length) - 1 byte (type) = 29 bytes BLE device name length

BLE_UUID128_VAL_LEN

128 bit UUID length

BROADCAST_PARAM_LEN

BLE device broadcast param length

BLE_CONN_GATT_CHR_BROADCAST

Characteristic broadcast properties

BLE_CONN_GATT_CHR_READ

Characteristic read properties

BLE_CONN_GATT_CHR_WRITE_NO_RSP

Characteristic write properties

BLE_CONN_GATT_CHR_WRITE

Characteristic write properties

BLE_CONN_GATT_CHR_NOTIFY

Characteristic notify properties

BLE_CONN_GATT_CHR_INDICATE

Characteristic indicate properties

BLE_CONN_GATT_CHR_READ_ENC

Characteristic read requires encryption

BLE_CONN_GATT_CHR_READ_AUTHEN

Characteristic read requires authentication

BLE_CONN_GATT_CHR_READ_AUTHOR

Characteristic read requires authorization

BLE_CONN_GATT_CHR_WRITE_ENC

Characteristic write requires encryption

BLE_CONN_GATT_CHR_WRITE_AUTHEN

Characteristic write requires authentication

BLE_CONN_GATT_CHR_WRITE_AUTHOR

Characteristic write requires authorization

BLE_UUID_CMP(type, src, dst)
BLE_UUID_TYPE(type)
MIN(a, b)

Type Definitions

typedef void *esp_ble_conn_l2cap_coc_chan_t

L2CAP CoC channel handle (opaque pointer)

Note

This is an opaque handle managed by the stack. Applications must not dereference, cast, or persist it beyond the lifetime of the associated connection. Use it only with the L2CAP CoC APIs provided here.

typedef bool (*esp_ble_conn_scan_cb_t)(const esp_ble_conn_scan_result_t *result, void *arg)
typedef struct esp_ble_conn_l2cap_coc_event esp_ble_conn_l2cap_coc_event_t

L2CAP CoC event payload.

typedef int (*esp_ble_conn_l2cap_coc_event_cb_t)(esp_ble_conn_l2cap_coc_event_t *event, void *arg)

L2CAP CoC event callback.

Note

For ESP_BLE_CONN_L2CAP_COC_EVENT_DATA_RECEIVED events, the sdu.data buffer is managed internally and will be freed immediately after this callback returns. The callback must not save the pointer for later use. If asynchronous processing is needed, the callback should copy the data before returning.

Param event

[in] L2CAP CoC event payload

Param arg

[in] User context

Return

  • 0 to indicate the event was handled successfully

  • Non-zero to indicate an application error (stack behavior may vary by event type)

typedef esp_err_t (*esp_ble_conn_cb_t)(const uint8_t *inbuf, uint16_t inlen, uint8_t **outbuf, uint16_t *outlen, void *priv_data, uint8_t *att_status)

This is type of function that will handle the registered characteristic.

Param inbuf

[in] The pointer to store data: read operation if NULL or write operation if not NULL

Param inlen

[in] The store data length

Param outbuf

[out] Variable to store data, it’ll free by connection management component

Param outlen

[out] Variable to store data length

Param priv_data

[in] Private data context

Param att_status

[in] The attribute return status

Return

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_FAIL on error

Enumerations

enum esp_ble_conn_l2cap_coc_event_type_t

L2CAP CoC event types.

Values:

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_CONNECTED

CoC channel connected

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_DISCONNECTED

CoC channel disconnected

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_ACCEPT

CoC connection accepted

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_DATA_RECEIVED

SDU received

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_TX_UNSTALLED

TX unstalled

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_RECONFIG_COMPLETED

Local reconfigure completed

enumerator ESP_BLE_CONN_L2CAP_COC_EVENT_PEER_RECONFIGURED

Peer reconfigured

enum esp_ble_conn_event_t

Type of event.

Values:

enumerator ESP_BLE_CONN_EVENT_UNKNOWN

Unknown event

enumerator ESP_BLE_CONN_EVENT_STARTED

When BLE connection management start, the event comes

enumerator ESP_BLE_CONN_EVENT_STOPPED

When BLE connection management stop, the event comes

enumerator ESP_BLE_CONN_EVENT_CONNECTED

When a new connection was established, the event comes

enumerator ESP_BLE_CONN_EVENT_DISCONNECTED

When a connection was terminated, the event comes

enumerator ESP_BLE_CONN_EVENT_DATA_RECEIVE

When receive a notification or indication data, the event comes

enumerator ESP_BLE_CONN_EVENT_DISC_COMPLETE

When the ble discover service complete, the event comes

enumerator ESP_BLE_CONN_EVENT_PERIODIC_REPORT

When the periodic adv report, the event comes

enumerator ESP_BLE_CONN_EVENT_PERIODIC_SYNC_LOST

When the periodic sync lost, the event comes

enumerator ESP_BLE_CONN_EVENT_PERIODIC_SYNC

When the periodic sync, the event comes

enumerator ESP_BLE_CONN_EVENT_CCCD_UPDATE

When CCCD (Client Characteristic Configuration Descriptor) is written, the event comes

enum esp_ble_conn_desc_t

Type of descriptors.

Values:

enumerator ESP_BLE_CONN_DESC_UNKNOWN

Unknown descriptors

enumerator ESP_BLE_CONN_DESC_EXTENDED

Characteristic Extended Properties

enumerator ESP_BLE_CONN_DESC_USER

Characteristic User Description

enumerator ESP_BLE_CONN_DESC_CIENT_CONFIG

Client Characteristic Configuration

enumerator ESP_BLE_CONN_DESC_SERVER_CONFIG

Server Characteristic Configuration

enumerator ESP_BLE_CONN_DESC_PRE_FORMAT

Characteristic Presentation Format

enumerator ESP_BLE_CONN_DESC_AGG_FORMAT

Characteristic Aggregate Format

enumerator ESP_BLE_CONN_DESC_VALID_RANGE

Valid Range

enumerator ESP_BLE_CONN_DESC_EXTREPORT

External Report Reference

enumerator ESP_BLE_CONN_DESC_REPORT

Report Reference

enumerator ESP_BLE_CONN_DESC_DIGITAL

Number of Digitals

enumerator ESP_BLE_CONN_DESC_VALUE_TRIGGER

Value Trigger Setting

enumerator ESP_BLE_CONN_DESC_ENV_SENS_CONFIG

Environmental Sensing Configuration

enumerator ESP_BLE_CONN_DESC_ENV_SENS_MEASURE

Environmental Sensing Measurement

enumerator ESP_BLE_CONN_DESC_ENV_TRIGGER

Environmental Sensing Trigger Setting

enumerator ESP_BLE_CONN_DESC_TIME_TRIGGER

Time Trigger Setting

enumerator ESP_BLE_CONN_DESC_COMPLETE_BLOCK

Complete BR-EDR Transport Block Data

enum esp_ble_conn_uuid_type_t

Type of UUID.

Values:

enumerator BLE_CONN_UUID_TYPE_16

16-bit UUID (BT SIG assigned)

enumerator BLE_CONN_UUID_TYPE_32

32-bit UUID (BT SIG assigned)

enumerator BLE_CONN_UUID_TYPE_128

128-bit UUID

Provide feedback about this document