Expose address type

[Jc2k]

I'm looking to add support for getting the address type for a BLEDevice. This is a (I think) a fairly small change for backends that support it. Mostly it's just getting an API that works for the bleak maintainers, so I thought I should start a discussion first.

For context, as per https://novelbits.io/bluetooth-address-privacy-ble/, there are 4 address types. A device can be public or random. Public addresses are static, and you can use the OUI data to get a vendor. With random you cannot, and the address may or may not change over time.

If you know an address is random, differentiating between the 3 types of random address can be done by masking one octet of the mac address. For example:

address[0] & 0xC0 == 0x40 # Resolvable random private address
address[0] & 0xC0 == 0x00 # Non-resolvable random private address
address[0] & 0xC0 == 0xC0 # Static random address

However, a device can be public and pass these tests - that would be incorrect. So I need to surface the address type from the bluetooth stack in order to be able to reliably use these tests.

Backend support

There is some support for this in bleaks backend, though it is not universal:

• On Linux this is visible on the Device dbus API as AddressType and can be public or random.
• winrt has an enum (see https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothaddresstype?view=winrt-22621). It is available in Windows 1511 or later on BluetoothLEDevice (https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothledevice?view=winrt-22621). It's available on BluetoothLEAdvertisementReceivedEventArgs too: https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.advertisement.bluetoothleadvertisementreceivedeventargs?view=winrt-22621
• Android seems to have the same public/random/unknown - the constants exist on BluetoothDevice, though I haven't yet found out how to get the value from the scan result.
• I don't believe macOS can surface this - they don't surface the address without using a private undocumented API, so theres not much sense in exposing address type. It's possible there is another private API we could use but I haven't found it.

Implementation

At the bare minimum I would like to have an enum like this:

class AddressType(enum.Enum):
    UNKNOWN = 0
    PUBLIC = 1
    RANDOM = 2

Then extend BLEDevice to have address_type alongside address.

Given UNKNOWN is a valid value on some backends, I think its fair to just return UNKNOWN on any backend where this isn't supported.

For backwards compatibility, the constructor of BLEDevice could use a kwarg and default to unknown. Either use a kwargs.get('address_type', AddressType.UNKNOWN) or maybe:

def __init__(
        self,
        address: str,
        name: Optional[str],
        details: Any,
        rssi: int,
        address_type: AddressType=AddressType.UNKNOWN,
        **kwargs
    ):

Finally, the enum could be extended to cover the 3 random subtypes - and the masking could happen in bleak when the BLEDevice is constructed.

class AddressType(enum.Enum):
    UNKNOWN = 0
    PUBLIC = 1
    RANDOM_STATIC = 2
    RANDOM_RESOLVABLE = 3
    RANDOM_NON_RESOLVABLE = 4

This would probably be my preference, but as long as I know whether an address is public or random, I can if needed handle the rest downstream.

[dlech]

You have done your research! 😄

I think the minimum enum is better (to avoid having to or 3 types to determine if random). However, instead we could add a separate property to BLEDevice that decodes the bit flags from the actual address.

It could also be useful to add a UUID type that is returned on macOS in the default case when the address hack is disabled.

I don't consider the BLEDevice constructor part of the public API, so I'm not worried about breaking changes there.