ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ble_client_base.cpp
Go to the documentation of this file.
1#include "ble_client_base.h"
2
4#include "esphome/core/log.h"
5
6#ifdef USE_ESP32
7
8#include <esp_gap_ble_api.h>
9#include <esp_gatt_defs.h>
10#include <esp_gattc_api.h>
11
13
14ESPHOME_LOG_TAG(TAG, "esp32_ble_client");
15
16// Connection parameters are shared with the other GATT client backends
17// (ble_device_base/ble_client_state.h) so the platforms cannot drift.
18using ble_device_base::FAST_CONN_TIMEOUT;
19using ble_device_base::FAST_MAX_CONN_INTERVAL;
20using ble_device_base::FAST_MIN_CONN_INTERVAL;
21using ble_device_base::MEDIUM_CONN_TIMEOUT;
22using ble_device_base::MEDIUM_MAX_CONN_INTERVAL;
23using ble_device_base::MEDIUM_MIN_CONN_INTERVAL;
24static constexpr uint32_t DISCONNECTING_TIMEOUT = 10000; // 10s
25static const esp_bt_uuid_t NOTIFY_DESC_UUID = {
26 .len = ESP_UUID_LEN_16,
27 .uuid =
28 {
29 .uuid16 = ESP_GATT_UUID_CHAR_CLIENT_CONFIG,
30 },
31};
32
34 static uint8_t connection_index = 0;
35 this->connection_index_ = connection_index++;
36}
37
39 ESP_LOGV(TAG, "[%d] [%s] Set state %d", this->connection_index_, this->address_str_, (int) st);
40 ESPBTClient::set_state(st);
41}
42
44 if (!esp32_ble::global_ble->is_active()) {
45 // ble_before_disabled_event_handler() resets the client.
46 return;
47 }
48 if (this->state() == espbt::ClientState::INIT) {
49 auto ret = esp_ble_gattc_app_register(this->app_id);
50 if (ret) {
51 ESP_LOGE(TAG, "gattc app register failed. app_id=%d code=%d", this->app_id, ret);
52 this->mark_failed();
53 }
54 this->set_state(espbt::ClientState::IDLE);
55 }
56 // If idle, we can disable the loop as connect()
57 // will enable it again when a connection is needed.
58 else if (this->state() == espbt::ClientState::IDLE) {
59 this->disable_loop();
60 } else if (this->state() == espbt::ClientState::DISCONNECTING &&
61 (millis() - this->disconnecting_started_) > DISCONNECTING_TIMEOUT) {
62 ESP_LOGE(TAG, "[%d] [%s] Timeout waiting for CLOSE_EVT after disconnect, forcing IDLE", this->connection_index_,
63 this->address_str_);
64 // release_services() must be called before set_idle_() — if we entered DISCONNECTING
65 // via unconditional_disconnect() (which doesn't call release_services()), and ESP-IDF
66 // never delivered CLOSE_EVT/DISCONNECT_EVT, services would leak without this call.
67 this->release_services();
68 this->set_idle_();
69 this->on_disconnect_complete(ESP_GATT_CONN_TIMEOUT);
70 }
71}
72
74
76 auto st = this->state();
77 if (st != espbt::ClientState::IDLE && st != espbt::ClientState::INIT) {
78 // No CLOSE_EVT will come: free the services and settle the link.
79 this->release_services();
80 this->set_idle_();
81 this->on_disconnect_complete(ESP_GATT_CONN_TERMINATE_LOCAL_HOST);
82 }
83 // The interface belongs to the torn-down stack.
84 this->gattc_if_ = ESP_GATT_IF_NONE;
85 this->set_state(espbt::ClientState::INIT);
86 // An idle client runs no loop; the INIT branch must run to register again.
87 this->enable_loop();
88}
89
91 ESP_LOGCONFIG(TAG,
92 " Address: %s\n"
93 " Auto-Connect: %s\n"
94 " State: %s",
95 this->address_str(), TRUEFALSE(this->auto_connect_), espbt::client_state_to_string(this->state()));
96 if (this->status_ == ESP_GATT_NO_RESOURCES) {
97 ESP_LOGE(TAG, " Failed due to no resources. Try to reduce number of BLE clients in config.");
98 } else if (this->status_ != ESP_GATT_OK) {
99 ESP_LOGW(TAG, " Failed due to error code %d", this->status_);
100 }
101}
102
103#ifdef USE_ESP32_BLE_DEVICE
105 if (!this->auto_connect_)
106 return false;
107 if (this->address_ == 0 || device.address_uint64() != this->address_)
108 return false;
109 if (this->state() != espbt::ClientState::IDLE)
110 return false;
111 // Not registered on this stack yet; promoting now would stop the scan for a
112 // connect that connect() rejects anyway.
113 if (this->gattc_if_ == ESP_GATT_IF_NONE)
114 return false;
115
116 this->log_event_("Found device");
117 if (ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_DEBUG)
119
120 this->set_state(espbt::ClientState::DISCOVERED);
121 this->set_address(device.address_uint64());
122 this->remote_addr_type_ = device.get_address_type();
123 return true;
124}
125#endif
126
128 // Prevent duplicate connection attempts or connecting while still disconnecting
129 if (this->state() == espbt::ClientState::CONNECTING || this->state() == espbt::ClientState::CONNECTED ||
130 this->state() == espbt::ClientState::ESTABLISHED) {
131 ESP_LOGW(TAG, "[%d] [%s] Connection already in progress, state=%s", this->connection_index_, this->address_str_,
132 espbt::client_state_to_string(this->state()));
133 return;
134 } else if (this->state() == espbt::ClientState::DISCONNECTING) {
135 ESP_LOGW(TAG, "[%d] [%s] Cannot connect, still waiting for CLOSE_EVT to complete disconnect",
136 this->connection_index_, this->address_str_);
137 return;
138 }
139 if (this->gattc_if_ == ESP_GATT_IF_NONE) {
140 // Bluedroid drops an open on an unknown interface without any event.
141 this->log_warning_("Connect rejected, GATT app not registered");
142 // INIT stays so loop() still registers; only a promoted client goes back.
143 if (this->state() == espbt::ClientState::DISCOVERED) {
144 this->set_state(espbt::ClientState::IDLE);
145 }
146 return;
147 }
148 ESP_LOGI(TAG, "[%d] [%s] 0x%02x Connecting", this->connection_index_, this->address_str_, this->remote_addr_type_);
149 this->paired_ = false;
150 // A registration whose event never arrived must not block this connection's release.
151 this->services_released_ = false;
152 this->pending_notify_regs_ = 0;
153 // A CONNECT_EVT seen while idle can leave the id of a link this attempt does not own.
154 this->conn_id_ = UNSET_CONN_ID;
155 // Enable loop for state processing
156 this->enable_loop();
157 // Immediately transition to CONNECTING to prevent duplicate connection attempts
158 this->set_state(espbt::ClientState::CONNECTING);
159
160 // Determine connection parameters based on connection type
161 if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
162 // V3 without cache needs fast params for service discovery
163 this->set_conn_params_(FAST_MIN_CONN_INTERVAL, FAST_MAX_CONN_INTERVAL, 0, FAST_CONN_TIMEOUT, "fast");
164 } else if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
165 // V3 with cache can use medium params
166 this->set_conn_params_(MEDIUM_MIN_CONN_INTERVAL, MEDIUM_MAX_CONN_INTERVAL, 0, MEDIUM_CONN_TIMEOUT, "medium");
167 }
168 // For V1/Legacy, don't set params - use ESP-IDF defaults
169
170 // Open the connection
171 auto ret = esp_ble_gattc_open(this->gattc_if_, this->remote_bda_, this->remote_addr_type_, true);
173}
174
175esp_err_t BLEClientBase::pair() { return esp_ble_set_encryption(this->remote_bda_, ESP_BLE_SEC_ENCRYPT); }
176
178 if (this->state() == espbt::ClientState::IDLE || this->state() == espbt::ClientState::DISCONNECTING) {
179 ESP_LOGI(TAG, "[%d] [%s] Disconnect requested, but already %s", this->connection_index_, this->address_str_,
180 espbt::client_state_to_string(this->state()));
181 return;
182 }
183 if (this->state() == espbt::ClientState::CONNECTING || this->conn_id_ == UNSET_CONN_ID) {
184 ESP_LOGD(TAG, "[%d] [%s] Disconnect before connected, disconnect scheduled", this->connection_index_,
185 this->address_str_);
186 this->want_disconnect_ = true;
187 return;
188 }
190}
191
193 // Disconnect without checking the state.
194 ESP_LOGI(TAG, "[%d] [%s] Disconnecting (conn_id: %d).", this->connection_index_, this->address_str_, this->conn_id_);
195 if (this->state() == espbt::ClientState::DISCONNECTING) {
196 this->log_error_("Already disconnecting");
197 return;
198 }
199 if (this->conn_id_ == UNSET_CONN_ID) {
200 this->log_error_("conn id unset, cannot disconnect");
201 return;
202 }
203 auto err = esp_ble_gattc_close(this->gattc_if_, this->conn_id_);
204 if (err != ESP_OK) {
205 //
206 // This is a fatal error, but we can't do anything about it
207 // and it likely means the BLE stack is in a bad state.
208 //
209 // In the future we might consider App.reboot() here since
210 // the BLE stack is in an indeterminate state.
211 //
212 this->log_gattc_warning_("esp_ble_gattc_close", err);
213 }
214
215 if (this->state() == espbt::ClientState::DISCOVERED) {
216 this->set_address(0);
217 this->set_state(espbt::ClientState::IDLE);
218 } else {
219 this->set_disconnecting_();
220 }
221}
222
224#ifdef USE_ESP32_BLE_DEVICE
225 for (auto &svc : this->services_)
226 delete svc; // NOLINT(cppcoreguidelines-owning-memory)
227 this->services_.clear();
228#endif
229#ifndef CONFIG_BT_GATTC_CACHE_NVS_FLASH
230 // Only the cache clean makes the stack's database unsafe to walk.
231 this->services_released_ = true;
232 // A stack on its way down frees its own cache.
233 if (esp32_ble::global_ble->is_active()) {
234 esp_ble_gattc_cache_clean(this->remote_bda_);
235 }
236#endif
237}
238
239esp_err_t BLEClientBase::register_for_notify(uint16_t char_handle) {
240 esp_err_t err = esp_ble_gattc_register_for_notify(this->gattc_if_, this->remote_bda_, char_handle);
241 if (err != ESP_OK)
242 return err;
243 if (this->pending_notify_regs_ == UINT8_MAX) {
244 // Saturating undercounts, so the release can run before the last registration completes.
245 // Wrapping to zero would undercount by the full range instead, which is worse.
246 this->log_warning_("Too many outstanding notify registrations to track");
247 return err;
248 }
249 this->pending_notify_regs_++;
250 return err;
251}
252
253void BLEClientBase::log_event_(const char *name) {
254 ESP_LOGD(TAG, "[%d] [%s] %s", this->connection_index_, this->address_str_, name);
255}
256
258 ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_%s_EVT", this->connection_index_, this->address_str_, name);
259}
260
262 // Data transfer events are logged at VERBOSE level because logging to UART creates
263 // delays that cause timing issues during time-sensitive BLE operations. This is
264 // especially problematic during pairing or firmware updates which require rapid
265 // writes to many characteristics - the log spam can cause these operations to fail.
266 ESP_LOGV(TAG, "[%d] [%s] ESP_GATTC_%s_EVT", this->connection_index_, this->address_str_, name);
267}
268
269void BLEClientBase::log_gattc_warning_(const char *operation, esp_gatt_status_t status) {
270 ESP_LOGW(TAG, "[%d] [%s] %s error, status=%d", this->connection_index_, this->address_str_, operation, status);
271}
272
273void BLEClientBase::log_gattc_warning_(const char *operation, esp_err_t err) {
274 ESP_LOGW(TAG, "[%d] [%s] %s error, status=%d", this->connection_index_, this->address_str_, operation, err);
275}
276
277void BLEClientBase::log_connection_params_(const char *param_type) {
278 ESP_LOGD(TAG, "[%d] [%s] %s conn params", this->connection_index_, this->address_str_, param_type);
279}
280
282 if (ret) {
283 this->log_gattc_warning_("esp_ble_gattc_open", ret);
284 // Don't use set_idle_() here — CONNECT_EVT never fired so conn_id_ is still UNSET_CONN_ID.
285 this->set_state(espbt::ClientState::IDLE);
286 }
287}
288
290 ESP_LOGE(TAG, "[%d] [%s] %s", this->connection_index_, this->address_str_, message);
291}
292
293void BLEClientBase::log_error_(const char *message, int code) {
294 ESP_LOGE(TAG, "[%d] [%s] %s=%d", this->connection_index_, this->address_str_, message, code);
295}
296
298 ESP_LOGW(TAG, "[%d] [%s] %s", this->connection_index_, this->address_str_, message);
299}
300
301esp_err_t BLEClientBase::update_conn_params_(uint16_t min_interval, uint16_t max_interval, uint16_t latency,
302 uint16_t timeout, const char *param_type) {
303 esp_ble_conn_update_params_t conn_params = {};
304 memcpy(conn_params.bda, this->remote_bda_, sizeof(esp_bd_addr_t));
305 conn_params.min_int = min_interval;
306 conn_params.max_int = max_interval;
307 conn_params.latency = latency;
308 conn_params.timeout = timeout;
309 this->log_connection_params_(param_type);
310 esp_err_t err = esp_ble_gap_update_conn_params(&conn_params);
311 if (err != ESP_OK) {
312 this->log_gattc_warning_("esp_ble_gap_update_conn_params", err);
313 }
314 return err;
315}
316
317void BLEClientBase::set_conn_params_(uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout,
318 const char *param_type) {
319 // Set preferred connection parameters before connecting
320 // These will be used when establishing the connection
321 this->log_connection_params_(param_type);
322 esp_err_t err = esp_ble_gap_set_prefer_conn_params(this->remote_bda_, min_interval, max_interval, latency, timeout);
323 if (err != ESP_OK) {
324 this->log_gattc_warning_("esp_ble_gap_set_prefer_conn_params", err);
325 }
326}
327
328bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t esp_gattc_if,
329 esp_ble_gattc_cb_param_t *param) {
330 if (event == ESP_GATTC_REG_EVT && this->app_id != param->reg.app_id)
331 return false;
332 if (event != ESP_GATTC_REG_EVT && esp_gattc_if != ESP_GATT_IF_NONE && esp_gattc_if != this->gattc_if_)
333 return false;
334
335 ESP_LOGV(TAG, "[%d] [%s] gattc_event_handler: event=%d gattc_if=%d", this->connection_index_, this->address_str_,
336 event, esp_gattc_if);
337
338 switch (event) {
339 case ESP_GATTC_REG_EVT: {
340 if (param->reg.status == ESP_GATT_OK) {
341 ESP_LOGV(TAG, "[%d] [%s] gattc registered app id %d", this->connection_index_, this->address_str_,
342 this->app_id);
343 this->gattc_if_ = esp_gattc_if;
344 } else {
345 this->log_error_("gattc app registration failed status", param->reg.status);
346 this->status_ = param->reg.status;
347 this->mark_failed();
348 }
349 break;
350 }
351 case ESP_GATTC_OPEN_EVT: {
352 if (!this->check_addr(param->open.remote_bda))
353 return false;
354 this->log_gattc_lifecycle_event_("OPEN");
355 this->service_count_ = 0;
356
357 // ESP-IDF's BLE stack may send ESP_GATTC_OPEN_EVT after esp_ble_gattc_open() returns an
358 // error, if the error occurred at the BTA/GATT layer. This can result in the event
359 // arriving after we've already transitioned to IDLE state.
360 if (this->state() == espbt::ClientState::IDLE) {
361 ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_OPEN_EVT in IDLE state (status=%d), ignoring", this->connection_index_,
362 this->address_str_, param->open.status);
363 break;
364 }
365
366 if (this->state() != espbt::ClientState::CONNECTING) {
367 ESP_LOGE(TAG, "[%d] [%s] ESP_GATTC_OPEN_EVT in %s state (status=%d)", this->connection_index_,
368 this->address_str_, espbt::client_state_to_string(this->state()), param->open.status);
369 }
370 if (param->open.status != ESP_GATT_OK && param->open.status != ESP_GATT_ALREADY_OPEN) {
371 this->log_gattc_warning_("Connection open", param->open.status);
372 // Connection was never established so CLOSE_EVT may not follow
373 this->set_idle_();
374 break;
375 }
376 // An open on a link that is already up sends no CONNECT_EVT, so take the id here.
377 this->conn_id_ = param->open.conn_id;
378 if (this->want_disconnect_) {
379 // Disconnect was requested after connecting started,
380 // but before the connection was established. Now that we have
381 // this->conn_id_ set, we can disconnect it.
382 // Don't reset conn_id_ here — CLOSE_EVT needs it to match and call set_idle_().
384 break;
385 }
386 // MTU negotiation already started in ESP_GATTC_CONNECT_EVT
387 this->set_state(espbt::ClientState::CONNECTED);
388 ESP_LOGI(TAG, "[%d] [%s] Connection open", this->connection_index_, this->address_str_);
389 if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
390 // Cached connections already connected with medium parameters, no update needed
391 // only set our state, subclients might have more stuff to do yet.
392 this->set_state_internal_(espbt::ClientState::ESTABLISHED);
393 break;
394 }
395 // For V3_WITHOUT_CACHE, we already set fast params before connecting
396 // No need to update them again here
397 this->log_event_("Searching for services");
398 esp_ble_gattc_search_service(esp_gattc_if, param->open.conn_id, nullptr);
399 break;
400 }
401 case ESP_GATTC_CONNECT_EVT: {
402 if (!this->check_addr(param->connect.remote_bda))
403 return false;
404 this->log_gattc_lifecycle_event_("CONNECT");
405 this->conn_id_ = param->connect.conn_id;
406 // Start MTU negotiation immediately as recommended by ESP-IDF examples
407 // (gatt_client, ble_throughput) which call esp_ble_gattc_send_mtu_req in
408 // ESP_GATTC_CONNECT_EVT instead of waiting for ESP_GATTC_OPEN_EVT.
409 // This saves ~3ms in the connection process.
410 auto ret = esp_ble_gattc_send_mtu_req(this->gattc_if_, param->connect.conn_id);
411 if (ret) {
412 this->log_gattc_warning_("esp_ble_gattc_send_mtu_req", ret);
413 }
414 break;
415 }
416 case ESP_GATTC_DISCONNECT_EVT: {
417 if (!this->check_addr(param->disconnect.remote_bda))
418 return false;
419 // Check if we were disconnected while waiting for service discovery
420 if (param->disconnect.reason == ESP_GATT_CONN_TERMINATE_PEER_USER &&
421 this->state() == espbt::ClientState::CONNECTED) {
422 this->log_warning_("Remote closed during discovery");
423 } else {
424 ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_DISCONNECT_EVT, reason 0x%02x", this->connection_index_, this->address_str_,
425 param->disconnect.reason);
426 }
427 // IDLE: CLOSE_EVT (active close) already cleaned up. No conn_id: no CONNECT_EVT for this attempt yet,
428 // so the event is left over from the previous link or precedes a failed open that OPEN_EVT handles.
429 if (this->state() == espbt::ClientState::IDLE || this->conn_id_ == UNSET_CONN_ID) {
430 this->log_event_("DISCONNECT_EVT with no live link, ignoring");
431 break;
432 }
433 // For passive disconnects (remote device disconnected or link lost),
434 // DISCONNECT_EVT arrives first. Don't transition to IDLE yet — wait for
435 // CLOSE_EVT to ensure the controller has fully freed resources (L2CAP
436 // channels, ATT resources, HCI connection handle). Transitioning to IDLE
437 // here would allow reconnection before cleanup is complete, causing the
438 // controller to reject the new connection (status=133) or crash with
439 // ASSERT_PARAM in lld_evt.c.
440 this->release_services();
441 this->set_disconnecting_();
442 break;
443 }
444
445 case ESP_GATTC_CFG_MTU_EVT: {
446 if (this->conn_id_ != param->cfg_mtu.conn_id)
447 return false;
448 if (param->cfg_mtu.status != ESP_GATT_OK) {
449 ESP_LOGW(TAG, "[%d] [%s] cfg_mtu failed, mtu %d, status %d", this->connection_index_, this->address_str_,
450 param->cfg_mtu.mtu, param->cfg_mtu.status);
451 // No state change required here - disconnect event will follow if needed.
452 break;
453 }
454 ESP_LOGD(TAG, "[%d] [%s] cfg_mtu status %d, mtu %d", this->connection_index_, this->address_str_,
455 param->cfg_mtu.status, param->cfg_mtu.mtu);
456 this->mtu_ = param->cfg_mtu.mtu;
457 break;
458 }
459 case ESP_GATTC_CLOSE_EVT: {
460 if (this->conn_id_ != param->close.conn_id)
461 return false;
462 this->log_gattc_lifecycle_event_("CLOSE");
463 this->release_services();
464 this->set_idle_();
465 this->on_disconnect_complete(param->close.reason);
466 break;
467 }
468 case ESP_GATTC_SEARCH_RES_EVT: {
469 if (this->conn_id_ != param->search_res.conn_id)
470 return false;
471 this->service_count_++;
472 if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
473 // V3 clients don't need services initialized since
474 // as they use the ESP APIs to get services.
475 break;
476 }
477#ifdef USE_ESP32_BLE_DEVICE
478 BLEService *ble_service = new BLEService(); // NOLINT(cppcoreguidelines-owning-memory)
479 ble_service->uuid = espbt::ESPBTUUID::from_uuid(param->search_res.srvc_id.uuid);
480 ble_service->start_handle = param->search_res.start_handle;
481 ble_service->end_handle = param->search_res.end_handle;
482 ble_service->client = this;
483 this->services_.push_back(ble_service);
484#endif
485 break;
486 }
487 case ESP_GATTC_SEARCH_CMPL_EVT: {
488 if (this->conn_id_ != param->search_cmpl.conn_id)
489 return false;
490 this->log_gattc_lifecycle_event_("SEARCH_CMPL");
491 // For V3_WITHOUT_CACHE, switch back to medium connection parameters after service discovery
492 // This balances performance with bandwidth usage after the critical discovery phase
493 if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
494 this->update_conn_params_(MEDIUM_MIN_CONN_INTERVAL, MEDIUM_MAX_CONN_INTERVAL, 0, MEDIUM_CONN_TIMEOUT, "medium");
495 } else if (this->connection_type_ != espbt::ConnectionType::V3_WITH_CACHE) {
496#ifdef USE_ESP32_BLE_DEVICE
497#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERBOSE
498 for (auto &svc : this->services_) {
499 char uuid_buf[espbt::UUID_STR_LEN];
500 svc->uuid.to_str(uuid_buf);
501 ESP_LOGV(TAG, "[%d] [%s] Service UUID: %s", this->connection_index_, this->address_str_, uuid_buf);
502 ESP_LOGV(TAG, "[%d] [%s] start_handle: 0x%x end_handle: 0x%x", this->connection_index_, this->address_str_,
503 svc->start_handle, svc->end_handle);
504 }
505#endif
506#endif
507 }
508 ESP_LOGI(TAG, "[%d] [%s] Service discovery complete", this->connection_index_, this->address_str_);
509 this->set_state_internal_(espbt::ClientState::ESTABLISHED);
510 break;
511 }
512 case ESP_GATTC_READ_DESCR_EVT: {
513 if (this->conn_id_ != param->write.conn_id)
514 return false;
515 this->log_gattc_data_event_("READ_DESCR");
516 break;
517 }
518 case ESP_GATTC_WRITE_DESCR_EVT: {
519 if (this->conn_id_ != param->write.conn_id)
520 return false;
521 this->log_gattc_data_event_("WRITE_DESCR");
522 break;
523 }
524 case ESP_GATTC_WRITE_CHAR_EVT: {
525 if (this->conn_id_ != param->write.conn_id)
526 return false;
527 this->log_gattc_data_event_("WRITE_CHAR");
528 break;
529 }
530 case ESP_GATTC_READ_CHAR_EVT: {
531 if (this->conn_id_ != param->read.conn_id)
532 return false;
533 this->log_gattc_data_event_("READ_CHAR");
534 break;
535 }
536 case ESP_GATTC_NOTIFY_EVT: {
537 if (this->conn_id_ != param->notify.conn_id)
538 return false;
539 this->log_gattc_data_event_("NOTIFY");
540 break;
541 }
542 case ESP_GATTC_REG_FOR_NOTIFY_EVT: {
543 this->log_gattc_data_event_("REG_FOR_NOTIFY");
544 // The event carries no conn_id, so this is the only place the request can be retired.
545 if (this->pending_notify_regs_ > 0)
546 this->pending_notify_regs_--;
547 if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE ||
548 this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
549 // Client is responsible for flipping the descriptor value
550 // when using the cache
551 break;
552 }
553 if (this->services_released_) {
554 // The lookup below walks the freed GATT cache, and Bluedroid asserts on it rather than erroring.
555 this->log_warning_("REG_FOR_NOTIFY after services released, notifications not enabled");
556 break;
557 }
558 esp_gattc_descr_elem_t desc_result;
559 uint16_t count = 1;
560 esp_gatt_status_t descr_status = esp_ble_gattc_get_descr_by_char_handle(
561 this->gattc_if_, this->conn_id_, param->reg_for_notify.handle, NOTIFY_DESC_UUID, &desc_result, &count);
562 if (descr_status != ESP_GATT_OK) {
563 this->log_gattc_warning_("esp_ble_gattc_get_descr_by_char_handle", descr_status);
564 break;
565 }
566 esp_gattc_char_elem_t char_result;
567 esp_gatt_status_t char_status =
568 esp_ble_gattc_get_all_char(this->gattc_if_, this->conn_id_, param->reg_for_notify.handle,
569 param->reg_for_notify.handle, &char_result, &count, 0);
570 if (char_status != ESP_GATT_OK) {
571 this->log_gattc_warning_("esp_ble_gattc_get_all_char", char_status);
572 break;
573 }
574
575 /*
576 1 = notify
577 2 = indicate
578 */
579 uint16_t notify_en = char_result.properties & ESP_GATT_CHAR_PROP_BIT_NOTIFY ? 1 : 2;
580 esp_err_t status =
581 esp_ble_gattc_write_char_descr(this->gattc_if_, this->conn_id_, desc_result.handle, sizeof(notify_en),
582 (uint8_t *) &notify_en, ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE);
583 ESP_LOGV(TAG, "Wrote notify descriptor %d, properties=%d", notify_en, char_result.properties);
584 if (status) {
585 this->log_gattc_warning_("esp_ble_gattc_write_char_descr", status);
586 }
587 break;
588 }
589
590 case ESP_GATTC_UNREG_FOR_NOTIFY_EVT: {
591 this->log_gattc_data_event_("UNREG_FOR_NOTIFY");
592 break;
593 }
594
595 default:
596 // Unknown events logged at VERBOSE to avoid UART delays during time-sensitive operations
597 ESP_LOGV(TAG, "[%d] [%s] Event %d", this->connection_index_, this->address_str_, event);
598 break;
599 }
600 return true;
601}
602
603// clients can't call defer() directly since it's protected.
604void BLEClientBase::run_later(std::function<void()> &&f) { // NOLINT
605 this->defer(std::move(f));
606}
607
608void BLEClientBase::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {
609 switch (event) {
610 // This event is sent by the server when it requests security
611 case ESP_GAP_BLE_SEC_REQ_EVT:
612 if (!this->check_addr(param->ble_security.auth_cmpl.bd_addr))
613 return;
614 ESP_LOGV(TAG, "[%d] [%s] ESP_GAP_BLE_SEC_REQ_EVT %x", this->connection_index_, this->address_str_, event);
615 esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
616 break;
617 // This event is sent once authentication has completed
618 case ESP_GAP_BLE_AUTH_CMPL_EVT:
619 if (!this->check_addr(param->ble_security.auth_cmpl.bd_addr))
620 return;
621 char addr_str[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
622 format_mac_addr_upper(param->ble_security.auth_cmpl.bd_addr, addr_str);
623 ESP_LOGI(TAG, "[%d] [%s] auth complete addr: %s", this->connection_index_, this->address_str_, addr_str);
624 if (!param->ble_security.auth_cmpl.success) {
625 this->log_error_("auth fail reason", param->ble_security.auth_cmpl.fail_reason);
626 } else {
627 this->paired_ = true;
628 ESP_LOGD(TAG, "[%d] [%s] auth success type = %d mode = %d", this->connection_index_, this->address_str_,
629 param->ble_security.auth_cmpl.addr_type, param->ble_security.auth_cmpl.auth_mode);
630 }
631 break;
632
633 // There are other events we'll want to implement at some point to support things like pass key
634 // https://github.com/espressif/esp-idf/blob/cba69dd088344ed9d26739f04736ae7a37541b3a/examples/bluetooth/bluedroid/ble/gatt_security_client/tutorial/Gatt_Security_Client_Example_Walkthrough.md
635 default:
636 break;
637 }
638}
639
640// Parse GATT values into a float for a sensor.
641// Ref: https://www.bluetooth.com/specifications/assigned-numbers/format-types/
643 // A length of one means a single octet value.
644 if (length == 0)
645 return 0;
646 if (length == 1)
647 return (float) ((uint8_t) value[0]);
648
649 switch (value[0]) {
650 case 0x1: // boolean.
651 case 0x2: // 2bit.
652 case 0x3: // nibble.
653 case 0x4: // uint8.
654 return (float) ((uint8_t) value[1]);
655 case 0x5: // uint12.
656 case 0x6: // uint16.
657 if (length > 2) {
658 return (float) encode_uint16(value[1], value[2]);
659 }
660 [[fallthrough]];
661 case 0x7: // uint24.
662 if (length > 3) {
663 return (float) encode_uint24(value[1], value[2], value[3]);
664 }
665 [[fallthrough]];
666 case 0x8: // uint32.
667 if (length > 4) {
668 return (float) encode_uint32(value[1], value[2], value[3], value[4]);
669 }
670 [[fallthrough]];
671 case 0xC: // int8.
672 return (float) ((int8_t) value[1]);
673 case 0xD: // int12.
674 case 0xE: // int16.
675 if (length > 2) {
676 return (float) encode_value<int16_t>(&value[1]);
677 }
678 [[fallthrough]];
679 case 0xF: // int24.
680 if (length > 3) {
681 return (float) encode_uint24(value[1], value[2], value[3]);
682 }
683 [[fallthrough]];
684 case 0x10: // int32.
685 if (length > 4) {
686 return (float) encode_value<int32_t>(&value[1]);
687 }
688 }
689 ESP_LOGW(TAG, "[%d] [%s] Cannot parse characteristic value of type 0x%x length %d", this->connection_index_,
690 this->address_str_, value[0], length);
691 return NAN;
692}
693
694#ifdef USE_ESP32_BLE_DEVICE
696 for (auto *svc : this->services_) {
697 if (svc->uuid == uuid)
698 return svc;
699 }
700 return nullptr;
701}
702
703BLEService *BLEClientBase::get_service(uint16_t uuid) { return this->get_service(espbt::ESPBTUUID::from_uint16(uuid)); }
704
706 auto *svc = this->get_service(service);
707 if (svc == nullptr)
708 return nullptr;
709 return svc->get_characteristic(chr);
710}
711
712BLECharacteristic *BLEClientBase::get_characteristic(uint16_t service, uint16_t chr) {
713 return this->get_characteristic(espbt::ESPBTUUID::from_uint16(service), espbt::ESPBTUUID::from_uint16(chr));
714}
715
717 for (auto *svc : this->services_) {
718 if (!svc->parsed)
719 svc->parse_characteristics();
720 for (auto *chr : svc->characteristics) {
721 if (chr->handle == handle)
722 return chr;
723 }
724 }
725 return nullptr;
726}
727
729 auto *chr = this->get_characteristic(handle);
730 if (chr != nullptr) {
731 if (!chr->parsed)
732 chr->parse_descriptors();
733 for (auto &desc : chr->descriptors) {
734 if (desc->uuid.get_uuid().uuid.uuid16 == ESP_GATT_UUID_CHAR_CLIENT_CONFIG)
735 return desc;
736 }
737 }
738 return nullptr;
739}
740
742 auto *svc = this->get_service(service);
743 if (svc == nullptr)
744 return nullptr;
745 auto *ch = svc->get_characteristic(chr);
746 if (ch == nullptr)
747 return nullptr;
748 return ch->get_descriptor(descr);
749}
750
751BLEDescriptor *BLEClientBase::get_descriptor(uint16_t service, uint16_t chr, uint16_t descr) {
752 return this->get_descriptor(espbt::ESPBTUUID::from_uint16(service), espbt::ESPBTUUID::from_uint16(chr),
753 espbt::ESPBTUUID::from_uint16(descr));
754}
755
757 for (auto *svc : this->services_) {
758 if (!svc->parsed)
759 svc->parse_characteristics();
760 for (auto *chr : svc->characteristics) {
761 if (!chr->parsed)
762 chr->parse_descriptors();
763 for (auto *desc : chr->descriptors) {
764 if (desc->handle == handle)
765 return desc;
766 }
767 }
768 }
769 return nullptr;
770}
771#endif // USE_ESP32_BLE_DEVICE
772
773} // namespace esphome::esp32_ble_client
774
775#endif // USE_ESP32
uint8_t status
Definition bl0942.h:8
void mark_failed()
Mark this component as failed.
void enable_loop()
Enable this component's loop.
Definition component.h:261
void defer(const char *name, std::function< void()> &&f)
Defer a callback to the next loop() call with a const char* name.
void disable_loop()
Disable this component's loop.
esp_ble_addr_type_t get_address_type() const
Definition ble_device.h:204
uint64_t address_uint64() const
Return MAC as packed uint64 (byte 0 in LSB — matches esp32's address_uint64).
std::vector< BLEService * > services_
char address_str_[MAC_ADDRESS_PRETTY_BUFFER_SIZE]
void log_gattc_warning_(const char *operation, esp_gatt_status_t status)
void log_connection_params_(const char *param_type)
BLEDescriptor * get_descriptor(espbt::ESPBTUUID service, espbt::ESPBTUUID chr, espbt::ESPBTUUID descr)
void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) override
void set_state(espbt::ClientState st) override
esp_err_t register_for_notify(uint16_t char_handle)
Register for notifications, holding the service release until the registration completes.
esp_err_t update_conn_params_(uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout, const char *param_type)
BLECharacteristic * get_characteristic(espbt::ESPBTUUID service, espbt::ESPBTUUID chr)
virtual void set_address(uint64_t address)
void set_idle_()
Transition to IDLE and reset conn_id — call when the connection is fully dead.
void run_later(std::function< void()> &&f)
virtual void on_disconnect_complete(esp_err_t reason)
Hook called once a connection has been fully torn down (after release_services() and set_idle_()): CL...
BLEService * get_service(espbt::ESPBTUUID uuid)
void set_disconnecting_()
Transition to DISCONNECTING and start the safety timeout.
bool gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param) override
bool parse_device(const espbt::ESPBTDevice &device) override
float parse_char_value(uint8_t *value, uint16_t length)
BLEDescriptor * get_config_descriptor(uint16_t handle)
void set_conn_params_(uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout, const char *param_type)
void print_bt_device_info(const ESPBTDevice &device)
void set_state_internal_(ClientState st)
Set state without IDLE handling - use for direct state transitions.
const LogString * message
Definition component.cpp:35
unsigned count
Definition gif.cpp:51
int ret
ESPHOME_LOG_TAG(TAG, "esp32_ble_client")
ESP32BLETracker * global_esp32_ble_tracker
ESP32BLE * global_ble
Definition ble.cpp:908
constexpr float AFTER_BLUETOOTH
Definition component.h:49
uint32_t value
Definition hal.cpp:41
constexpr uint32_t encode_uint24(uint8_t byte1, uint8_t byte2, uint8_t byte3)
Encode a 24-bit value given three bytes in most to least significant byte order.
Definition helpers.h:1047
constexpr T encode_value(const uint8_t *bytes)
Encode a value from its constituent bytes (from most to least significant) in an array with length si...
Definition helpers.h:1064
constexpr uint32_t encode_uint32(uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4)
Encode a 32-bit value given four bytes in most to least significant byte order.
Definition helpers.h:1051
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb)
Encode a 16-bit value given the most and least significant byte.
Definition helpers.h:1043
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
char * format_mac_addr_upper(const uint8_t *mac, char *output)
Format MAC address as XX:XX:XX:XX:XX:XX (uppercase, colon separators)
Definition helpers.h:1754
static void uint32_t
uint16_t length
Definition tt21100.cpp:0
spi_device_handle_t handle