Support BDADDR_LE_RANDOM (p1): Add BLERandomAddressType, distinguish HCIAddressType..., Move EUI48 into direct_bt namespace

Add BLERandomAddressType
Exposed in DBTDevice and BluetoothDevice C++ and Java.

See "BT Core Spec v5.2:  Vol 6 LE, Part B Link Layer Specification: 1.3.2 Random device Address"

+++

Distinguish HCIAddressType -> HCILEPeerAddressType + HCILEOwnAddressType
As used for HCIHandler::le_create_conn(..)

See "BT Core Spec v5.2: Vol 4, Part E Host Controller Interface (HCI) Functionality: 7.8.12: LE Create Connection command"

DBTDevice::connectLE(..) translates its own BDAddressType -> HCILEPeerAddressType
using BLERandomAddressType (BDAddressType, address).

Currently only HCILEPeerAddressType::STATIC_PUBLIC is allowed
and passed through.

+++

Move EUI48 into direct_bt namespace

5 files changed, 141 insertions, 71 deletions

diff --git a/api/direct_bt/BTAddress.hpp b/api/direct_bt/BTAddress.hpp
index 1c13ad71..b2702a7f 100644
--- a/api/direct_bt/BTAddress.hpp
+++ b/api/direct_bt/BTAddress.hpp
@@ -30,86 +30,142 @@
 #include <string>
 #include <cstdint>
 
