EspBluetooth.h

Go to the documentation of this file.

 
#pragma once
 
#include "BaseBluetooth.h"
#include "HardwareTypes.h"
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
#include "esp_log.h"
#include "nvs_flash.h"
 
#ifdef __cplusplus
}
#endif
 
// ESP32 variant detection and feature matrix
#if defined(CONFIG_IDF_TARGET_ESP32) || defined(CONFIG_IDF_TARGET_ESP32S3)
// Full Classic BT + BLE support
#define HAS_CLASSIC_BLUETOOTH 1
#define HAS_BLE_SUPPORT 1
#define HAS_A2DP_SUPPORT 1
#define HAS_AVRCP_SUPPORT 1
#define HAS_SPP_SUPPORT 1
#if defined(CONFIG_BT_NIMBLE_ENABLED)
#define HAS_NIMBLE_SUPPORT 1
#define HAS_BLUEDROID_SUPPORT 0
#else
#define HAS_NIMBLE_SUPPORT 0
#define HAS_BLUEDROID_SUPPORT 1
#endif
#elif defined(CONFIG_IDF_TARGET_ESP32C6)
// BLE-only with NimBLE (preferred for ESP32C6)
#define HAS_CLASSIC_BLUETOOTH 0
#define HAS_BLE_SUPPORT 1
#define HAS_A2DP_SUPPORT 0
#define HAS_AVRCP_SUPPORT 0
#define HAS_SPP_SUPPORT 0
#if defined(CONFIG_BT_NIMBLE_ENABLED)
#define HAS_NIMBLE_SUPPORT 1
#define HAS_BLUEDROID_SUPPORT 0
#else
#define HAS_NIMBLE_SUPPORT 0
#define HAS_BLUEDROID_SUPPORT 1
#endif
#elif defined(CONFIG_IDF_TARGET_ESP32C3) || defined(CONFIG_IDF_TARGET_ESP32H2)
// BLE-only with Bluedroid
#define HAS_CLASSIC_BLUETOOTH 0
#define HAS_BLE_SUPPORT 1
#define HAS_A2DP_SUPPORT 0
#define HAS_AVRCP_SUPPORT 0
#define HAS_SPP_SUPPORT 0
#if defined(CONFIG_BT_NIMBLE_ENABLED)
#define HAS_NIMBLE_SUPPORT 1
#define HAS_BLUEDROID_SUPPORT 0
#else
#define HAS_NIMBLE_SUPPORT 0
#define HAS_BLUEDROID_SUPPORT 1
#endif
#elif defined(CONFIG_IDF_TARGET_ESP32S2)
// No Bluetooth support
#define HAS_CLASSIC_BLUETOOTH 0
#define HAS_BLE_SUPPORT 0
#define HAS_A2DP_SUPPORT 0
#define HAS_AVRCP_SUPPORT 0
#define HAS_SPP_SUPPORT 0
#define HAS_NIMBLE_SUPPORT 0
#define HAS_BLUEDROID_SUPPORT 0
#else
// Default to no Classic Bluetooth for unknown targets
#define HAS_CLASSIC_BLUETOOTH 0
#define HAS_BLE_SUPPORT 1
#define HAS_A2DP_SUPPORT 0
#define HAS_AVRCP_SUPPORT 0
#define HAS_SPP_SUPPORT 0
#define HAS_NIMBLE_SUPPORT 0
#define HAS_BLUEDROID_SUPPORT 1
#endif
 
// Conditional includes based on target capabilities
#if HAS_BLE_SUPPORT
 
#if HAS_NIMBLE_SUPPORT && defined(CONFIG_BT_ENABLED) && defined(CONFIG_BT_NIMBLE_ENABLED)
// NimBLE headers for ESP32C6 (ESP-IDF v5.5+)
#define NIMBLE_HEADERS_AVAILABLE 1
extern "C" {
#include "host/ble_att.h"
#include "host/ble_gap.h"
#include "host/ble_gatt.h"
#include "host/ble_hs.h"
#include "host/ble_uuid.h"
#include "host/util/util.h"
#include "nimble/nimble_port.h"
#include "nimble/nimble_port_freertos.h"
#include "services/gap/ble_svc_gap.h"
#include "services/gatt/ble_svc_gatt.h"
}
#else
#define NIMBLE_HEADERS_AVAILABLE 0
#endif
 
