BLE 连接管理

支持的芯片

ESP32

ESP32-C2

ESP32-C3

ESP32-S3

BLE 连接管理为访问常用 BLE 功能提供了简化的 API 接口。它支持外围、中心等常见场景。

应用示例

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

示例

BLE 周期广告示例: bluetooth/ble_conn_mgr/ble_periodic_adv.
BLE 周期同步示例: bluetooth/ble_conn_mgr/ble_periodic_sync.
BLE 串口配置文件示例: bluetooth/ble_conn_mgr/ble_spp.

API 参考

Header File

components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h

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.

参数

config – [in] The configurations, see esp_ble_conn_config_t.

返回

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.

返回

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.

返回

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.

返回

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.

参数

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

返回

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.

返回

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.

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

desc – [in] The declarations of descriptors
inbuff – [in] The pointer to store subscribe data.

返回

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.

参数

svc – [in] The pointer to store service.

返回

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.

参数

svc – [in] The pointer to store service.

返回

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

uint16_t adv_uuid16: NOTE: Only Support one 16-bit UUID

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

提供有关此文档的反馈