ESPHome 2026.8.0b4
Loading...
Searching...
No Matches
esphome::bluetooth_connection::BluetoothConnection Class Referencefinal

#include <bluetooth_connection_hub.h>

Inheritance diagram for esphome::bluetooth_connection::BluetoothConnection:
esphome::ble_device_base::GattClientListener

Public Member Functions

void set_backend (ble_device_base::BLEGattConnection *backend)
 Wire the platform backend. Called from codegen before setup.
 
conn_err_t read_characteristic (uint16_t handle)
 
conn_err_t write_characteristic (uint16_t handle, const uint8_t *data, size_t length, bool response)
 
conn_err_t read_descriptor (uint16_t handle)
 
conn_err_t write_descriptor (uint16_t handle, const uint8_t *data, size_t length, bool response)
 
conn_err_t notify_characteristic (uint16_t handle, bool enable)
 
conn_err_t update_connection_params (uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout)
 
void abort_service_stream (conn_err_t err)
 Streamer abort: latch the GATT cause, park the cursor, tear down.
 
void initiate_connection (uint8_t address_type)
 Start connecting with the API address type (BLE_ADDR_TYPE_* code space).
 
void disconnect ()
 
bool cancel_teardown ()
 A connect request racing a scheduled teardown: true when the backend had not started closing - the in-flight open resumes and reports connected.
 
bool is_paired () const
 
void set_unpaired ()
 
conn_err_t pair ()
 
void set_address (uint64_t address)
 
uint64_t get_address () const
 
const char * address_str () const
 
uint8_t get_connection_index () const
 
ClientState state () const
 
void set_state (ClientState st)
 
bool connected () const
 
void set_connection_type (ConnectionType ct)
 
bool has_gatt_services () const
 
void process_pending_services ()
 Stream any pending service-discovery batch (proxy loop; the backend owns the disconnect safety timer).
 
void on_connection_state (bool connected, uint16_t mtu, int error) override
 
void on_service_discovery_done (int error) override
 
void on_read_result (uint16_t handle, const uint8_t *data, uint16_t len, int error) override
 
void on_write_result (uint16_t handle, int error) override
 
void on_notify_state (uint16_t handle, bool enabled, int error) override
 
void on_notify_data (uint16_t handle, const uint8_t *data, uint16_t len) override
 
void on_pairing_result (int status) override
 
- Public Member Functions inherited from esphome::ble_device_base::GattClientListener

Protected Member Functions

void latch_pending_error_ (conn_err_t err)
 First cause wins: a later, less specific error must not overwrite it.
 
void latch_pending_ack_ (PendingAck kind, uint16_t handle, conn_err_t error=0)
 Latch a refused reply for the proxy drain.
 
void clear_pending_ack_ ()
 
void supersede_pending_ack_ (uint16_t handle, PendingAck kind)
 Drop an owed reply this re-ask makes stale.
 
bool has_pending_ack_ () const
 
void note_batch_stalled_ ()
 Warn on the stall's leading edge only.
 
void send_connected_reply_ ()
 Send the connected=true reply, latching it if the API refuses.
 
void flush_owed_replies_ ()
 Re-offer everything this slot owes.
 
void clear_owed_flags_ ()
 Drop everything this slot owes, in one write to the shared tail byte.
 
bool try_send_ack_ (PendingAck kind, uint16_t handle, conn_err_t error)
 Sole construction site for these replies, shared by send and retry.
 
void send_ack_ (PendingAck kind, uint16_t handle, conn_err_t error=0)
 First attempt: send, and latch it for the drain if the API refuses.
 
void send_gatt_error_ (uint16_t handle, conn_err_t error)
 Report a rejected request.
 
void flush_pending_ack_ ()
 Re-offer the owed reply; clears on success, stays owed on a refusal.
 
void age_pending_ack_ ()
 Advance the retry budget and abandon at the limit, without sending.
 
template<typename Backend >
void stream_pending_ (Backend *backend)
 
