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.
BLE L2CAP CoC 中心设备示例: bluetooth/ble_l2cap_coc/l2cap_coc_central.
BLE L2CAP CoC 外围设备示例: bluetooth/ble_l2cap_coc/l2cap_coc_peripheral.

API 参考

Header File

components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h

Functions

esp_err_t esp_ble_conn_l2cap_coc_mem_init(void)

Initialize L2CAP CoC SDU memory pool.

备注

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

返回

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.

备注

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.

返回

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)

参数

conn_handle – [in] Connection handle
peer_sdu_size – [in] Peer SDU size from accept event
chan – [in] L2CAP CoC channel

返回

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.

参数

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)

Legacy API to set preferred MTU.

This API is kept for backward compatibility and is a no-op in multi-connection implementation. Use esp_ble_conn_mtu_update(conn_handle, mtu) instead.

参数

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 if BLE connection manager is not initialized
ESP_ERR_TIMEOUT if connect event is not received within wait timeout
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 if BLE connection manager is not initialized
ESP_ERR_NOT_FOUND if no active connection exists
ESP_ERR_TIMEOUT if disconnect event is not received within wait timeout
ESP_FAIL on other error

esp_err_t esp_ble_conn_connect_to_addr(const uint8_t peer_addr[6], uint8_t peer_addr_type)

Initiate BLE connection to a peer (Central role).

备注

Only one outgoing connection attempt is allowed at a time. Returns ESP_ERR_INVALID_STATE if a connection attempt is already in progress.

参数

peer_addr – [in] Peer BLE address (6 bytes)
peer_addr_type – [in] Peer address type: esp_ble_conn_addr_type_t

返回

ESP_OK on success (connection initiated; result via ESP_BLE_CONN_EVENT_CONNECTED/DISCONNECTED)
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_INVALID_STATE if max connections reached, peer already connected/pending, or another attempt in progress
ESP_ERR_NOT_SUPPORTED if Central role is not enabled
ESP_FAIL if connection initiation fails

esp_err_t esp_ble_conn_disconnect_by_handle(uint16_t conn_handle)

Disconnect a BLE connection by handle.

参数

conn_handle – [in] Connection handle to terminate (valid range 0x0000–0x0EFF)

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if conn_handle is BLE_CONN_HANDLE_INVALID or out of range
ESP_FAIL if disconnect fails

esp_err_t esp_ble_conn_get_conn_handle(uint16_t *out_conn_handle)

Get current (default) connection handle (read-only).

In multi-connection mode this returns the first/primary connection handle, or BLE_CONN_HANDLE_INVALID if none.

参数

out_conn_handle – [out] Pointer to store the handle. Set to BLE_CONN_HANDLE_INVALID when not connected.

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if out_conn_handle is NULL

esp_err_t esp_ble_conn_get_conn_handle_by_addr(const uint8_t peer_addr[6], uint8_t peer_addr_type, uint16_t *out_conn_handle)

Get connection handle by peer address.

Use this in multi-connection scenarios to resolve a peer address to its connection handle (valid range 0x0000–0x0EFF).

参数

peer_addr – [in] Peer BLE address (6 bytes)
peer_addr_type – [in] Peer address type: esp_ble_conn_addr_type_t
out_conn_handle – [out] Pointer to store the connection handle for that peer

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if peer_addr or out_conn_handle is NULL
ESP_ERR_NOT_FOUND if no connection exists for the given peer address

esp_err_t esp_ble_conn_get_mtu(uint16_t *out_mtu)

Get current negotiated GATT MTU (read-only).

参数

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

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if out_mtu is NULL

esp_err_t esp_ble_conn_get_mtu_by_handle(uint16_t conn_handle, uint16_t *out_mtu)

Get negotiated GATT MTU by connection handle.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid)
out_mtu – [out] Pointer to store MTU

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters (e.g. conn_handle out of range)
ESP_ERR_NOT_FOUND if connection does not exist

esp_err_t esp_ble_conn_get_peer_addr(uint8_t out_addr[6])

Get current peer address (read-only).

参数

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

返回

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_peer_addr_by_handle(uint16_t conn_handle, uint8_t out_peer_addr[6], uint8_t *out_peer_addr_type)

Get peer address by connection handle.

参数

conn_handle – [in] Connection handle
out_peer_addr – [out] Pointer to store peer address (6 bytes)
out_peer_addr_type – [out] Pointer to store peer address type (can be NULL)

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_FOUND if connection does not exist

esp_err_t esp_ble_conn_find_conn_handle_by_peer_addr(const uint8_t peer_addr[6], uint8_t peer_addr_type, uint16_t *out_conn_handle)

Find connection handle by peer address.

参数

peer_addr – [in] Peer address (6 bytes)
peer_addr_type – [in] Peer address type
out_conn_handle – [out] Pointer to store matched connection handle

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_FOUND if no matched connection exists

esp_err_t esp_ble_conn_find_peer_addr_by_conn_handle(uint16_t conn_handle, uint8_t out_peer_addr[6], uint8_t *out_peer_addr_type)

Find peer address by connection handle (deprecated).

Deprecated:: Use esp_ble_conn_get_peer_addr_by_handle() instead.

参数

conn_handle – [in] Connection handle
out_peer_addr – [out] Output peer address (6 bytes)
out_peer_addr_type – [out] Output peer address type (can be NULL)

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_FOUND if the connection handle does not exist

esp_err_t esp_ble_conn_get_disconnect_reason(uint16_t *out_reason)

Get last disconnect reason (read-only).

参数

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

返回

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_get_disconnect_reason_by_handle(uint16_t conn_handle, uint16_t *out_reason)

Get disconnect reason by connection handle.

参数

conn_handle – [in] Connection handle
out_reason – [out] Pointer to store disconnect reason

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_FOUND if reason is unavailable for the connection

esp_err_t esp_ble_conn_update_params(uint16_t conn_handle, const esp_ble_conn_params_t *params)

Request connection parameter update.

参数

conn_handle – [in] Connection handle (use esp_ble_conn_get_conn_handle to query)
params – [in] Desired connection parameters (min_ce_len and max_ce_len are forwarded to NimBLE).

返回

ESP_OK on success (request accepted)
ESP_ERR_INVALID_ARG on wrong parameters
ESP_FAIL on other error

esp_err_t esp_ble_conn_get_phy(uint16_t conn_handle, uint8_t *out_tx_phy, uint8_t *out_rx_phy)

Get current LE PHY for a connection.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF).
out_tx_phy – [out] Pointer to store TX PHY (esp_ble_conn_phy_t: 1=1M, 2=2M, 3=Coded). Can be NULL.
out_rx_phy – [out] Pointer to store RX PHY (esp_ble_conn_phy_t). Can be NULL.

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if conn_handle is invalid or both out_tx_phy and out_rx_phy are NULL
ESP_ERR_NOT_FOUND if connection does not exist
ESP_FAIL on other error

esp_err_t esp_ble_conn_set_preferred_phy(uint16_t conn_handle, uint8_t tx_phys_mask, uint8_t rx_phys_mask, uint16_t phy_opts)

Set preferred LE PHY for a connection.

The controller may not apply the change if the peer does not support the requested PHY.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF).
tx_phys_mask – [in] Preferred TX PHY mask: ESP_BLE_CONN_PHY_MASK_1M, _2M, _CODED, or _ALL (or combination).
rx_phys_mask – [in] Preferred RX PHY mask (same as tx_phys_mask).
phy_opts – [in] Coded PHY option when using CODED: ESP_BLE_CONN_PHY_CODED_OPT_ANY, _S2, or _S8; otherwise 0.

返回

