ble_hub.h

Go to the documentation of this file.

// ble_hub.h
//
// The platform-neutral BLE tracker contract: shared types plus the method
// surface every tracker provides (documented below). Exactly one tracker
// exists per build, so BLEHub is a compile-time alias (ble_hub_impl.h), not
// an abstract interface — no vtable, every hub call inlinable. Consumers
// include ble_hub_impl.h and bind in YAML via cv.use_id(BLEHub).
//
// Chip differences are expressed as data (HubCapabilities), never as
// platform conditionals in consumers.
 
#pragma once
 
#include "ble_device.h"
#include "esphome/core/defines.h"
 
#include <concepts>
#include <cstdint>
 
namespace esphome::ble_device_base {
 
struct RawAdvertisement {
  uint64_t address;
  const uint8_t *data;
  uint16_t data_len;
  int8_t rssi;  // signed dBm
  uint8_t addr_type;
};
 
struct RawAdvertisementCallback {
  void *instance{nullptr};
  void (*fn)(void *instance, const RawAdvertisement &adv){nullptr};
  bool is_set() const { return this->fn != nullptr; }
  void invoke(const RawAdvertisement &adv) const { this->fn(this->instance, adv); }
};
 
enum class ScannerState : uint8_t {
  IDLE = 0,
  STARTING = 1,
  RUNNING = 2,
  FAILED = 3,
  STOPPING = 4,
  STOPPED = 5,
};
 
struct ScannerStateCallback {
  void *instance{nullptr};
  void (*fn)(void *instance, ScannerState state){nullptr};
  bool is_set() const { return this->fn != nullptr; }
  void invoke(ScannerState state) const { this->fn(this->instance, state); }
};
 
struct HubCapabilities {
  bool active_scan;
  bool merges_scan_response;
  bool gatt;
  bool scan_mode_switch;
};
 
// The BLEHub method surface, asserted where ble_hub_impl.h binds the alias.
// Semantics beyond the signatures:
// - register_listener: parsed-advertisement consumers (sensors, triggers).
// - set_raw_advertisement_callback: raw stream, one consumer at a time.
// - get_adapter_mac: printable order, out[0] = MSB.
// - scan_active: the current/configured mode sends scan requests.
// - request_scan_mode: false = cannot honor, state untouched (the caller
//   reports the real state back); true = applied immediately, restarting a
//   running scan. Honoring is advertised by HubCapabilities::scan_mode_switch.
// Push hubs additionally provide set_scanner_state_callback(ScannerStateCallback)
// and get_scanner_state() under USE_BLE_SCANNER_STATE_CALLBACK; the concept
// requires both exactly when that define is set. A push hub must emit a
// transition for every accepted or refused mode request - consumers skip
// their own mode report on push builds.
template<typename T>
concept BLEHubContract = requires(T hub, ESPBTDeviceListener *listener, RawAdvertisementCallback raw_callback,
                                  uint8_t *mac) {
  hub.register_listener(listener);
  hub.set_raw_advertisement_callback(raw_callback);
  { T::get_capabilities() } -> std::same_as<HubCapabilities>;
  hub.get_adapter_mac(mac);
  { hub.scan_running() } -> std::same_as<bool>;
  { hub.scan_active() } -> std::same_as<bool>;
  { hub.request_scan_mode(true) } -> std::same_as<bool>;
#ifdef USE_BLE_SCANNER_STATE_CALLBACK
  hub.set_scanner_state_callback(ScannerStateCallback{});
  { hub.get_scanner_state() } -> std::same_as<ScannerState>;
#endif
};
 
}  // namespace esphome::ble_device_base