ESPHome  2024.11.0
ble_client_base.cpp
Go to the documentation of this file.
1 #include "ble_client_base.h"
2 
3 #include "esphome/core/helpers.h"
4 #include "esphome/core/log.h"
5 
6 #ifdef USE_ESP32
7 
8 namespace esphome {
9 namespace esp32_ble_client {
10 
11 static const char *const TAG = "esp32_ble_client";
12 static const esp_bt_uuid_t NOTIFY_DESC_UUID = {
13  .len = ESP_UUID_LEN_16,
14  .uuid =
15  {
16  .uuid16 = ESP_GATT_UUID_CHAR_CLIENT_CONFIG,
17  },
18 };
19 
21  static uint8_t connection_index = 0;
22  this->connection_index_ = connection_index++;
23 }
24 
26  if (!esp32_ble::global_ble->is_active()) {
28  return;
29  }
30  if (this->state_ == espbt::ClientState::INIT) {
31  auto ret = esp_ble_gattc_app_register(this->app_id);
32  if (ret) {
33  ESP_LOGE(TAG, "gattc app register failed. app_id=%d code=%d", this->app_id, ret);
34  this->mark_failed();
35  }
37  }
38  // READY_TO_CONNECT means we have discovered the device
39  // and the scanner has been stopped by the tracker.
40  if (this->state_ == espbt::ClientState::READY_TO_CONNECT) {
41  this->connect();
42  }
43 }
44 
46 
48  if (!this->auto_connect_)
49  return false;
50  if (this->address_ == 0 || device.address_uint64() != this->address_)
51  return false;
52  if (this->state_ != espbt::ClientState::IDLE && this->state_ != espbt::ClientState::SEARCHING)
53  return false;
54 
55  this->log_event_("Found device");
56  if (ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_DEBUG)
58 
59  this->set_state(espbt::ClientState::DISCOVERED);
60  this->set_address(device.address_uint64());
61  this->remote_addr_type_ = device.get_address_type();
62  return true;
63 }
64 
66  ESP_LOGI(TAG, "[%d] [%s] 0x%02x Attempting BLE connection", this->connection_index_, this->address_str_.c_str(),
67  this->remote_addr_type_);
68  this->paired_ = false;
69  auto ret = esp_ble_gattc_open(this->gattc_if_, this->remote_bda_, this->remote_addr_type_, true);
70  if (ret) {
71  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_open error, status=%d", this->connection_index_, this->address_str_.c_str(),
72  ret);
74  } else {
75  this->set_state(espbt::ClientState::CONNECTING);
76  }
77 }
78 
79 esp_err_t BLEClientBase::pair() { return esp_ble_set_encryption(this->remote_bda_, ESP_BLE_SEC_ENCRYPT); }
80 
82  if (this->state_ == espbt::ClientState::IDLE || this->state_ == espbt::ClientState::DISCONNECTING)
83  return;
84  ESP_LOGI(TAG, "[%d] [%s] Disconnecting.", this->connection_index_, this->address_str_.c_str());
85  auto err = esp_ble_gattc_close(this->gattc_if_, this->conn_id_);
86  if (err != ESP_OK) {
87  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_close error, err=%d", this->connection_index_, this->address_str_.c_str(),
88  err);
89  }
90 
91  if (this->state_ == espbt::ClientState::SEARCHING || this->state_ == espbt::ClientState::READY_TO_CONNECT ||
92  this->state_ == espbt::ClientState::DISCOVERED) {
93  this->set_address(0);
95  } else {
96  this->set_state(espbt::ClientState::DISCONNECTING);
97  }
98 }
99 
101  for (auto &svc : this->services_)
102  delete svc; // NOLINT(cppcoreguidelines-owning-memory)
103  this->services_.clear();
104 #ifndef CONFIG_BT_GATTC_CACHE_NVS_FLASH
105  esp_ble_gattc_cache_clean(this->remote_bda_);
106 #endif
107 }
108 
109 void BLEClientBase::log_event_(const char *name) {
110  ESP_LOGD(TAG, "[%d] [%s] %s", this->connection_index_, this->address_str_.c_str(), name);
111 }
112 
113 bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t esp_gattc_if,
114  esp_ble_gattc_cb_param_t *param) {
115  if (event == ESP_GATTC_REG_EVT && this->app_id != param->reg.app_id)
116  return false;
117  if (event != ESP_GATTC_REG_EVT && esp_gattc_if != ESP_GATT_IF_NONE && esp_gattc_if != this->gattc_if_)
118  return false;
119 
120  ESP_LOGV(TAG, "[%d] [%s] gattc_event_handler: event=%d gattc_if=%d", this->connection_index_,
121  this->address_str_.c_str(), event, esp_gattc_if);
122 
123  switch (event) {
124  case ESP_GATTC_REG_EVT: {
125  if (param->reg.status == ESP_GATT_OK) {
126  ESP_LOGV(TAG, "[%d] [%s] gattc registered app id %d", this->connection_index_, this->address_str_.c_str(),
127  this->app_id);
128  this->gattc_if_ = esp_gattc_if;
129  } else {
130  ESP_LOGE(TAG, "[%d] [%s] gattc app registration failed id=%d code=%d", this->connection_index_,
131  this->address_str_.c_str(), param->reg.app_id, param->reg.status);
132  }
133  break;
134  }
135  case ESP_GATTC_OPEN_EVT: {
136  if (!this->check_addr(param->open.remote_bda))
137  return false;
138  this->log_event_("ESP_GATTC_OPEN_EVT");
139  this->conn_id_ = param->open.conn_id;
140  this->service_count_ = 0;
141  if (param->open.status != ESP_GATT_OK && param->open.status != ESP_GATT_ALREADY_OPEN) {
142  ESP_LOGW(TAG, "[%d] [%s] Connection failed, status=%d", this->connection_index_, this->address_str_.c_str(),
143  param->open.status);
145  break;
146  }
147  auto ret = esp_ble_gattc_send_mtu_req(this->gattc_if_, param->open.conn_id);
148  if (ret) {
149  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_send_mtu_req failed, status=%x", this->connection_index_,
150  this->address_str_.c_str(), ret);
151  }
153  if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE) {
154  ESP_LOGI(TAG, "[%d] [%s] Connected", this->connection_index_, this->address_str_.c_str());
155  // only set our state, subclients might have more stuff to do yet.
156  this->state_ = espbt::ClientState::ESTABLISHED;
157  break;
158  }
159  esp_ble_gattc_search_service(esp_gattc_if, param->cfg_mtu.conn_id, nullptr);
160  break;
161  }
162  case ESP_GATTC_CONNECT_EVT: {
163  if (!this->check_addr(param->connect.remote_bda))
164  return false;
165  this->log_event_("ESP_GATTC_CONNECT_EVT");
166  break;
167  }
168  case ESP_GATTC_DISCONNECT_EVT: {
169  if (!this->check_addr(param->disconnect.remote_bda))
170  return false;
171  ESP_LOGD(TAG, "[%d] [%s] ESP_GATTC_DISCONNECT_EVT, reason %d", this->connection_index_,
172  this->address_str_.c_str(), param->disconnect.reason);
173  this->release_services();
175  break;
176  }
177 
178  case ESP_GATTC_CFG_MTU_EVT: {
179  if (this->conn_id_ != param->cfg_mtu.conn_id)
180  return false;
181  if (param->cfg_mtu.status != ESP_GATT_OK) {
182  ESP_LOGW(TAG, "[%d] [%s] cfg_mtu failed, mtu %d, status %d", this->connection_index_,
183  this->address_str_.c_str(), param->cfg_mtu.mtu, param->cfg_mtu.status);
184  // No state change required here - disconnect event will follow if needed.
185  break;
186  }
187  ESP_LOGD(TAG, "[%d] [%s] cfg_mtu status %d, mtu %d", this->connection_index_, this->address_str_.c_str(),
188  param->cfg_mtu.status, param->cfg_mtu.mtu);
189  this->mtu_ = param->cfg_mtu.mtu;
190  break;
191  }
192  case ESP_GATTC_CLOSE_EVT: {
193  if (this->conn_id_ != param->close.conn_id)
194  return false;
195  this->log_event_("ESP_GATTC_CLOSE_EVT");
196  this->release_services();
198  break;
199  }
200  case ESP_GATTC_SEARCH_RES_EVT: {
201  if (this->conn_id_ != param->search_res.conn_id)
202  return false;
203  this->service_count_++;
204  if (this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
205  // V3 clients don't need services initialized since
206  // they only request by handle after receiving the services.
207  break;
208  }
209  BLEService *ble_service = new BLEService(); // NOLINT(cppcoreguidelines-owning-memory)
210  ble_service->uuid = espbt::ESPBTUUID::from_uuid(param->search_res.srvc_id.uuid);
211  ble_service->start_handle = param->search_res.start_handle;
212  ble_service->end_handle = param->search_res.end_handle;
213  ble_service->client = this;
214  this->services_.push_back(ble_service);
215  break;
216  }
217  case ESP_GATTC_SEARCH_CMPL_EVT: {
218  if (this->conn_id_ != param->search_cmpl.conn_id)
219  return false;
220  this->log_event_("ESP_GATTC_SEARCH_CMPL_EVT");
221  for (auto &svc : this->services_) {
222  ESP_LOGV(TAG, "[%d] [%s] Service UUID: %s", this->connection_index_, this->address_str_.c_str(),
223  svc->uuid.to_string().c_str());
224  ESP_LOGV(TAG, "[%d] [%s] start_handle: 0x%x end_handle: 0x%x", this->connection_index_,
225  this->address_str_.c_str(), svc->start_handle, svc->end_handle);
226  }
227  ESP_LOGI(TAG, "[%d] [%s] Connected", this->connection_index_, this->address_str_.c_str());
228  this->state_ = espbt::ClientState::ESTABLISHED;
229  break;
230  }
231  case ESP_GATTC_READ_DESCR_EVT: {
232  if (this->conn_id_ != param->write.conn_id)
233  return false;
234  this->log_event_("ESP_GATTC_READ_DESCR_EVT");
235  break;
236  }
237  case ESP_GATTC_WRITE_DESCR_EVT: {
238  if (this->conn_id_ != param->write.conn_id)
239  return false;
240  this->log_event_("ESP_GATTC_WRITE_DESCR_EVT");
241  break;
242  }
243  case ESP_GATTC_WRITE_CHAR_EVT: {
244  if (this->conn_id_ != param->write.conn_id)
245  return false;
246  this->log_event_("ESP_GATTC_WRITE_CHAR_EVT");
247  break;
248  }
249  case ESP_GATTC_READ_CHAR_EVT: {
250  if (this->conn_id_ != param->read.conn_id)
251  return false;
252  this->log_event_("ESP_GATTC_READ_CHAR_EVT");
253  break;
254  }
255  case ESP_GATTC_NOTIFY_EVT: {
256  if (this->conn_id_ != param->notify.conn_id)
257  return false;
258  this->log_event_("ESP_GATTC_NOTIFY_EVT");
259  break;
260  }
261  case ESP_GATTC_REG_FOR_NOTIFY_EVT: {
262  this->log_event_("ESP_GATTC_REG_FOR_NOTIFY_EVT");
263  if (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE ||
264  this->connection_type_ == espbt::ConnectionType::V3_WITHOUT_CACHE) {
265  // Client is responsible for flipping the descriptor value
266  // when using the cache
267  break;
268  }
269  esp_gattc_descr_elem_t desc_result;
270  uint16_t count = 1;
271  esp_gatt_status_t descr_status = esp_ble_gattc_get_descr_by_char_handle(
272  this->gattc_if_, this->conn_id_, param->reg_for_notify.handle, NOTIFY_DESC_UUID, &desc_result, &count);
273  if (descr_status != ESP_GATT_OK) {
274  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_get_descr_by_char_handle error, status=%d", this->connection_index_,
275  this->address_str_.c_str(), descr_status);
276  break;
277  }
278  esp_gattc_char_elem_t char_result;
279  esp_gatt_status_t char_status =
280  esp_ble_gattc_get_all_char(this->gattc_if_, this->conn_id_, param->reg_for_notify.handle,
281  param->reg_for_notify.handle, &char_result, &count, 0);
282  if (char_status != ESP_GATT_OK) {
283  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_get_all_char error, status=%d", this->connection_index_,
284  this->address_str_.c_str(), char_status);
285  break;
286  }
287 
288  /*
289  1 = notify
290  2 = indicate
291  */
292  uint16_t notify_en = char_result.properties & ESP_GATT_CHAR_PROP_BIT_NOTIFY ? 1 : 2;
293  esp_err_t status =
294  esp_ble_gattc_write_char_descr(this->gattc_if_, this->conn_id_, desc_result.handle, sizeof(notify_en),
295  (uint8_t *) &notify_en, ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE);
296  ESP_LOGD(TAG, "Wrote notify descriptor %d, properties=%d", notify_en, char_result.properties);
297  if (status) {
298  ESP_LOGW(TAG, "[%d] [%s] esp_ble_gattc_write_char_descr error, status=%d", this->connection_index_,
299  this->address_str_.c_str(), status);
300  }
301  break;
302  }
303 
304  default:
305  // ideally would check all other events for matching conn_id
306  ESP_LOGD(TAG, "[%d] [%s] Event %d", this->connection_index_, this->address_str_.c_str(), event);
307  break;
308  }
309  return true;
310 }
311 
312 // clients can't call defer() directly since it's protected.
313 void BLEClientBase::run_later(std::function<void()> &&f) { // NOLINT
314  this->defer(std::move(f));
315 }
316 
317 void BLEClientBase::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {
318  switch (event) {
319  // This event is sent by the server when it requests security
320  case ESP_GAP_BLE_SEC_REQ_EVT:
321  if (!this->check_addr(param->ble_security.auth_cmpl.bd_addr))
322  return;
323  ESP_LOGV(TAG, "[%d] [%s] ESP_GAP_BLE_SEC_REQ_EVT %x", this->connection_index_, this->address_str_.c_str(), event);
324  esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
325  break;
326  // This event is sent once authentication has completed
327  case ESP_GAP_BLE_AUTH_CMPL_EVT:
328  if (!this->check_addr(param->ble_security.auth_cmpl.bd_addr))
329  return;
330  esp_bd_addr_t bd_addr;
331  memcpy(bd_addr, param->ble_security.auth_cmpl.bd_addr, sizeof(esp_bd_addr_t));
332  ESP_LOGI(TAG, "[%d] [%s] auth complete. remote BD_ADDR: %s", this->connection_index_, this->address_str_.c_str(),
333  format_hex(bd_addr, 6).c_str());
334  if (!param->ble_security.auth_cmpl.success) {
335  ESP_LOGE(TAG, "[%d] [%s] auth fail reason = 0x%x", this->connection_index_, this->address_str_.c_str(),
336  param->ble_security.auth_cmpl.fail_reason);
337  } else {
338  this->paired_ = true;
339  ESP_LOGD(TAG, "[%d] [%s] auth success. address type = %d auth mode = %d", this->connection_index_,
340  this->address_str_.c_str(), param->ble_security.auth_cmpl.addr_type,
341  param->ble_security.auth_cmpl.auth_mode);
342  }
343  break;
344 
345  // There are other events we'll want to implement at some point to support things like pass key
346  // https://github.com/espressif/esp-idf/blob/cba69dd088344ed9d26739f04736ae7a37541b3a/examples/bluetooth/bluedroid/ble/gatt_security_client/tutorial/Gatt_Security_Client_Example_Walkthrough.md
347  default:
348  break;
349  }
350 }
351 
352 // Parse GATT values into a float for a sensor.
353 // Ref: https://www.bluetooth.com/specifications/assigned-numbers/format-types/
354 float BLEClientBase::parse_char_value(uint8_t *value, uint16_t length) {
355  // A length of one means a single octet value.
356  if (length == 0)
357  return 0;
358  if (length == 1)
359  return (float) ((uint8_t) value[0]);
360 
361  switch (value[0]) {
362  case 0x1: // boolean.
363  case 0x2: // 2bit.
364  case 0x3: // nibble.
365  case 0x4: // uint8.
366  return (float) ((uint8_t) value[1]);
367  case 0x5: // uint12.
368  case 0x6: // uint16.
369  if (length > 2) {
370  return (float) encode_uint16(value[1], value[2]);
371  }
372  // fall through
373  case 0x7: // uint24.
374  if (length > 3) {
375  return (float) encode_uint24(value[1], value[2], value[3]);
376  }
377  // fall through
378  case 0x8: // uint32.
379  if (length > 4) {
380  return (float) encode_uint32(value[1], value[2], value[3], value[4]);
381  }
382  // fall through
383  case 0xC: // int8.
384  return (float) ((int8_t) value[1]);
385  case 0xD: // int12.
386  case 0xE: // int16.
387  if (length > 2) {
388  return (float) ((int16_t) (value[1] << 8) + (int16_t) value[2]);
389  }
390  // fall through
391  case 0xF: // int24.
392  if (length > 3) {
393  return (float) ((int32_t) (value[1] << 16) + (int32_t) (value[2] << 8) + (int32_t) (value[3]));
394  }
395  // fall through
396  case 0x10: // int32.
397  if (length > 4) {
398  return (float) ((int32_t) (value[1] << 24) + (int32_t) (value[2] << 16) + (int32_t) (value[3] << 8) +
399  (int32_t) (value[4]));
400  }
401  }
402  ESP_LOGW(TAG, "[%d] [%s] Cannot parse characteristic value of type 0x%x length %d", this->connection_index_,
403  this->address_str_.c_str(), value[0], length);
404  return NAN;
405 }
406 
408  for (auto *svc : this->services_) {
409  if (svc->uuid == uuid)
410  return svc;
411  }
412  return nullptr;
413 }
414 
416 
418  auto *svc = this->get_service(service);
419  if (svc == nullptr)
420  return nullptr;
421  return svc->get_characteristic(chr);
422 }
423 
424 BLECharacteristic *BLEClientBase::get_characteristic(uint16_t service, uint16_t chr) {
426 }
427 
429  for (auto *svc : this->services_) {
430  if (!svc->parsed)
431  svc->parse_characteristics();
432  for (auto *chr : svc->characteristics) {
433  if (chr->handle == handle)
434  return chr;
435  }
436  }
437  return nullptr;
438 }
439 
441  auto *chr = this->get_characteristic(handle);
442  if (chr != nullptr) {
443  if (!chr->parsed)
444  chr->parse_descriptors();
445  for (auto &desc : chr->descriptors) {
446  if (desc->uuid.get_uuid().uuid.uuid16 == ESP_GATT_UUID_CHAR_CLIENT_CONFIG)
447  return desc;
448  }
449  }
450  return nullptr;
451 }
452 
454  auto *svc = this->get_service(service);
455  if (svc == nullptr)
456  return nullptr;
457  auto *ch = svc->get_characteristic(chr);
458  if (ch == nullptr)
459  return nullptr;
460  return ch->get_descriptor(descr);
461 }
462 
463 BLEDescriptor *BLEClientBase::get_descriptor(uint16_t service, uint16_t chr, uint16_t descr) {
466 }
467 
469  for (auto *svc : this->services_) {
470  if (!svc->parsed)
471  svc->parse_characteristics();
472  for (auto *chr : svc->characteristics) {
473  if (!chr->parsed)
474  chr->parse_descriptors();
475  for (auto *desc : chr->descriptors) {
476  if (desc->handle == handle)
477  return desc;
478  }
479  }
480  }
481  return nullptr;
482 }
483 
484 } // namespace esp32_ble_client
485 } // namespace esphome
486 
487 #endif // USE_ESP32
BLEDescriptor * get_descriptor(espbt::ESPBTUUID service, espbt::ESPBTUUID chr, espbt::ESPBTUUID descr)
const char * name
Definition: stm32flash.h:78
BLEService * get_service(espbt::ESPBTUUID uuid)
ESP32BLE * global_ble
Definition: ble.cpp:411
std::string format_hex(const uint8_t *data, size_t length)
Format the byte array data of length len in lowercased hex.
Definition: helpers.cpp:352
std::vector< BLEService * > services_
void defer(const std::string &name, std::function< void()> &&f)
Defer a callback to the next loop() call.
Definition: component.cpp:130
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:187
bool check_addr(esp_bd_addr_t &addr)
void run_later(std::function< void()> &&f)
const float AFTER_BLUETOOTH
Definition: component.cpp:22
BLEDescriptor * get_config_descriptor(uint16_t handle)
static ESPBTUUID from_uuid(esp_bt_uuid_t uuid)
Definition: ble_uuid.cpp:98
ESP32BLETracker * global_esp32_ble_tracker
virtual void set_state(ClientState st)
static ESPBTUUID from_uint16(uint16_t uuid)
Definition: ble_uuid.cpp:16
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:192
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:183
esp_ble_addr_type_t get_address_type() const
uint8_t status
Definition: bl0942.h:74
void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) override
BLECharacteristic * get_characteristic(espbt::ESPBTUUID service, espbt::ESPBTUUID chr)
virtual void mark_failed()
Mark this component as failed.
Definition: component.cpp:118
uint16_t length
Definition: tt21100.cpp:12
Implementation of SPI Controller mode.
Definition: a01nyub.cpp:7
bool parse_device(const espbt::ESPBTDevice &device) override
bool gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param) override
void print_bt_device_info(const ESPBTDevice &device)
float parse_char_value(uint8_t *value, uint16_t length)