ESP_OK on success (request accepted)
ESP_ERR_INVALID_ARG if conn_handle is invalid or out of range
ESP_ERR_NOT_FOUND if connection does not exist
ESP_FAIL on other error

esp_err_t esp_ble_conn_set_data_len(uint16_t conn_handle, uint16_t tx_octets, uint16_t tx_time)

Set preferred data length for a connection (LE Data Length Extension).

Sends LE Set Data Length command to the controller. The controller negotiates with the peer asynchronously. Per BLE spec: tx_octets 27–251 bytes, tx_time 328–17040 microseconds.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF).
tx_octets – [in] Preferred TX payload size in bytes (27–251).
tx_time – [in] Preferred TX time in microseconds (328–17040).

返回

ESP_OK on success (command accepted)
ESP_ERR_INVALID_ARG if conn_handle or parameters are out of range
ESP_ERR_NOT_FOUND if connection does not exist
ESP_ERR_NOT_SUPPORTED if Data Length Extension is not supported
ESP_FAIL on other error

esp_err_t esp_ble_conn_adv_params_set(const esp_ble_conn_adv_params_t *params)

Configure advertising parameters.

参数

params – [in] Advertising parameters (NULL to use defaults)

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized

esp_err_t esp_ble_conn_adv_data_set(const uint8_t *data, uint16_t len)

Set advertising data (legacy or extended).

参数

data – [in] Raw advertising data (format: length-byte + type + value per AD structure). Can be NULL to clear.
len – [in] Data length in bytes. Max: ESP_BLE_CONN_ADV_DATA_MAX_LEN (31) for legacy; larger when extended advertising is enabled (platform-dependent).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized
ESP_ERR_INVALID_ARG if len exceeds maximum or data is NULL while len > 0
ESP_ERR_NO_MEM on allocation failure

esp_err_t esp_ble_conn_scan_rsp_data_set(const uint8_t *data, uint16_t len)

Set scan response data (legacy or extended).

参数

data – [in] Raw scan response data (format: length-byte + type + value per AD structure). Can be NULL to clear.
len – [in] Data length in bytes. Max: ESP_BLE_CONN_ADV_DATA_MAX_LEN (31) for legacy; larger when extended advertising is enabled (platform-dependent).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized
ESP_ERR_INVALID_ARG if len exceeds maximum or data is NULL while len > 0
ESP_ERR_NO_MEM on allocation failure

esp_err_t esp_ble_conn_periodic_adv_data_set(const uint8_t *data, uint16_t len)

Set periodic advertising data (extended advertising only).

参数

data – [in] Raw periodic advertising data. Can be NULL to clear.
len – [in] Data length in bytes (platform-dependent max when CONFIG_BLE_CONN_MGR_PERIODIC_ADV is set).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized
ESP_ERR_INVALID_ARG if len exceeds maximum or data is NULL while len > 0
ESP_ERR_NO_MEM on allocation failure
ESP_ERR_NOT_SUPPORTED if periodic advertising is not enabled

esp_err_t esp_ble_conn_adv_start(void)

Start advertising (peripheral role).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if not initialized or not in peripheral role
ESP_FAIL on other error

esp_err_t esp_ble_conn_adv_stop(void)

Stop advertising (peripheral role).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if not initialized
ESP_FAIL on other error

esp_err_t esp_ble_conn_scan_params_set(const esp_ble_conn_scan_params_t *params)

Configure scan parameters.

参数

params – [in] Scan parameters (NULL to use defaults)

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized

esp_err_t esp_ble_conn_scan_start(void)

Start scanning (central role).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if not initialized or not in central role
ESP_FAIL on other error

esp_err_t esp_ble_conn_scan_stop(void)

Stop ongoing BLE scan (central role).

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if scan is not active
ESP_FAIL on other error

esp_err_t esp_ble_conn_mtu_update(uint16_t conn_handle, uint16_t mtu)

Initiate MTU exchange on a connection.