#if HAS_BLUEDROID_SUPPORT && defined(CONFIG_BT_ENABLED)
// Bluedroid BLE headers for other targets
extern "C" {
#include "esp_bt.h"
#include "esp_bt_defs.h"
#include "esp_bt_main.h"
#include "esp_gap_ble_api.h"
#include "esp_gatt_common_api.h"
#include "esp_gattc_api.h"
#include "esp_gatts_api.h"
}
#define BLUEDROID_HEADERS_AVAILABLE 1
#else
#define BLUEDROID_HEADERS_AVAILABLE 0
#endif
 
#if HAS_CLASSIC_BLUETOOTH && defined(CONFIG_BT_ENABLED)
// Classic Bluetooth headers (ESP32/ESP32S3 only)
extern "C" {
#include "esp_gap_bt_api.h"
#include "esp_hf_client_api.h"
#include "esp_spp_api.h"
#if HAS_A2DP_SUPPORT
#include "esp_a2dp_api.h"
#include "esp_avrc_api.h"
#endif
}
#endif
 
#endif // HAS_BLE_SUPPORT
 
#include "PlatformMutex.h"
#include <functional>
#include <map>
#include <vector>
 
class EspBluetooth : public BaseBluetooth {
private:
  // Internal state
  bool m_initialized;
  bool m_enabled;
  hf_bluetooth_mode_t m_mode;
  hf_bluetooth_state_t m_state;
 
  // Device management
  std::vector<hf_bluetooth_device_info_t> m_discovered_devices;
  std::map<std::string, hf_bluetooth_device_info_t> m_connected_devices;
 
  // Configuration
  hf_bluetooth_ble_config_t m_ble_config;
 
  // Synchronization
  mutable PlatformMutex m_device_mutex;
  mutable PlatformMutex m_state_mutex;
 
  // Callback functions
  hf_bluetooth_event_callback_t m_event_callback;
  hf_bluetooth_data_callback_t m_data_callback;
  void* m_callback_context;
 
#if HAS_NIMBLE_SUPPORT && NIMBLE_HEADERS_AVAILABLE
  // NimBLE-specific members
  static EspBluetooth* s_instance;
  uint16_t m_conn_handle;
  uint8_t m_addr_type;
 
  // NimBLE event handlers
  static int GapEventHandler(struct ble_gap_event* event, void* arg);
  static int GattSvrCharAccess(uint16_t conn_handle, uint16_t attr_handle,
                               struct ble_gatt_access_ctxt* ctxt, void* arg);
 
  // NimBLE utility functions
  hf_bluetooth_err_t InitializeNimBLE();
  hf_bluetooth_err_t DeinitializeNimBLE();
  hf_bluetooth_err_t StartScanning();
  hf_bluetooth_err_t StopScanning();
 
  // Address conversion utilities
  static void ConvertBleAddr(const ble_addr_t* ble_addr, hf_bluetooth_address_t& hf_addr);
  static void ConvertHfAddr(const hf_bluetooth_address_t& hf_addr, ble_addr_t* ble_addr);
#endif
 
#if HAS_BLUEDROID_SUPPORT && defined(CONFIG_BT_ENABLED)
  // Bluedroid-specific members and methods
  hf_bluetooth_err_t InitializeBluedroid();
  hf_bluetooth_err_t DeinitializeBluedroid();
 
  // Bluedroid event handlers
  static void GapEventHandler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t* param);
  static void GattcEventHandler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
                                esp_ble_gattc_cb_param_t* param);
  static void GattsEventHandler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if,
                                esp_ble_gatts_cb_param_t* param);
#endif
 
