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
BLE periodic advertiser example: bluetooth/ble_conn_mgr/ble_periodic_adv.
BLE periodic sync example: bluetooth/ble_conn_mgr/ble_periodic_sync.
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.
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
-
const char *name
-
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
-
uint8_t type
-
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
-
uint8_t device_name[MAX_BLE_DEVNAME_LEN]
-
struct esp_ble_conn_data_t
This structure maps handler required by UUID which are used to data.
-
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
-
uint8_t status
-
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
-
uint16_t sync_handle
-
struct esp_ble_conn_periodic_sync_lost_t
This structure represents a periodic advertising sync lost of established sync.
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
-
enumerator ESP_BLE_CONN_EVENT_UNKNOWN
-
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
-
enumerator ESP_BLE_CONN_DESC_UNKNOWN