Sets preferred MTU and initiates exchange (central) or sets preferred for future (peripheral).

参数

conn_handle – [in] Connection handle
mtu – [in] Desired MTU (BLE_ATT_MTU_DFLT to BLE_ATT_MTU_MAX, typically 512)

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_FAIL on other error

esp_err_t esp_ble_conn_set_local_passkey(uint32_t passkey)

Set local passkey for pairing (DISP mode).

When the device displays a passkey during pairing (action DISP), this key is used and auto-injected. Set to 0 to disable (application handles via esp_ble_conn_passkey_reply).

参数

passkey – [in] 6-digit passkey (0-999999); 0 to clear

返回

ESP_OK on success
ESP_ERR_INVALID_STATE if BLE connection manager is not initialized

esp_err_t esp_ble_conn_security_initiate(uint16_t conn_handle)

Initiate BLE security procedure.

Call this to start pairing. When ESP_BLE_CONN_EVENT_PASSKEY_ACTION occurs, use esp_ble_conn_passkey_reply() or esp_ble_conn_numcmp_reply() to respond.

参数

conn_handle – [in] Connection handle

返回

ESP_OK on success
ESP_ERR_INVALID_ARG if conn_handle is BLE_CONN_HANDLE_INVALID or out of range
ESP_ERR_NOT_SUPPORTED if stack SMP is disabled
ESP_FAIL on other error

esp_err_t esp_ble_conn_passkey_reply(uint16_t conn_handle, uint32_t passkey)

Reply to passkey action.

Call when ESP_BLE_CONN_EVENT_PASSKEY_ACTION has action INPUT. Pass the passkey entered by the user.

参数

conn_handle – [in] Connection handle
passkey – [in] 6-digit passkey (0-999999)

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_SUPPORTED if NimBLE SMP is disabled
ESP_FAIL on other error

esp_err_t esp_ble_conn_numcmp_reply(uint16_t conn_handle, bool accept)

Reply to numeric comparison (NUMCMP).

Call when ESP_BLE_CONN_EVENT_PASSKEY_ACTION has action NUMCMP.

参数

conn_handle – [in] Connection handle
accept – [in] true to accept, false to reject

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters
ESP_ERR_NOT_SUPPORTED if NimBLE SMP is disabled
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.

备注

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.

参数

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

返回

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.

备注

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.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid)
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

返回

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.

备注

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.

备注

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.

参数

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)

返回

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.

参数

chan – [in] L2CAP CoC channel
sdu_size – [in] Receive buffer size for next SDU

返回

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.

参数

chan – [in] L2CAP CoC channel

返回

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.

参数

chan – [in] L2CAP CoC channel
chan_info – [out] Channel info output

返回

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.

备注

When the callback returns true, a connection is initiated to that peer. Only one outgoing connection attempt is allowed at a time. If a connection attempt is already in progress, further scan results that would trigger connect are skipped until the current attempt completes (success or fail).

参数

cb – [in] Scan callback (can be NULL to disable)
cb_arg – [in] Callback argument

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters

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.

参数

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

返回

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.

参数

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_notify_by_handle(uint16_t conn_handle, const esp_ble_conn_data_t *inbuff)

Send notification/indication to a specific connection.

备注

The given conn_handle is the effective target; inbuff->write_conn_id is ignored. Use this API for multi-connection when sending to a specific link.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid).
inbuff – [in] Notify payload (characteristic UUID and data).

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters (e.g. conn_handle out of range)
ESP_ERR_NO_MEM if system resources are insufficient
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_read_by_handle(uint16_t conn_handle, esp_ble_conn_data_t *outbuf)

Read characteristic on a specific connection.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid).
outbuf – [inout] Read request/response buffer (UUID and optional write_conn_id; response in outbuf).

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters (e.g. conn_handle out of range)
ESP_ERR_TIMEOUT if read completion is not received within wait timeout
ESP_FAIL or stack-specific error code on read failure

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_write_by_handle(uint16_t conn_handle, const esp_ble_conn_data_t *inbuff)

