scan_response_merger.h

Go to the documentation of this file.

// Shared support for trackers whose controller delivers advertisement and
// scan response as SEPARATE reports (ln882h, rp2, bk72xx; ESP-IDF concatenates
// both into one result before ESPHome sees it):
//
//   ScanResponseMerger — Bluedroid-style merge: a scannable advertisement is
//   held briefly, its scan response is appended on arrival and the pair is
//   delivered as ONE merged frame. Merged delivery is what the receiving side
//   is built around: Home Assistant keeps the latest raw frame per device and
//   skips re-parsing when it is unchanged — split delivery alternates two raw
//   frames per device and defeats both.
//
//   AdvDispatcher — the delivery half every such tracker repeats: raw
//   callback, listener parsing, discovered-device log. Trackers delegate
//   their BLEHub register_listener / set_raw_advertisement_callback here.
//
// The merger delivers straight into the tracker's AdvDispatcher — bind() wires
// the pair once in setup(). Single-task use only (every tracker calls this on
// the ESPHome main task). The clock is caller-provided: pass the same clock to
// stash_adv() and sweep() (millis() or App.get_loop_component_start_time(),
// never mixed).
 
#pragma once
 
#include "esphome/core/defines.h"
 
// Emitted (cg.add_define) by each tracker that adopts the merger, so builds
// whose tracker merges in-stack (esp32) never compile this code.
#ifdef USE_BLE_SCAN_RESPONSE_MERGER
 
#include "ble_device.h"
#include "ble_hub.h"
#include "esphome/core/helpers.h"
 
#include <cstdint>
 
namespace esphome::ble_device_base {
 
class AdvDispatcher {
 public:
  void register_listener(ESPBTDeviceListener *listener) {
#ifdef ESPHOME_BLE_DEVICE_BASE_LISTENER_COUNT
    this->listeners_.push_back(listener);
#endif
  }
  void set_raw_advertisement_callback(RawAdvertisementCallback callback) { this->raw_callback_ = callback; }
  void dispatch(const uint8_t *mac, int8_t rssi, uint8_t addr_type, const uint8_t *data, uint8_t data_len,
                bool raw_only, const char *log_unclaimed_tag);
  void on_scan_end();
 
 protected:
  RawAdvertisementCallback raw_callback_{};
#ifdef ESPHOME_BLE_DEVICE_BASE_LISTENER_COUNT
  // Parsed-advertisement consumers registered through ble_device_base.
  // Codegen-sized: no heap allocation, no std::vector template instantiations.
  StaticVector<ESPBTDeviceListener *, ESPHOME_BLE_DEVICE_BASE_LISTENER_COUNT> listeners_;
  // Per-period "Found device" DEBUG log with MAC dedup. Guarded like its only
  // writer so a no-listener build does not carry an unused vector.
  DiscoveredDeviceLog discovered_log_{};
#endif
};
 
class ScanResponseMerger {
 public:
  void bind(AdvDispatcher *dispatcher, const bool *scan_continuous, const char *log_tag) {
    this->dispatcher_ = dispatcher;
    this->scan_continuous_ = scan_continuous;
    this->log_tag_ = log_tag;
  }
  void stash_adv(const uint8_t *mac, int8_t rssi, uint8_t addr_type, const uint8_t *data, uint8_t data_len,
                 uint32_t now);
  void submit_scan_rsp(const uint8_t *mac, int8_t rssi, uint8_t addr_type, const uint8_t *data, uint8_t data_len);
  void sweep(uint32_t now);
  void flush();
  bool empty() const { return this->pending_count_ == 0; }
 
 private:
  void deliver_(const uint8_t *mac, int8_t rssi, uint8_t addr_type, const uint8_t *data, uint8_t data_len,
                bool raw_only);
 
  // 62 bytes = legacy adv (31) + scan response (31), the same merged maximum
  // as ESP-IDF delivers on ESP32.
  struct PendingAdv {
    bool used{false};
    uint8_t mac[MAC_ADDRESS_SIZE];
    uint8_t addr_type;
    int8_t rssi;
    uint8_t data_len;  // <= sizeof(data)
    uint8_t data[62];
    uint32_t stored_ms;
  };
  // Sized for the unanswered case: a pair that IS answered normally matches
  // within one report-queue drain, so a slot is held for the full timeout only
  // by scannable devices that never reply. 8 concurrent such advertisers
  // before the merge degrades (frames still delivered, just unmerged) at
  // ~80 B each.
  static constexpr size_t MAX_PENDING_ADV = 8;
  // On air a scan response follows its advertisement by T_IFS (150 µs) — the
  // timeout only covers HOST-side report queuing under WiFi/BLE coexistence,
  // measured on-device (ln882h) at up to ~136 ms. 300 ms = >2x that margin,
  // while staying below any device's re-advertising period.
  static constexpr uint32_t PENDING_ADV_TIMEOUT_MS = 300;
  AdvDispatcher *dispatcher_{nullptr};
  const bool *scan_continuous_{nullptr};  // read at delivery; see bind()
  const char *log_tag_{nullptr};
  // pending_count_ mirrors the number of set `used` flags; both are updated
  // together on every transition.
  PendingAdv pending_adv_[MAX_PENDING_ADV];
  uint8_t pending_count_{0};
};
 
}  // namespace esphome::ble_device_base
 
#endif  // USE_BLE_SCAN_RESPONSE_MERGER