IBluetoothController.h

Go to the documentation of this file.

#pragma once
 
#include "cdc_core/IService.h"
#include <cstdint>
#include <cstring>
#include <functional>
 
namespace cdc::hal {

struct BleScanResult {
    char name[32];
    uint8_t mac[6];
    uint8_t addrType;          // 0=public, 1=random
    int8_t rssi;
    uint8_t advData[31];       // Raw advertising data (AD structures)
    uint8_t advDataLen;
};

struct BleBondInfo {
    uint8_t addr[6];           // Identity address
    uint8_t addrType;          // 0=public, 1=random
    bool connected;            // Currently in an active connection
};

struct BleUuid {
    enum Type : uint8_t { UUID_16 = 0, UUID_128 = 1 };
    Type type;
    union {
        uint16_t u16;
        uint8_t u128[16];
    };
 
    static BleUuid from16(uint16_t v) {
        BleUuid u;
        u.type = UUID_16;
        // u16 and u128 alias in the union: zero first, then set the value
        std::memset(u.u128, 0, sizeof(u.u128));
        u.u16 = v;
        return u;
    }
 
    static BleUuid from128(const uint8_t v[16]) {
        BleUuid u;
        u.type = UUID_128;
        std::memcpy(u.u128, v, 16);
        return u;
    }
 
    bool operator==(const BleUuid& other) const {
        if (type != other.type) return false;
        if (type == UUID_16) return u16 == other.u16;
        return std::memcmp(u128, other.u128, 16) == 0;
    }
};

namespace GattProp {
    constexpr uint8_t READ         = 0x02;
    constexpr uint8_t WRITE_NO_RSP = 0x04;
    constexpr uint8_t WRITE        = 0x08;
    constexpr uint8_t NOTIFY       = 0x10;
    constexpr uint8_t INDICATE     = 0x20;
}

namespace GattPerm {
    constexpr uint8_t READ         = 0x01;
    constexpr uint8_t WRITE        = 0x02;
    constexpr uint8_t READ_ENC     = 0x04;  // Requires encryption (pairing)
    constexpr uint8_t WRITE_ENC    = 0x08;  // Requires encryption (pairing)
}

using GattWriteCallback = std::function<int(uint16_t connHandle, uint16_t attrHandle,
                                             const uint8_t* data, uint16_t len)>;

using GattReadCallback = std::function<int(uint16_t connHandle, uint16_t attrHandle,
                                            uint8_t* buf, uint16_t* len)>;

enum class GattDescriptorKind : uint8_t {
    NONE = 0,
    REPORT_REFERENCE = 1,   // 0x2908 - HID Report Reference (2 bytes: reportId, reportType)
};

struct GattDescriptor {
    GattDescriptorKind kind;
    uint8_t data[4];           // Descriptor value bytes
    uint8_t dataLen;           // Number of valid bytes in data
};

struct GattCharacteristic {
    BleUuid uuid;
    uint8_t properties;        // GattProp flags
    uint8_t permissions;       // GattPerm flags
    uint16_t* valueHandle;     // Output: handle assigned by stack
    GattWriteCallback onWrite;
    GattReadCallback onRead;
    const GattDescriptor* descriptors = nullptr;  // Optional descriptor list
    uint8_t numDescriptors = 0;
};

struct GattServiceDef {
    BleUuid uuid;
    GattCharacteristic* characteristics;
    uint8_t numCharacteristics;
};

class IBluetoothController : public core::IService {
public:
    virtual ~IBluetoothController() = default;

    using ListenerToken = uint16_t;
    static constexpr ListenerToken INVALID_LISTENER = 0xFFFF;
 
    // GATT server limits (single source of truth for the controller and any
    // caller validating a service before registerGattService()).
    static constexpr uint8_t MAX_REGISTERED_SERVICES = 7;
    static constexpr uint8_t MAX_CHARS_PER_SERVICE   = 6;
 
    // === Power Control ===

    virtual bool enable() = 0;

    virtual void disable() = 0;

    virtual bool isEnabled() const = 0;
 
    // === Device Info ===

    virtual bool getMacAddress(uint8_t* mac) const = 0;

    virtual void setDeviceName(const char* name) = 0;

    virtual const char* getDeviceName() const = 0;
 
    // === Connection ===

    virtual bool isConnected() const = 0;

    virtual void disconnect() = 0;

    virtual int8_t getRssi() const = 0;

    virtual bool getConnectedDeviceName(char* buf, size_t bufLen) const { (void)buf; (void)bufLen; return false; }

    static constexpr uint8_t MAX_BONDED_DEVICES = 5;

    virtual uint8_t getBondedDeviceCount() const { return 0; }

    virtual uint8_t getBondedDevices(BleBondInfo* out, uint8_t maxCount) const {
        (void)out; (void)maxCount;
        return 0;
    }
 
    // === Advertising ===

    virtual void startAdvertising() {}

    virtual void stopAdvertising() {}

    virtual bool isAdvertising() const { return false; }

    virtual bool addAdvertisingUuid(const BleUuid& uuid) { (void)uuid; return false; }

    virtual void removeAdvertisingUuid(const BleUuid& uuid) { (void)uuid; }

    virtual bool setAdvertisingManufacturerData(uint16_t companyId,
                                                 const uint8_t* data, uint16_t len) {
        (void)companyId; (void)data; (void)len;
        return false;
    }

    virtual void clearAdvertisingManufacturerData() {}

    virtual void setAppearance(uint16_t appearance) { (void)appearance; }
 
    // === Scanning ===

    static constexpr uint8_t MAX_SCAN_RESULTS = 64;

    virtual bool startScan(uint32_t durationMs = 5000, bool keepAdvertising = false) {
        (void)durationMs; (void)keepAdvertising; return false;
    }

    virtual void stopScan() {}

    virtual bool isScanComplete() const { return true; }

    virtual uint8_t getScanResults(BleScanResult* results, uint8_t maxResults) { (void)results; (void)maxResults; return 0; }
 
    // === Pairing Callbacks ===
 
    using PasskeyCallback = std::function<void(uint32_t passkey)>;
    using AuthCompleteCallback = std::function<void(bool success)>;

    virtual void setPasskeyCallback(PasskeyCallback cb) { (void)cb; }

    virtual void setAuthCompleteCallback(AuthCompleteCallback cb) { (void)cb; }

    using NumericComparisonCallback = std::function<void(uint16_t connHandle, uint32_t passkey)>;

    virtual ListenerToken addNumericComparisonCallback(NumericComparisonCallback cb) {
        (void)cb;
        return INVALID_LISTENER;
    }

    virtual void removeNumericComparisonCallback(ListenerToken token) { (void)token; }

    virtual void setNumericComparisonCallback(NumericComparisonCallback cb) { (void)cb; }

    virtual void respondToNumericComparison(uint16_t connHandle, bool accept) {
        (void)connHandle; (void)accept;
    }

    using EncChangeCallback = std::function<void(uint16_t connHandle, int status)>;

    virtual ListenerToken addEncryptionChangeCallback(EncChangeCallback cb) {
        (void)cb; return INVALID_LISTENER;
    }

    virtual void removeEncryptionChangeCallback(ListenerToken token) { (void)token; }

    virtual bool initiateSecurity(uint16_t connHandle) { (void)connHandle; return false; }

    virtual bool getPeerIdAddr(uint16_t connHandle, uint8_t addr[6], uint8_t* addrType) const {
        (void)connHandle; (void)addr; (void)addrType; return false;
    }
 
    // === Connection Callbacks (multi-listener) ===
 
    using ConnectionCallback = std::function<void(uint16_t connHandle)>;
    using DisconnectionCallback = std::function<void(uint16_t connHandle, int reason)>;

    virtual ListenerToken addConnectionCallback(ConnectionCallback cb) { (void)cb; return INVALID_LISTENER; }

    virtual ListenerToken addDisconnectionCallback(DisconnectionCallback cb) { (void)cb; return INVALID_LISTENER; }

    virtual void removeConnectionCallback(ListenerToken token) { (void)token; }

    virtual void removeDisconnectionCallback(ListenerToken token) { (void)token; }
 
    // === Bond Management ===

    virtual void clearAllBonds() {}

    virtual void forgetBond(const uint8_t addr[6], uint8_t addrType) {
        (void)addr; (void)addrType;
    }
 
    // === GATT Server ===

    virtual bool registerGattService(const GattServiceDef& service,
                                     bool pluginReserved = false) {
        (void)service; (void)pluginReserved;
        return false;
    }

    virtual bool unregisterGattService(const BleUuid& serviceUuid) {
        (void)serviceUuid;
        return false;
    }

    virtual bool sendNotification(uint16_t connHandle, uint16_t attrHandle,
                                  const uint8_t* data, uint16_t len) {
        (void)connHandle; (void)attrHandle; (void)data; (void)len;
        return false;
    }

    virtual bool sendIndication(uint16_t connHandle, uint16_t attrHandle,
                                const uint8_t* data, uint16_t len) {
        (void)connHandle; (void)attrHandle; (void)data; (void)len;
        return false;
    }

    virtual uint16_t getMtu() const { return 20; }
 
    // === Central Role (GATT Client) ===

    virtual bool connect(const uint8_t* addr, uint8_t addrType = 0) {
        (void)addr; (void)addrType;
        return false;
    }

    virtual void cancelConnect() {}

    virtual bool discoverServiceByUuid(uint16_t connHandle, const BleUuid& uuid) {
        (void)connHandle; (void)uuid;
        return false;
    }

    virtual bool writeCharacteristic(uint16_t connHandle, uint16_t attrHandle,
                                     const uint8_t* data, uint16_t len,
                                     bool withResponse = true) {
        (void)connHandle; (void)attrHandle; (void)data; (void)len; (void)withResponse;
        return false;
    }

    virtual bool readCharacteristic(uint16_t connHandle, uint16_t attrHandle) {
        (void)connHandle; (void)attrHandle;
        return false;
    }

    virtual bool enableNotifications(uint16_t connHandle, uint16_t cccdHandle) {
        (void)connHandle; (void)cccdHandle;
        return false;
    }

    virtual void disconnectHandle(uint16_t connHandle) { (void)connHandle; }
 
    // === Central Role Callbacks ===

    struct DiscoveredCharacteristic {
        BleUuid uuid;
        uint16_t valueHandle;
        uint8_t properties;  // GattProp flags
    };

    struct DiscoveredService {
        BleUuid uuid;
        static constexpr uint8_t MAX_DISCOVERED_CHARS = 8;
        DiscoveredCharacteristic characteristics[MAX_DISCOVERED_CHARS];
        uint8_t numCharacteristics;
    };

    using ServiceDiscoveryCallback = std::function<void(uint16_t connHandle,
                                                         const DiscoveredService* service,
                                                         bool complete)>;

    using CharacteristicReadCallback = std::function<void(uint16_t connHandle,
                                                           uint16_t attrHandle,
                                                           const uint8_t* data, uint16_t len)>;

    using NotificationCallback = std::function<void(uint16_t connHandle,
                                                      uint16_t attrHandle,
                                                      const uint8_t* data, uint16_t len)>;

    using WriteCompleteCallback = std::function<void(uint16_t connHandle,
                                                       uint16_t attrHandle,
                                                       int status)>;

    virtual ListenerToken addServiceDiscoveryCallback(ServiceDiscoveryCallback cb) {
        (void)cb; return INVALID_LISTENER;
    }
    virtual ListenerToken addCharacteristicReadCallback(CharacteristicReadCallback cb) {
        (void)cb; return INVALID_LISTENER;
    }
    virtual ListenerToken addNotificationCallback(NotificationCallback cb) {
        (void)cb; return INVALID_LISTENER;
    }
    virtual ListenerToken addWriteCompleteCallback(WriteCompleteCallback cb) {
        (void)cb; return INVALID_LISTENER;
    }
 
    virtual void removeServiceDiscoveryCallback(ListenerToken token) { (void)token; }
    virtual void removeCharacteristicReadCallback(ListenerToken token) { (void)token; }
    virtual void removeNotificationCallback(ListenerToken token) { (void)token; }
    virtual void removeWriteCompleteCallback(ListenerToken token) { (void)token; }

    virtual void setServiceDiscoveryCallback(ServiceDiscoveryCallback cb) { (void)cb; }
    virtual void setCharacteristicReadCallback(CharacteristicReadCallback cb) { (void)cb; }
    virtual void setNotificationCallback(NotificationCallback cb) { (void)cb; }
    virtual void setWriteCompleteCallback(WriteCompleteCallback cb) { (void)cb; }

    virtual uint16_t getConnectionHandle() const { return 0xFFFF; }
};
 
// Namespace-level aliases for the multi-listener token type, so callers can
// write cdc::hal::ListenerToken / cdc::hal::INVALID_LISTENER.
using ListenerToken = IBluetoothController::ListenerToken;
inline constexpr ListenerToken INVALID_LISTENER = IBluetoothController::INVALID_LISTENER;
 
// Factory function
IBluetoothController* getBluetoothControllerInstance();

namespace BleAdvParser {
    bool findManufacturerData(const uint8_t* advData, uint8_t len,
                               uint16_t* companyId, const uint8_t** data, uint8_t* dataLen);

    bool findServiceUuid128(const uint8_t* advData, uint8_t len,
                              const uint8_t uuid128[16]);

    bool findName(const uint8_t* advData, uint8_t len,
                    char* name, uint8_t nameMaxLen);
}
 
} // namespace cdc::hal