Write characteristic on a specific connection.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid).
inbuff – [in] Write payload (characteristic UUID and data).

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters (e.g. conn_handle out of range)
ESP_ERR_NO_MEM if system resources are insufficient
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_subscribe_by_handle(uint16_t conn_handle, esp_ble_conn_desc_t desc, const esp_ble_conn_data_t *inbuff)

Subscribe to notifications/indications on a specific connection.

参数

conn_handle – [in] Connection handle (valid range 0x0000–0x0EFF; BLE_CONN_HANDLE_INVALID is invalid).
desc – [in] Descriptor type (e.g. ESP_BLE_CONN_DESC_CIENT_CONFIG for CCCD).
inbuff – [in] Subscribe payload (characteristic UUID and enable flags).

返回

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid parameters (e.g. conn_handle out of range)
ESP_ERR_NO_MEM if system resources are insufficient
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_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]: Local name for peripheral role (name broadcast when advertising)

uint8_t remote_name[MAX_BLE_DEVNAME_LEN]: Remote name for central role (target device name to connect to when scan_cb is NULL)

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; use BLE_CONN_HANDLE_INVALID to use default link

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. Valid range: 0x0000–0x0C80

uint16_t max_ce_len: Maximum connection event length. Valid range: 0x0000–0x0C80

struct esp_ble_conn_adv_params_t

BLE advertising parameters. Aligned with LE Set Extended Advertising Parameters (HCI). Interval units: 0.625ms. e.g. 0x100 = 100ms. Legacy advertising uses itvl_min, itvl_max, conn_mode, disc_mode; extended fields are applied when CONFIG_BLE_CONN_MGR_EXTENDED_ADV is enabled.

Public Members

uint8_t adv_handle: Advertising_Handle: instance index; 0 = use default (e.g. 1)

uint16_t adv_event_properties: Advertising_Event_Properties: BIT0=connectable, BIT1=scannable, BIT2=directed, BIT3=high_duty_directed, BIT4=legacy_pdu, BIT5=anonymous, BIT6=include_tx_power, BIT7=scan_req_notif

uint16_t itvl_min: Primary_Advertising_Interval_Min (0.625ms). Valid 0x0020–0x4000, 0 = default

uint16_t itvl_max: Primary_Advertising_Interval_Max (0.625ms). Valid 0x0020–0x4000, 0 = default

uint8_t conn_mode: Legacy: esp_ble_conn_adv_conn_mode_t

uint8_t disc_mode: Legacy: esp_ble_conn_adv_disc_mode_t

uint8_t channel_map: Primary_Advertising_Channel_Map: BIT0=ch37, BIT1=ch38, BIT2=ch39. 0 = default (all)

uint8_t own_addr_type: Own address type: esp_ble_conn_addr_type_t

uint8_t peer_addr_type: Peer address type for directed adv: esp_ble_conn_addr_type_t; 0 = not directed

uint8_t peer_addr[6]: Peer_Address for directed advertising

uint8_t filter_policy: Advertising filter: esp_ble_conn_scan_filt_policy_t

int8_t tx_power: Advertising_TX_Power in dBm; 127 = use stack default

uint8_t primary_phy: Primary advertising PHY: esp_ble_conn_phy_t

uint8_t secondary_adv_max_skip: Secondary_Advertising_Max_Skip (0 = send every primary)

uint8_t secondary_phy: Secondary advertising PHY: esp_ble_conn_phy_t

uint8_t sid: Advertising_SID (0–15)

uint8_t scan_req_notif: Scan_Request_Notification_Enable: 0 = disabled, non-zero = enabled

uint8_t primary_phy_options: Primary_Advertising_PHY_Options, 0 = default

uint8_t secondary_phy_options: Secondary_Advertising_PHY_Options, 0 = default