void park_service_stream_ ()
 Park the stream without services-done and free any held table: an interrupted stream must never be declared complete (the client's timeout arbitrates), and an owed done is dropped with it.
 
void send_service_for_discovery_ ()
 
void send_services_done_ ()
 Send services-done and settle the cursor: DONE when it lands (or no subscriber), SERVICES_DONE_PENDING on a refused frame (proxy drain retries).
 
void age_services_done_ ()
 Advance the retry budget and abandon at the limit, without sending.
 
void reset_connection_ (conn_err_t reason)
 
conn_err_t check_connected_op_ (const char *action, const char *type) const
 
void log_gatt_operation_error_ (const char *operation, uint16_t handle, int status)
 

Protected Attributes

bluetooth_proxy::BluetoothProxyproxy_ {nullptr}
 
ble_device_base::BLEGattConnectionbackend_ {nullptr}
 
int16_t send_service_ {INIT_SENDING_SERVICES}
 
uint16_t mtu_ {ble_device_base::DEFAULT_ATT_MTU}
 
uint64_t address_ {0}
 
conn_err_t pending_error_ {0}
 
conn_err_t pending_ack_error_ {0}
 
char address_str_ [MAC_ADDRESS_PRETTY_BUFFER_SIZE] {}
 
uint16_t pending_ack_handle_ {0}
 
ClientState state_: 3 {ClientState::IDLE}
 
uint8_t services_done_retries_: 5 {0}
 
uint8_t connection_index_: 4 {0}
 
ConnectionType connection_type_: 2 {ConnectionType::V1}
 
bool paired_: 1 {false}
 
bool services_discovered_: 1 {false}
 
PendingAck pending_ack_: 2 {PendingAck::PENDING_ACK_NONE}
 
bool batch_stalled_: 1 {false}
 Set while a refused batch is retrying, so only the first one warns.
 
bool connected_reply_owed_: 1 {false}
 An owed connected=true reply; the proxy's paced drain re-offers it.
 
uint8_t pending_ack_retries_ {0}
 

Detailed Description

Definition at line 38 of file bluetooth_connection_hub.h.

Member Function Documentation

◆ abort_service_stream()

void esphome::bluetooth_connection::BluetoothConnection::abort_service_stream ( conn_err_t err)
inline

Streamer abort: latch the GATT cause, park the cursor, tear down.

Definition at line 55 of file bluetooth_connection_hub.h.

◆ address_str()

const char * esphome::bluetooth_connection::BluetoothConnection::address_str ( ) const
inline

Definition at line 82 of file bluetooth_connection_hub.h.

◆ age_pending_ack_()

void esphome::bluetooth_connection::BluetoothConnection::age_pending_ack_ ( )
protected

Advance the retry budget and abandon at the limit, without sending.

Definition at line 299 of file bluetooth_connection_hub.cpp.

◆ age_services_done_()

void esphome::bluetooth_connection::BluetoothConnection::age_services_done_ ( )
protected

Advance the retry budget and abandon at the limit, without sending.

Definition at line 454 of file bluetooth_connection_hub.cpp.

◆ cancel_teardown()

bool esphome::bluetooth_connection::BluetoothConnection::cancel_teardown ( )
inline

A connect request racing a scheduled teardown: true when the backend had not started closing - the in-flight open resumes and reports connected.

False once the teardown owns the link.

Definition at line 69 of file bluetooth_connection_hub.h.

◆ check_connected_op_()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::check_connected_op_ ( const char * action,
const char * type ) const
protected

Definition at line 375 of file bluetooth_connection_hub.cpp.

◆ clear_owed_flags_()

void esphome::bluetooth_connection::BluetoothConnection::clear_owed_flags_ ( )
inlineprotected

Drop everything this slot owes, in one write to the shared tail byte.

Definition at line 163 of file bluetooth_connection_hub.h.

◆ clear_pending_ack_()

void esphome::bluetooth_connection::BluetoothConnection::clear_pending_ack_ ( )
inlineprotected

Definition at line 139 of file bluetooth_connection_hub.h.

◆ connected()

bool esphome::bluetooth_connection::BluetoothConnection::connected ( ) const
inline

Definition at line 87 of file bluetooth_connection_hub.h.

◆ disconnect()

void esphome::bluetooth_connection::BluetoothConnection::disconnect ( )

Definition at line 63 of file bluetooth_connection_hub.cpp.

◆ flush_owed_replies_()

void esphome::bluetooth_connection::BluetoothConnection::flush_owed_replies_ ( )
protected

Re-offer everything this slot owes.

One entry point so the proxy drain does not have to know which latches exist.

Definition at line 190 of file bluetooth_connection_hub.cpp.

◆ flush_pending_ack_()

void esphome::bluetooth_connection::BluetoothConnection::flush_pending_ack_ ( )
protected

Re-offer the owed reply; clears on success, stays owed on a refusal.

Definition at line 289 of file bluetooth_connection_hub.cpp.

◆ get_address()

uint64_t esphome::bluetooth_connection::BluetoothConnection::get_address ( ) const
inline

Definition at line 81 of file bluetooth_connection_hub.h.

◆ get_connection_index()

uint8_t esphome::bluetooth_connection::BluetoothConnection::get_connection_index ( ) const
inline

Definition at line 83 of file bluetooth_connection_hub.h.

◆ has_gatt_services()

bool esphome::bluetooth_connection::BluetoothConnection::has_gatt_services ( ) const
inline

Definition at line 99 of file bluetooth_connection_hub.h.

◆ has_pending_ack_()

bool esphome::bluetooth_connection::BluetoothConnection::has_pending_ack_ ( ) const
inlineprotected

Definition at line 149 of file bluetooth_connection_hub.h.

◆ initiate_connection()

void esphome::bluetooth_connection::BluetoothConnection::initiate_connection ( uint8_t address_type)

Start connecting with the API address type (BLE_ADDR_TYPE_* code space).

Failures report through the same reset path a failed open takes.

Definition at line 52 of file bluetooth_connection_hub.cpp.

◆ is_paired()

bool esphome::bluetooth_connection::BluetoothConnection::is_paired ( ) const
inline

Definition at line 76 of file bluetooth_connection_hub.h.

◆ latch_pending_ack_()

void esphome::bluetooth_connection::BluetoothConnection::latch_pending_ack_ ( PendingAck kind,
uint16_t handle,
conn_err_t error = 0 )
inlineprotected

Latch a refused reply for the proxy drain.

One slot per connection, newest wins: a GATT client works one request at a time, and a discarded reply falls back to the timeout it would have hit anyway.

Definition at line 133 of file bluetooth_connection_hub.h.

◆ latch_pending_error_()

void esphome::bluetooth_connection::BluetoothConnection::latch_pending_error_ ( conn_err_t err)
inlineprotected

First cause wins: a later, less specific error must not overwrite it.

Definition at line 124 of file bluetooth_connection_hub.h.

◆ log_gatt_operation_error_()

void esphome::bluetooth_connection::BluetoothConnection::log_gatt_operation_error_ ( const char * operation,
uint16_t handle,
int status )
protected

Definition at line 229 of file bluetooth_connection_hub.cpp.

◆ note_batch_stalled_()

void esphome::bluetooth_connection::BluetoothConnection::note_batch_stalled_ ( )
protected

Warn on the stall's leading edge only.

The batch is never lost (the caller rewinds the cursor), and a warning per attempt would add traffic to the connection already refusing frames. Both streamers route here.

Definition at line 234 of file bluetooth_connection_hub.cpp.

◆ notify_characteristic()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::notify_characteristic ( uint16_t handle,
bool enable )

Definition at line 420 of file bluetooth_connection_hub.cpp.

◆ on_connection_state()

void esphome::bluetooth_connection::BluetoothConnection::on_connection_state ( bool connected,
uint16_t mtu,
int error )
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 107 of file bluetooth_connection_hub.cpp.

◆ on_notify_data()

void esphome::bluetooth_connection::BluetoothConnection::on_notify_data ( uint16_t handle,
const uint8_t * data,
uint16_t len )
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 355 of file bluetooth_connection_hub.cpp.

◆ on_notify_state()

void esphome::bluetooth_connection::BluetoothConnection::on_notify_state ( uint16_t handle,
bool enabled,
int error )
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 343 of file bluetooth_connection_hub.cpp.

◆ on_pairing_result()

void esphome::bluetooth_connection::BluetoothConnection::on_pairing_result ( int status)
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 81 of file bluetooth_connection_hub.cpp.

◆ on_read_result()

void esphome::bluetooth_connection::BluetoothConnection::on_read_result ( uint16_t handle,
const uint8_t * data,
uint16_t len,
int error )
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 309 of file bluetooth_connection_hub.cpp.

◆ on_service_discovery_done()

void esphome::bluetooth_connection::BluetoothConnection::on_service_discovery_done ( int error)
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 173 of file bluetooth_connection_hub.cpp.

◆ on_write_result()

void esphome::bluetooth_connection::BluetoothConnection::on_write_result ( uint16_t handle,
int error )
overridevirtual

Reimplemented from esphome::ble_device_base::GattClientListener.

Definition at line 332 of file bluetooth_connection_hub.cpp.

◆ pair()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::pair ( )
inline

Definition at line 78 of file bluetooth_connection_hub.h.

◆ park_service_stream_()

void esphome::bluetooth_connection::BluetoothConnection::park_service_stream_ ( )
inlineprotected

Park the stream without services-done and free any held table: an interrupted stream must never be declared complete (the client's timeout arbitrates), and an owed done is dropped with it.

Definition at line 195 of file bluetooth_connection_hub.h.

◆ process_pending_services()

void esphome::bluetooth_connection::BluetoothConnection::process_pending_services ( )
inline

Stream any pending service-discovery batch (proxy loop; the backend owns the disconnect safety timer).

Definition at line 103 of file bluetooth_connection_hub.h.

◆ read_characteristic()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::read_characteristic ( uint16_t handle)

Definition at line 384 of file bluetooth_connection_hub.cpp.

◆ read_descriptor()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::read_descriptor ( uint16_t handle)

Definition at line 401 of file bluetooth_connection_hub.cpp.

◆ reset_connection_()

void esphome::bluetooth_connection::BluetoothConnection::reset_connection_ ( conn_err_t reason)
protected

Definition at line 91 of file bluetooth_connection_hub.cpp.

◆ send_ack_()

void esphome::bluetooth_connection::BluetoothConnection::send_ack_ ( PendingAck kind,
uint16_t handle,
conn_err_t error = 0 )
protected

First attempt: send, and latch it for the drain if the API refuses.

Definition at line 274 of file bluetooth_connection_hub.cpp.

◆ send_connected_reply_()

void esphome::bluetooth_connection::BluetoothConnection::send_connected_reply_ ( )
protected

Send the connected=true reply, latching it if the API refuses.

Rebuilt from address_ and mtu_, so the latch is one bit; a dropped confirmation leaves the client timing out while this slot holds a live link. No retry bound: the slot's lifetime is the bound (teardown clears the flag).

Definition at line 216 of file bluetooth_connection_hub.cpp.

◆ send_gatt_error_()

void esphome::bluetooth_connection::BluetoothConnection::send_gatt_error_ ( uint16_t handle,
conn_err_t error )
inlineprotected

Report a rejected request.

Latched like a completion reply, so a refused frame does not strand the client for its whole timeout.

Definition at line 174 of file bluetooth_connection_hub.h.

◆ send_service_for_discovery_()

void esphome::bluetooth_connection::BluetoothConnection::send_service_for_discovery_ ( )
protected

Definition at line 462 of file bluetooth_connection_hub.cpp.

◆ send_services_done_()

void esphome::bluetooth_connection::BluetoothConnection::send_services_done_ ( )
protected

Send services-done and settle the cursor: DONE when it lands (or no subscriber), SERVICES_DONE_PENDING on a refused frame (proxy drain retries).

Callers release the table first; the message needs only the address.

Definition at line 438 of file bluetooth_connection_hub.cpp.

◆ set_address()

void esphome::bluetooth_connection::BluetoothConnection::set_address ( uint64_t address)

Definition at line 36 of file bluetooth_connection_hub.cpp.

◆ set_backend()

void esphome::bluetooth_connection::BluetoothConnection::set_backend ( ble_device_base::BLEGattConnection * backend)
inline

Wire the platform backend. Called from codegen before setup.

Definition at line 41 of file bluetooth_connection_hub.h.

◆ set_connection_type()

void esphome::bluetooth_connection::BluetoothConnection::set_connection_type ( ConnectionType ct)
inline

Definition at line 88 of file bluetooth_connection_hub.h.

◆ set_state()

void esphome::bluetooth_connection::BluetoothConnection::set_state ( ClientState st)
inline

Definition at line 86 of file bluetooth_connection_hub.h.

◆ set_unpaired()

void esphome::bluetooth_connection::BluetoothConnection::set_unpaired ( )
inline

Definition at line 77 of file bluetooth_connection_hub.h.

◆ state()

ClientState esphome::bluetooth_connection::BluetoothConnection::state ( ) const
inline

Definition at line 85 of file bluetooth_connection_hub.h.

◆ stream_pending_()

template<typename Backend >
void esphome::bluetooth_connection::BluetoothConnection::stream_pending_ ( Backend * backend)
inlineprotected

Definition at line 185 of file bluetooth_connection_hub.h.

◆ supersede_pending_ack_()

void esphome::bluetooth_connection::BluetoothConnection::supersede_pending_ack_ ( uint16_t handle,
PendingAck kind )
inlineprotected

Drop an owed reply this re-ask makes stale.

Clients match futures on response type as well as handle, so an owed error (which resolves any op on the handle) is cleared by any re-ask, other kinds only by their own.

Definition at line 143 of file bluetooth_connection_hub.h.

◆ try_send_ack_()

bool esphome::bluetooth_connection::BluetoothConnection::try_send_ack_ ( PendingAck kind,
uint16_t handle,
conn_err_t error )
protected

Sole construction site for these replies, shared by send and retry.

Sole construction site, so a re-offer cannot drift from the original.

Definition at line 252 of file bluetooth_connection_hub.cpp.

◆ update_connection_params()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::update_connection_params ( uint16_t min_interval,
uint16_t max_interval,
uint16_t latency,
uint16_t timeout )

Definition at line 429 of file bluetooth_connection_hub.cpp.

◆ write_characteristic()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::write_characteristic ( uint16_t handle,
const uint8_t * data,
size_t length,
bool response )

Definition at line 392 of file bluetooth_connection_hub.cpp.

◆ write_descriptor()

conn_err_t esphome::bluetooth_connection::BluetoothConnection::write_descriptor ( uint16_t handle,
const uint8_t * data,
size_t length,
bool response )

Definition at line 411 of file bluetooth_connection_hub.cpp.

Field Documentation

◆ address_

uint64_t esphome::bluetooth_connection::BluetoothConnection::address_ {0}
protected

Definition at line 227 of file bluetooth_connection_hub.h.

◆ address_str_

char esphome::bluetooth_connection::BluetoothConnection::address_str_[MAC_ADDRESS_PRETTY_BUFFER_SIZE] {}
protected

Definition at line 234 of file bluetooth_connection_hub.h.

◆ backend_

ble_device_base::BLEGattConnection* esphome::bluetooth_connection::BluetoothConnection::backend_ {nullptr}
protected

Definition at line 219 of file bluetooth_connection_hub.h.

◆ batch_stalled_

bool esphome::bluetooth_connection::BluetoothConnection::batch_stalled_
protected

Set while a refused batch is retrying, so only the first one warns.

Definition at line 258 of file bluetooth_connection_hub.h.

◆ connected_reply_owed_

bool esphome::bluetooth_connection::BluetoothConnection::connected_reply_owed_
protected

An owed connected=true reply; the proxy's paced drain re-offers it.

Definition at line 260 of file bluetooth_connection_hub.h.

◆ connection_index_

uint8_t esphome::bluetooth_connection::BluetoothConnection::connection_index_
protected

Definition at line 251 of file bluetooth_connection_hub.h.

◆ connection_type_

ConnectionType esphome::bluetooth_connection::BluetoothConnection::connection_type_
protected

Definition at line 252 of file bluetooth_connection_hub.h.

◆ mtu_

uint16_t esphome::bluetooth_connection::BluetoothConnection::mtu_ {ble_device_base::DEFAULT_ATT_MTU}
protected

Definition at line 224 of file bluetooth_connection_hub.h.

◆ paired_

bool esphome::bluetooth_connection::BluetoothConnection::paired_
protected

Definition at line 253 of file bluetooth_connection_hub.h.

◆ pending_ack_

PendingAck esphome::bluetooth_connection::BluetoothConnection::pending_ack_
protected

Definition at line 256 of file bluetooth_connection_hub.h.

◆ pending_ack_error_

conn_err_t esphome::bluetooth_connection::BluetoothConnection::pending_ack_error_ {0}
protected

Definition at line 231 of file bluetooth_connection_hub.h.

◆ pending_ack_handle_

uint16_t esphome::bluetooth_connection::BluetoothConnection::pending_ack_handle_ {0}
protected

Definition at line 237 of file bluetooth_connection_hub.h.

◆ pending_ack_retries_

uint8_t esphome::bluetooth_connection::BluetoothConnection::pending_ack_retries_ {0}
protected

Definition at line 264 of file bluetooth_connection_hub.h.

◆ pending_error_

conn_err_t esphome::bluetooth_connection::BluetoothConnection::pending_error_ {0}
protected

Definition at line 228 of file bluetooth_connection_hub.h.

◆ proxy_

bluetooth_proxy::BluetoothProxy* esphome::bluetooth_connection::BluetoothConnection::proxy_ {nullptr}
protected

Definition at line 218 of file bluetooth_connection_hub.h.

◆ send_service_

int16_t esphome::bluetooth_connection::BluetoothConnection::send_service_ {INIT_SENDING_SERVICES}
protected

Definition at line 223 of file bluetooth_connection_hub.h.

◆ services_discovered_

bool esphome::bluetooth_connection::BluetoothConnection::services_discovered_
protected

Definition at line 254 of file bluetooth_connection_hub.h.

◆ services_done_retries_

uint8_t esphome::bluetooth_connection::BluetoothConnection::services_done_retries_
protected

Definition at line 250 of file bluetooth_connection_hub.h.

◆ state_

ClientState esphome::bluetooth_connection::BluetoothConnection::state_
protected

Definition at line 248 of file bluetooth_connection_hub.h.


The documentation for this class was generated from the following files: