BLE Connection Management

[中文]

Supported Socs

ESP32

ESP32-C2

ESP32-C3

ESP32-S3

The BLE connection management provide 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.

API Reference

Header File

Functions

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

uint8_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

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

Macros

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_UUID_CMP(type, src, dst)
BLE_UUID_TYPE(type)
MIN(a, b)

Type Definitions

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)

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

Return

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_FAIL on error

Enumerations

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

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