uint8_t ext_adv_cap: Deprecated: use adv_event_properties; applied when adv_event_properties is 0

struct esp_ble_conn_scan_params_t

BLE scan parameters. Aligned with LE Set Scan Parameters / Extended Scan (HCI). Interval/window units: 0.625ms. e.g. 0x12 = 11.25ms.

Public Members

uint8_t own_addr_type: Own address type: esp_ble_conn_addr_type_t

uint8_t filter_policy: Scanning filter: esp_ble_conn_scan_filt_policy_t

uint16_t itvl: Scan_Interval (0.625ms). 0 = use stack default

uint16_t window: Scan_Window (0.625ms). 0 = use stack default. Must be <= itvl

bool passive: Scan_Type: true = passive scan (no scan requests), false = active

bool filter_duplicates: true = filter duplicate advertisements

bool limited: true = limited discovery procedure

uint8_t scan_phys: Scanning PHYs (bitmask). 0 = standard scan (1M). Reserved and currently ignored by NimBLE backend

struct esp_ble_conn_event_data_t

Unified event data for BLE connection manager events. Use the union member corresponding to the event type (esp_ble_conn_event_t).

Public Members

uint16_t conn_handle: Connection handle

uint8_t peer_addr[6]

Peer address (big-endian)

Peer address

uint8_t peer_addr_type

Peer address type: esp_ble_conn_addr_type_t

Peer address type

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] connected: ESP_BLE_CONN_EVENT_CONNECTED

uint16_t reason: Disconnect reason (stack/HCI error code)

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] disconnected: ESP_BLE_CONN_EVENT_DISCONNECTED

esp_ble_conn_data_t data_receive: ESP_BLE_CONN_EVENT_DATA_RECEIVE

esp_ble_conn_periodic_report_t periodic_report: ESP_BLE_CONN_EVENT_PERIODIC_REPORT

esp_ble_conn_periodic_sync_lost_t periodic_sync_lost: ESP_BLE_CONN_EVENT_PERIODIC_SYNC_LOST

esp_ble_conn_periodic_sync_t periodic_sync: ESP_BLE_CONN_EVENT_PERIODIC_SYNC

esp_ble_conn_cccd_update_t cccd_update: ESP_BLE_CONN_EVENT_CCCD_UPDATE

uint16_t channel_id: GATT channel ID (0 for ATT)

uint16_t mtu: Negotiated MTU value

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] mtu_update: ESP_BLE_CONN_EVENT_MTU

int status

Update status (0 on success, non-zero on failure)

0 on success, non-zero on failure

esp_ble_conn_params_t params: Updated connection parameters

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] conn_param_update: ESP_BLE_CONN_EVENT_CONN_PARAM_UPDATE

esp_ble_conn_scan_result_t scan_result: ESP_BLE_CONN_EVENT_SCAN_RESULT

bool encrypted: Link is encrypted

bool authenticated: Link is authenticated

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] enc_change: ESP_BLE_CONN_EVENT_ENC_CHANGE

esp_ble_conn_sm_action_t action: Passkey action type, see esp_ble_conn_sm_action_t

uint32_t passkey: Passkey to display (DISP), or for user to enter (INPUT), or to compare (NUMCMP)

struct esp_ble_conn_event_data_t::[anonymous]::[anonymous] passkey_action: ESP_BLE_CONN_EVENT_PASSKEY_ACTION

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

BLE_CONN_HANDLE_INVALID: Invalid connection handle (no connection). Use to check “not connected” or invalid handle.

BLE_CONN_HANDLE_MAX: Maximum valid connection handle. Valid range is 0x0000 – BLE_CONN_HANDLE_MAX (0x0EFF).

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

ESP_BLE_CONN_PHY_MASK_1M: LE PHY preference mask (for set preferred PHY). Values match the underlying stack. Prefer 1M PHY

