bluetooth_proxy.hpp

Go to the documentation of this file.

#pragma once
 
 
#include <esphome/api/model/enums.hpp>
#include <esphome/api/subsystems/subsystem.hpp>
 
#include <cstdint>
#include <functional>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace esphome::api {
 
struct BleServiceData {
    std::string uuid;
    std::string data;
};
 
struct BleManufacturerData {
    std::string uuid;
    std::string data;
};
 
struct BleAdvertisement {
    std::uint64_t address = 0;
    std::string name;
    std::int32_t rssi = 0;
    std::uint32_t address_type = 0;
    std::vector<BleServiceData> service_data;
    std::vector<std::string> service_uuids;
    std::vector<BleManufacturerData> manufacturer_data;
};
 
struct BleRawAdvertisement {
    std::uint64_t address = 0;
    std::int32_t rssi = 0;
    std::uint32_t address_type = 0;
    std::string data;
};
 
struct BleScannerState {
    BluetoothScannerState state = BluetoothScannerState::Idle;
    BluetoothScannerMode mode = BluetoothScannerMode::Passive;
    BluetoothScannerMode configured_mode = BluetoothScannerMode::Passive;
};
 
struct BleConnection {
    std::uint64_t address = 0;
    bool connected = false;
    std::uint32_t mtu = 0;
    std::int32_t error = 0;
};
 
struct BleConnectionsFree {
    std::uint32_t free = 0;
    std::uint32_t limit = 0;
    std::vector<std::uint64_t> allocated;
};
 
struct BleGattRead {
    std::uint64_t address = 0;
    std::uint32_t handle = 0;
    std::string data;
};
 
struct BleGattNotifyData {
    std::uint64_t address = 0;
    std::uint32_t handle = 0;
    std::string data;
};
 
struct BleGattDescriptor {
    std::vector<std::uint64_t> uuid;
    std::uint32_t handle = 0;
};
 
struct BleGattCharProperties {
    bool broadcast = false;                    
    bool read = false;                         
    bool write_without_response = false;       
    bool write = false;                        
    bool notify = false;                       
    bool indicate = false;                     
    bool authenticated_signed_writes = false;  
    bool extended_properties = false;          
 
    [[nodiscard]] static BleGattCharProperties from_bits(const std::uint32_t b) {
        return {(b & 0x01) != 0,
                (b & 0x02) != 0,
                (b & 0x04) != 0,
                (b & 0x08) != 0,
                (b & 0x10) != 0,
                (b & 0x20) != 0,
                (b & 0x40) != 0,
                (b & 0x80) != 0};
    }
};
 
struct BleGattCharacteristic {
    std::vector<std::uint64_t> uuid;
    std::uint32_t handle = 0;
    std::uint32_t properties = 0;  
    std::vector<BleGattDescriptor> descriptors;
 
    [[nodiscard]] BleGattCharProperties props() const {
        return BleGattCharProperties::from_bits(properties);
    }
};
 
struct BleGattService {
    std::vector<std::uint64_t> uuid;
    std::uint32_t handle = 0;
    std::vector<BleGattCharacteristic> characteristics;
};
 
struct BleGattServices {
    std::uint64_t address = 0;
    std::vector<BleGattService> services;
};
 
struct BleGattError {
    std::uint64_t address = 0;
    std::uint32_t handle = 0;
    std::int32_t error = 0;
};
 
struct BleGattReadResult {
    std::uint64_t address = 0;
    std::uint32_t handle = 0;
    bool ok = false;
    std::string data;
    std::int32_t error = 0;
};
 
struct BleGattWriteResult {
    std::uint64_t address = 0;
    std::uint32_t handle = 0;
    bool ok = false;
    std::int32_t error = 0;
};
 
struct BleGattServicesResult {
    std::uint64_t address = 0;
    bool ok = false;
    std::vector<BleGattService> services;
    std::int32_t error = 0;
};
 