-/**
- * A packed 48 bit EUI-48 identifier, formerly known as MAC-48
- * or simply network device MAC address (Media Access Control address).
- * <p>
- * Since we utilize this type within *ioctl* _and_ our high-level *types*,
- * declaration is not within our *direct_bt* namespace.
- * </p>
- */
-struct __attribute__((packed)) EUI48 {
-    uint8_t b[6]; // == sizeof(EUI48)
-
-    EUI48() { bzero(b, sizeof(EUI48)); }
-    EUI48(const uint8_t * b);
-    EUI48(const std::string mac);
-    EUI48(const EUI48 &o) noexcept = default;
-    EUI48(EUI48 &&o) noexcept = default;
-    EUI48& operator=(const EUI48 &o) noexcept = default;
-    EUI48& operator=(EUI48 &&o) noexcept = default;
-
-    std::string toString() const;
-};
-
-inline bool operator<(const EUI48& lhs, const EUI48& rhs)
-{ return memcmp(&lhs, &rhs, sizeof(EUI48))<0; }
-
-inline bool operator==(const EUI48& lhs, const EUI48& rhs)
-{ return !memcmp(&lhs, &rhs, sizeof(EUI48)); }
-
-inline bool operator!=(const EUI48& lhs, const EUI48& rhs)
-{ return !(lhs == rhs); }
-
-/** EUI48 MAC address matching any device, i.e. '0:0:0:0:0:0'. */
-extern const EUI48 EUI48_ANY_DEVICE;
-/** EUI48 MAC address matching all device, i.e. 'ff:ff:ff:ff:ff:ff'. */
-extern const EUI48 EUI48_ALL_DEVICE;
-/** EUI48 MAC address matching local device, i.e. '0:0:0:ff:ff:ff'. */
-extern const EUI48 EUI48_LOCAL_DEVICE;
-
 namespace direct_bt {
 
     /**
      * BT Core Spec v5.2:  Vol 3, Part C Generic Access Profile (GAP): 15.1.1.1 Public Bluetooth address
+     * <pre>
      * 1) BT public address used as BD_ADDR for BR/EDR physical channel is defined in Vol 2, Part B 1.2
      * - EUI-48 or MAC (6 octets)
      *
      * 2) BT public address used as BD_ADDR for the LE physical channel is defined in Vol 6, Part B 1.3
-     *
+     * </pre>
+     * <p>
      * BT Core Spec v5.2:  Vol 3, Part C Generic Access Profile (GAP): 15.1.1.2 Random Bluetooth address
+     * <pre>
      * 3) BT random address used as BD_ADDR on the LE physical channel is defined in Vol 3, Part C 10.8
-     *
-     * +++
-     *
-     * For HCI LE Address-Type it is: PUBLIC: 0x00, RANDOM: 0x01
-     *
-     * BT Core Spec v5.2:  Vol 4, Part E Host Controller Interface (HCI) Functionality:
-     *
-     * > 7.8.5: LE Set Advertising Parameters command
-     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
-     * > 7.8.10: LE Set Scan Parameters command
-     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
-     *
-     * +++
-     *
-     * Couldn't yet find a reference to the BDADDR/L2CAP Address Type, which differs from HCI Address Type!
+     * </pre>
      */
     enum BDAddressType : uint8_t {
+        /** Bluetooth BREDR address */
         BDADDR_BREDR      = 0x00,
+        /** Bluetooth LE public address */
         BDADDR_LE_PUBLIC  = 0x01,
+        /** Bluetooth LE random address, see {@link BLERandomAddressType} */
         BDADDR_LE_RANDOM  = 0x02,
+        /** Undefined */
         BDADDR_UNDEFINED  = 0xff
     };
 
-    enum HCIAddressType : uint8_t {
-        HCIADDR_LE_PUBLIC = 0x00,
-        HCIADDR_LE_RANDOM = 0x01,
-        HCIADDR_UNDEFINED = 0xff
+    std::string getBDAddressTypeString(const BDAddressType op);
+
+    /**
+     * BT Core Spec v5.2:  Vol 6 LE, Part B Link Layer Specification: 1.3 Device Address
+     * <p>
+     * BT Core Spec v5.2:  Vol 6 LE, Part B Link Layer Specification: 1.3.2 Random device Address
+     * </p>
+     * <p>
+     * Table 1.2, address bits [47:46]
+     * </p>
+     * <p>
+     * If {@link BDAddressType} is {@link BDAddressType::BDADDR_LE_RANDOM},
+     * its value shall be different than {@link BLERandomAddressType::UNDEFINED}.
+     * </p>
+     * <p>
+     * If {@link BDAddressType} is not {@link BDAddressType::BDADDR_LE_RANDOM},
+     * its value shall be {@link BLERandomAddressType::UNDEFINED}.
+     * </p>
+     */
+    enum class BLERandomAddressType : uint8_t {
+        /** Non-resolvable private random device address 0b00 */
+        UNRESOLVABLE_PRIVAT = 0x00,
+        /** Resolvable private random device address 0b01 */
+        RESOLVABLE_PRIVAT   = 0x01,
+        /** Reserved for future use 0b10 */
+        RESERVED            = 0x02,
+        /** Static public 'random' device address 0b11 */
+        STATIC_PUBLIC       = 0x03,
+        /** Undefined */
+        UNDEFINED           = 0xff
+    };
+    std::string getBLERandomAddressTypeString(const BLERandomAddressType op);
+
+    /**
+     * HCI LE Address-Type is PUBLIC: 0x00, RANDOM: 0x01
+     * <p>
+     * BT Core Spec v5.2:  Vol 4, Part E Host Controller Interface (HCI) Functionality:
+     * <pre>
+     * > 7.8.5: LE Set Advertising Parameters command
+     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
+     * > 7.8.10: LE Set Scan Parameters command
+     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
+     * > 7.8.12: LE Create Connection command
+     * -- Own_Address_Type: public: 0x00 (default), random: 0x01,
+     *    Public Identity Address (resolvable-1, any not supporting LE_Set_Privacy_Mode command): 0x02,
+     *    Random (static) Identity Address (resolvable-2, any not supporting LE_Set_Privacy_Mode command): 0x03
+     * </pre>
+     * </p>
+     */
+    enum class HCILEPeerAddressType : uint8_t {
+        PUBLIC = 0x00,/**< HCIADDR_LE_PUBLIC */
+        RANDOM = 0x01,/**< HCIADDR_LE_RANDOM */
+        PUBLIC_IDENTITY = 0x02,
+        RANDOM_STATIC_IDENTITY = 0x03,
+        UNDEFINED = 0xff /**< HCIADDR_UNDEFINED */
     };
 
-    BDAddressType getBDAddressType(const HCIAddressType hciAddrType);
-    std::string getBDAddressTypeString(const BDAddressType op);
+    BDAddressType getBDAddressType(const HCILEPeerAddressType hciPeerAddrType);
+
+    enum class HCILEOwnAddressType : uint8_t {
+        PUBLIC = 0x00,
+        RANDOM = 0x01,
+        RESOLVABLE_OR_PUBLIC = 0x02,
+        RESOLVABLE_OR_RANDOM = 0x03,
+        UNDEFINED = 0xff
+    };
+
+    BDAddressType getBDAddressType(const HCILEOwnAddressType hciOwnAddrType);
+
+    /**
+     * A packed 48 bit EUI-48 identifier, formerly known as MAC-48
+     * or simply network device MAC address (Media Access Control address).
+     * <p>
+     * Since we utilize this type within *ioctl* _and_ our high-level *types*,
+     * declaration is not within our *direct_bt* namespace.
+     * </p>
+     */
+    struct __attribute__((packed)) EUI48 {
+        uint8_t b[6]; // == sizeof(EUI48)
+
+        EUI48() { bzero(b, sizeof(EUI48)); }
+        EUI48(const uint8_t * b);
+        EUI48(const std::string mac);
+        EUI48(const EUI48 &o) noexcept = default;
+        EUI48(EUI48 &&o) noexcept = default;
+        EUI48& operator=(const EUI48 &o) noexcept = default;
+        EUI48& operator=(EUI48 &&o) noexcept = default;
+
+        BLERandomAddressType getBLERandomAddressType() const;
+        std::string toString() const;
+    };
+
+    inline bool operator<(const EUI48& lhs, const EUI48& rhs)
+    { return memcmp(&lhs, &rhs, sizeof(EUI48))<0; }
+
+    inline bool operator==(const EUI48& lhs, const EUI48& rhs)
+    { return !memcmp(&lhs, &rhs, sizeof(EUI48)); }
+
+    inline bool operator!=(const EUI48& lhs, const EUI48& rhs)
+    { return !(lhs == rhs); }
+
+    std::string getBLERandomAddressTypeString(const EUI48 &a);
+
+    /** EUI48 MAC address matching any device, i.e. '0:0:0:0:0:0'. */
+    extern const EUI48 EUI48_ANY_DEVICE;
+    /** EUI48 MAC address matching all device, i.e. 'ff:ff:ff:ff:ff:ff'. */
+    extern const EUI48 EUI48_ALL_DEVICE;
+    /** EUI48 MAC address matching local device, i.e. '0:0:0:ff:ff:ff'. */
+    extern const EUI48 EUI48_LOCAL_DEVICE;
 
 } // namespace direct_bt
 
diff --git a/api/direct_bt/DBTAdapter.hpp b/api/direct_bt/DBTAdapter.hpp
index b70f80c4..21dc4a52 100644
--- a/api/direct_bt/DBTAdapter.hpp
+++ b/api/direct_bt/DBTAdapter.hpp
@@ -180,10 +180,9 @@ namespace direct_bt {
             friend std::shared_ptr<ConnectionInfo> DBTDevice::getConnectionInfo();
             friend bool DBTDevice::disconnect(const bool sentFromManager, const bool ioErrorCause,const HCIStatusCode reason);
             friend void DBTDevice::remove();
-            friend bool DBTDevice::connectLE(HCIAddressType peer_mac_type, HCIAddressType own_mac_type,
-                    uint16_t interval, uint16_t window,
-                    uint16_t min_interval, uint16_t max_interval,
-                    uint16_t latency, uint16_t supervision_timeout);
+            friend bool DBTDevice::connectLE(uint16_t interval, uint16_t window,
+                                             uint16_t min_interval, uint16_t max_interval,
+                                             uint16_t latency, uint16_t supervision_timeout);
             friend bool DBTDevice::connectBREDR(const uint16_t pkt_type, const uint16_t clock_offset, const uint8_t role_switch);
             friend std::vector<std::shared_ptr<GATTService>> DBTDevice::getGATTServices();
 
@@ -412,7 +411,7 @@ namespace direct_bt {
              * @param le_scan_window in units of 0.625ms, default value 48 for 30ms,  min value 4 for 2.5ms -> 0x4000 for 10.24s. Shall be <= le_scan_interval
              * @return
              */
-            bool startDiscovery(const bool keepAlive=true, const HCIAddressType own_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
+            bool startDiscovery(const bool keepAlive=true, const HCILEOwnAddressType own_mac_type=HCILEOwnAddressType::PUBLIC,
                                 const uint16_t le_scan_interval=48, const uint16_t le_scan_window=48);
 
             /**
diff --git a/api/direct_bt/DBTDevice.hpp b/api/direct_bt/DBTDevice.hpp
index 9683e987..5dd8e9db 100644
--- a/api/direct_bt/DBTDevice.hpp
+++ b/api/direct_bt/DBTDevice.hpp
@@ -92,6 +92,7 @@ namespace direct_bt {
             /** Device mac address */
             const EUI48 address;
             const BDAddressType addressType;
+            const BLERandomAddressType leRandomAddressType;
 
             /**
              * Releases this instance after calling {@link #remove()}.
@@ -143,6 +144,20 @@ namespace direct_bt {
             bool isLEAddressType() const { return BDADDR_LE_PUBLIC == addressType || BDADDR_LE_RANDOM == addressType; }
             bool isBREDRAddressType() const { return BDADDR_BREDR == addressType; }
 
+            /**
+             * Returns the {@link BLERandomAddressType}.
+             * <p>
+             * If {@link #getAddressType()} is {@link BDAddressType::BDADDR_LE_RANDOM},
+             * method shall return a valid value other than {@link BLERandomAddressType::UNDEFINED}.
+             * </p>
+             * <p>
+             * If {@link #getAddressType()} is not {@link BDAddressType::BDADDR_LE_RANDOM},
+             * method shall return {@link BLERandomAddressType::UNDEFINED}.
+             * </p>
+             * @since 2.0.0
+             */
+            BLERandomAddressType getBLERandomAddressType() const { return leRandomAddressType; }
+
             /** Return RSSI of device as recognized at discovery and connect. */
             int8_t getRSSI() const { return rssi; }
 
@@ -221,9 +236,7 @@ namespace direct_bt {
              * @param supervision_timeout in units of 10ms, default value 1000 for 10000ms or 10s.
              * @return
              */
-            bool connectLE(const HCIAddressType peer_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
-                           const HCIAddressType own_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
-                           const uint16_t le_scan_interval=48, const uint16_t le_scan_window=48,
+            bool connectLE(const uint16_t le_scan_interval=48, const uint16_t le_scan_window=48,
                            const uint16_t conn_interval_min=0x000F, const uint16_t conn_interval_max=0x000F,
                            const uint16_t conn_latency=0x0000, const uint16_t supervision_timeout=number(HCIConstInt::LE_CONN_TIMEOUT_MS)/10);
 
diff --git a/api/direct_bt/HCIHandler.hpp b/api/direct_bt/HCIHandler.hpp
index a2f70308..dc9dc46e 100644
--- a/api/direct_bt/HCIHandler.hpp
+++ b/api/direct_bt/HCIHandler.hpp
@@ -226,8 +226,8 @@ namespace direct_bt {
              * @return
              */
             HCIStatusCode le_create_conn(const EUI48 &peer_bdaddr,
-                                        const HCIAddressType peer_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
-                                        const HCIAddressType own_mac_type=HCIAddressType::HCIADDR_LE_PUBLIC,
+                                        const HCILEPeerAddressType peer_mac_type=HCILEPeerAddressType::PUBLIC,
+                                        const HCILEOwnAddressType own_mac_type=HCILEOwnAddressType::PUBLIC,
                                         const uint16_t le_scan_interval=48, const uint16_t le_scan_window=48,
                                         const uint16_t conn_interval_min=0x000F, const uint16_t conn_interval_max=0x000F,
                                         const uint16_t conn_latency=0x0000, const uint16_t supervision_timeout=number(HCIConstInt::LE_CONN_TIMEOUT_MS)/10);
diff --git a/api/direct_bt/linux_kernel_types.hpp b/api/direct_bt/linux_kernel_types.hpp
index dca8b227..552c1c0e 100644
--- a/api/direct_bt/linux_kernel_types.hpp
+++ b/api/direct_bt/linux_kernel_types.hpp
@@ -26,6 +26,8 @@
 #ifndef LINUX_KERNEL_TYPES_HPP_
 #define LINUX_KERNEL_TYPES_HPP_
 
+#include "BTAddress.hpp"
+
 typedef uint8_t  __u8;
 typedef int8_t   __s8;
 typedef uint16_t __u16;
@@ -37,7 +39,7 @@ typedef uint32_t __be32;
 typedef uint64_t __u64;
 typedef uint64_t __le64;
 typedef uint64_t __be64;
-typedef EUI48    bdaddr_t;
+typedef direct_bt::EUI48 bdaddr_t;
 #define __packed __attribute__ ((packed))
 
 #endif /* LINUX_KERNEL_TYPES_HPP_ */