ESP_BLE_CONN_PHY_MASK_2M: Prefer 2M PHY

ESP_BLE_CONN_PHY_MASK_CODED: Prefer Coded PHY

ESP_BLE_CONN_PHY_MASK_ALL: All PHYs (1M | 2M | Coded)

ESP_BLE_CONN_PHY_CODED_OPT_ANY: Coded PHY option (phy_opts when using ESP_BLE_CONN_PHY_MASK_CODED). Coded: any

ESP_BLE_CONN_PHY_CODED_OPT_S2: Coded: S=2

ESP_BLE_CONN_PHY_CODED_OPT_S8: Coded: S=8

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)

备注

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.

备注

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_sm_action_t

Passkey action types for Security Manager pairing.

Values:

enumerator ESP_BLE_CONN_SM_ACT_NONE: No action / unknown / other

enumerator ESP_BLE_CONN_SM_ACT_OOB: Out-of-band (OOB) data required

enumerator ESP_BLE_CONN_SM_ACT_INPUT: User must enter passkey; call esp_ble_conn_passkey_reply()

enumerator ESP_BLE_CONN_SM_ACT_DISP: Display passkey to user, application should display the passkey

enumerator ESP_BLE_CONN_SM_ACT_NUMCMP: Numeric comparison; call esp_ble_conn_numcmp_reply()

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_adv_conn_mode_t

Legacy advertising connection mode (conn_mode in esp_ble_conn_adv_params_t). Values match the underlying BLE stack.

Values:

enumerator ESP_BLE_CONN_ADV_CONN_MODE_NON: Non-connectable

enumerator ESP_BLE_CONN_ADV_CONN_MODE_DIR: Connectable directed

enumerator ESP_BLE_CONN_ADV_CONN_MODE_UND: Connectable undirected

enum esp_ble_conn_adv_disc_mode_t

Legacy advertising discoverable mode (disc_mode in esp_ble_conn_adv_params_t)

Values:

enumerator ESP_BLE_CONN_ADV_DISC_MODE_NON: Non-discoverable

enumerator ESP_BLE_CONN_ADV_DISC_MODE_LTD: Limited discoverable

enumerator ESP_BLE_CONN_ADV_DISC_MODE_GEN: General discoverable

enum esp_ble_conn_addr_type_t

BLE address type (for own_addr_type, peer_addr_type in adv/scan/event data)

Values:

enumerator ESP_BLE_CONN_ADDR_PUBLIC: Public device address

enumerator ESP_BLE_CONN_ADDR_RANDOM: Random device address

enum esp_ble_conn_phy_t

LE PHY (primary_phy, secondary_phy in adv params; scan_phys bitmask)

Values:

enumerator ESP_BLE_CONN_PHY_1M: 1M PHY

enumerator ESP_BLE_CONN_PHY_2M: 2M PHY

enumerator ESP_BLE_CONN_PHY_CODED: Coded PHY

enum esp_ble_conn_scan_filt_policy_t

Scan filter policy (filter_policy in scan params)

Values:

enumerator ESP_BLE_CONN_SCAN_FILT_NO_WL: Accept any advertiser

enumerator ESP_BLE_CONN_SCAN_FILT_USE_WL: Use whitelist only

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

enumerator ESP_BLE_CONN_EVENT_MTU: When GATT MTU is negotiated/updated, the event comes

enumerator ESP_BLE_CONN_EVENT_CONN_PARAM_UPDATE: When connection parameters are updated, the event comes

enumerator ESP_BLE_CONN_EVENT_SCAN_RESULT: When a BLE advertisement is received during scan (central role), the event comes

enumerator ESP_BLE_CONN_EVENT_ENC_CHANGE: When link encryption state changes (pairing/encryption complete or failed), the event comes

enumerator ESP_BLE_CONN_EVENT_PASSKEY_ACTION: When passkey input/display/confirm is needed during pairing, 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

提供有关此文档的反馈