class BluetoothProxy : public Subsystem {
public:
    using AdvertisementHandler = std::function<void(const BleAdvertisement&)>;
    using RawAdvertisementHandler = std::function<void(const std::vector<BleRawAdvertisement>&)>;
    using ScannerStateHandler = std::function<void(const BleScannerState&)>;
    using ConnectionHandler = std::function<void(const BleConnection&)>;
    using ConnectionsFreeHandler = std::function<void(const BleConnectionsFree&)>;
    using GattReadHandler = std::function<void(const BleGattRead&)>;
    using GattNotifyDataHandler = std::function<void(const BleGattNotifyData&)>;
    using GattServicesHandler = std::function<void(const BleGattServices&)>;
    using GattServicesDoneHandler = std::function<void(std::uint64_t address)>;
    using GattErrorHandler = std::function<void(const BleGattError&)>;
    using ReadResultHandler = std::function<void(const BleGattReadResult&)>;
    using WriteResultHandler = std::function<void(const BleGattWriteResult&)>;
    using ServicesResultHandler = std::function<void(const BleGattServicesResult&)>;
 
    explicit BluetoothProxy(Client& client) : Subsystem(client) {}
 
    // --- Scanning ---------------------------------------------------------
 
    void subscribe_advertisements(AdvertisementHandler handler, std::uint32_t flags = 0);
 
    void on_raw_advertisements(RawAdvertisementHandler handler);
 
    void unsubscribe_advertisements() const;
 
    void set_scanner_mode(BluetoothScannerMode mode) const;
 
    void on_scanner_state(ScannerStateHandler handler);
 
    // --- Connections ------------------------------------------------------
 
    void request_connection(std::uint64_t address, bool with_cache = true) const;
 
    void disconnect(std::uint64_t address) const;
 
    void subscribe_connections_free() const;
 
    void on_connection(ConnectionHandler handler);
 
    void on_connections_free(ConnectionsFreeHandler handler);
 
    // --- GATT (one-shot, request/response) --------------------------------
    // These correlate the device's response to your call and deliver it (or a
    // GATT error) to `done`. Drive the event loop to receive it.
 
    void read(std::uint64_t address, std::uint32_t handle, ReadResultHandler done);
 
    void write(std::uint64_t address,
               std::uint32_t handle,
               const std::string& data,
               bool response,
               WriteResultHandler done);
 
    void get_services(std::uint64_t address, ServicesResultHandler done);
 
    // --- GATT (raw / advanced, fire-and-forget) ---------------------------
    // Send the request and observe responses via the on_* streaming callbacks.
 
    void read(std::uint64_t address, std::uint32_t handle) const;
 
    void write(std::uint64_t address,
               std::uint32_t handle,
               const std::string& data,
               bool response = true) const;
 
    void notify(std::uint64_t address, std::uint32_t handle, bool enable) const;
 
    void get_services(std::uint64_t address) const;
 
    void on_read(GattReadHandler handler);
 
    void on_notify_data(GattNotifyDataHandler handler);
 
    void on_services(GattServicesHandler handler);
 
    void on_services_done(GattServicesDoneHandler handler);
 
    void on_error(GattErrorHandler handler);
 
private:
    void ensure_gatt_handlers();
    static std::uint64_t gatt_key(const std::uint64_t address, const std::uint32_t handle) {
        return (address << 16) | (handle & 0xFFFFU);
    }
 
    AdvertisementHandler advertisement_handler_;
    RawAdvertisementHandler raw_advertisement_handler_;
    ScannerStateHandler scanner_state_handler_;
    ConnectionHandler connection_handler_;
    ConnectionsFreeHandler connections_free_handler_;
    GattReadHandler read_handler_;
    GattNotifyDataHandler notify_data_handler_;
    GattServicesHandler services_handler_;
    GattServicesDoneHandler services_done_handler_;
    GattErrorHandler error_handler_;
 
    bool gatt_registered_ = false;
    std::unordered_map<std::uint64_t, std::vector<ReadResultHandler>> pending_reads_;
    std::unordered_map<std::uint64_t, std::vector<WriteResultHandler>> pending_writes_;
    struct ServicesAccumulator {
        std::vector<BleGattService> services;
        std::vector<ServicesResultHandler> handlers;
    };
    std::unordered_map<std::uint64_t, ServicesAccumulator> pending_services_;
};
 
}  // namespace esphome::api