#if HAS_CLASSIC_BLUETOOTH && defined(CONFIG_BT_ENABLED)
  // Classic Bluetooth methods
  hf_bluetooth_err_t InitializeClassic();
  hf_bluetooth_err_t DeinitializeClassic();
 
  // Classic BT event handlers
  static void ClassicGapEventHandler(esp_bt_gap_cb_event_t event, esp_bt_gap_cb_param_t* param);
  static void SppEventHandler(esp_spp_cb_event_t event, esp_spp_cb_param_t* param);
#endif
 
  // Internal utility methods
  void TriggerEvent(hf_bluetooth_event_t event, const void* data = nullptr);
  hf_bluetooth_err_t ValidateAddress(const hf_bluetooth_address_t& address) const;
  std::string AddressToString(const hf_bluetooth_address_t& address) const;
  hf_bluetooth_address_t StringToAddress(const std::string& address_str) const;
 
public:
  EspBluetooth();
 
  virtual ~EspBluetooth();
 
  // ========== Initialization and Configuration ==========
 
  hf_bluetooth_err_t Initialize(hf_bluetooth_mode_t mode) noexcept override;
 
  hf_bluetooth_err_t Deinitialize() noexcept override;
 
  bool IsInitialized() const noexcept override;
 
  hf_bluetooth_err_t Enable() noexcept override;
 
  hf_bluetooth_err_t Disable() noexcept override;
 
  bool IsEnabled() const noexcept override;
 
  hf_bluetooth_err_t SetMode(hf_bluetooth_mode_t mode) noexcept override;
 
  hf_bluetooth_mode_t GetMode() const noexcept override;
 
  // ========== Device Management ==========
 
  hf_bluetooth_err_t GetLocalAddress(hf_bluetooth_address_t& address) const noexcept override;
 
  hf_bluetooth_err_t SetDeviceName(const std::string& name) noexcept override;
 
  std::string GetDeviceName() const noexcept override;
 
  // ========== Discovery and Scanning ==========
 
  hf_bluetooth_err_t StartScan(
      uint32_t duration_ms = 0,
      hf_bluetooth_scan_type_t type =
          hf_bluetooth_scan_type_t::HF_BLUETOOTH_SCAN_TYPE_ACTIVE) noexcept override;
 
  hf_bluetooth_err_t StopScan() noexcept override;
 
  bool IsScanning() const noexcept override;
 
  hf_bluetooth_err_t GetDiscoveredDevices(
      std::vector<hf_bluetooth_device_info_t>& devices) noexcept override;
 
  hf_bluetooth_err_t ClearDiscoveredDevices() noexcept override;
 
  // ========== Advertising (BLE) ==========
 
  hf_bluetooth_err_t StartAdvertising() noexcept override;
 
  hf_bluetooth_err_t StopAdvertising() noexcept override;
 
  bool IsAdvertising() const noexcept override;
 
  // ========== Connection Management ==========
 
  hf_bluetooth_err_t Connect(const hf_bluetooth_address_t& address,
                             uint32_t timeout_ms = 0) noexcept override;
 
  hf_bluetooth_err_t Disconnect(const hf_bluetooth_address_t& address) noexcept override;
 
  bool IsConnected(const hf_bluetooth_address_t& address) const noexcept override;
 
  hf_bluetooth_err_t GetConnectedDevices(std::vector<hf_bluetooth_device_info_t>& devices) noexcept override;
 
  // ========== Pairing and Bonding ==========
 
  hf_bluetooth_err_t Pair(const hf_bluetooth_address_t& address,
                          const std::string& pin = "") noexcept override;
 
  hf_bluetooth_err_t Unpair(const hf_bluetooth_address_t& address) noexcept override;
 
  bool IsPaired(const hf_bluetooth_address_t& address) const noexcept override;
 
  // ========== Data Transfer ==========
 
  hf_bluetooth_err_t SendData(const hf_bluetooth_address_t& address,
                              const std::vector<uint8_t>& data) noexcept override;
 
  int GetAvailableData(const hf_bluetooth_address_t& address) const noexcept override;
 
  hf_bluetooth_err_t ReadData(const hf_bluetooth_address_t& address, std::vector<uint8_t>& data,
                              size_t max_bytes = 0) noexcept override;
 
  // ========== GATT Operations (BLE) ==========
 
  hf_bluetooth_err_t DiscoverServices(const hf_bluetooth_address_t& address,
                                      std::vector<hf_bluetooth_gatt_service_t>& services) noexcept override;
 
  hf_bluetooth_err_t DiscoverCharacteristics(
      const hf_bluetooth_address_t& address, const std::string& service_uuid,
      std::vector<hf_bluetooth_gatt_characteristic_t>& characteristics) noexcept override;
 
  hf_bluetooth_err_t ReadCharacteristic(const hf_bluetooth_address_t& address,
                                        const std::string& service_uuid,
                                        const std::string& characteristic_uuid,
                                        std::vector<uint8_t>& value) noexcept override;
 
  hf_bluetooth_err_t WriteCharacteristic(const hf_bluetooth_address_t& address,
                                         const std::string& service_uuid,
                                         const std::string& characteristic_uuid,
                                         const std::vector<uint8_t>& value,
                                         bool with_response = true) noexcept override;
 
  hf_bluetooth_err_t SubscribeCharacteristic(const hf_bluetooth_address_t& address,
                                             const std::string& service_uuid,
                                             const std::string& characteristic_uuid,
                                             bool enable) noexcept override;
 
  // ========== State and Status ==========
 
  hf_bluetooth_state_t GetState() const noexcept override;
 
  int8_t GetRssi(const hf_bluetooth_address_t& address) const noexcept override;
 
  // ========== Event Handling ==========
 
  hf_bluetooth_err_t RegisterEventCallback(hf_bluetooth_event_callback_t callback) noexcept override;
 
  hf_bluetooth_err_t RegisterDataCallback(hf_bluetooth_data_callback_t callback) noexcept override;
 
  hf_bluetooth_err_t UnregisterEventCallback() noexcept override;
 
  hf_bluetooth_err_t UnregisterDataCallback() noexcept override;
 
  // ========== Classic Bluetooth Operations ==========
 
  hf_bluetooth_err_t ConfigureClassic(const hf_bluetooth_classic_config_t& config) noexcept override;
 
  hf_bluetooth_err_t SetDiscoverable(bool discoverable, uint32_t timeout_ms = 0) noexcept override;
 
  bool IsDiscoverable() const noexcept override;
 
  // ========== BLE Operations ==========
 
  hf_bluetooth_err_t ConfigureBle(const hf_bluetooth_ble_config_t& config) noexcept override;
 
  // ========== Pairing and Bonding ==========
 
  hf_bluetooth_err_t GetPairedDevices(std::vector<hf_bluetooth_device_info_t>& devices) noexcept override;
 
  // ========== Utility Methods ==========
 
  std::string GetImplementationInfo() const;
 
  uint32_t GetSupportedFeatures() const;
};
 
#if !HAS_BLE_SUPPORT
class EspBluetoothStub : public BaseBluetooth {
public:
  // All methods return NOT_SUPPORTED error
  hf_bluetooth_err_t Initialize(hf_bluetooth_mode_t mode) noexcept override {
    return hf_bluetooth_err_t::BLUETOOTH_ERR_NOT_SUPPORTED;
  }
 
  hf_bluetooth_err_t Deinitialize() noexcept override {
    return hf_bluetooth_err_t::BLUETOOTH_ERR_NOT_SUPPORTED;
  }
 
  bool IsInitialized() const noexcept override {
    return false;
  }
 
  // ... (other methods would return appropriate errors)
  // For brevity, showing only key methods
};
 
// Use stub for ESP32S2
using EspBluetoothImpl = EspBluetoothStub;
#else
// Use full implementation for other targets
using EspBluetoothImpl = EspBluetooth;
#endif