Skip to content

scanner.py

scanner

Scanning tools for finding mugs.

Attributes

DEFAULT_TIMEOUT module-attribute 

DEFAULT_TIMEOUT = 30

logger module-attribute 

logger = logging.getLogger(__name__)

Classes

ScannerKwargs

Bases: typing.TypedDict

Optional kwargs for scanner.

Source code in ember_mug/scanner.py 
20
21
22
23
24
class ScannerKwargs(TypedDict):
    """Optional kwargs for scanner."""

    adapter: NotRequired[str]
    service_uuids: NotRequired[list[str]]
Attributes
adapter instance-attribute 
adapter: typing.NotRequired[str]
service_uuids instance-attribute 
service_uuids: typing.NotRequired[list[str]]

Functions

build_scanner_kwargs 

build_scanner_kwargs(
    adapter: str | None = None,
    *,
    service_uuids: list[str] | None = None
) -> scanner.ScannerKwargs

Add Adapter to kwargs for scanner if specified and using BlueZ.

Source code in ember_mug/scanner.py 
32
33
34
35
36
37
38
def build_scanner_kwargs(adapter: str | None = None, *, service_uuids: list[str] | None = None) -> ScannerKwargs:
    """Add Adapter to kwargs for scanner if specified and using BlueZ."""
    if adapter and IS_LINUX is not True:
        msg = "The adapter option is only valid for the Linux BlueZ Backend."
        raise ValueError(msg)
    kwargs = {"service_uuids": service_uuids} if service_uuids else {}
    return cast("ScannerKwargs", kwargs | {"adapter": adapter} if adapter else kwargs)

discover_devices async 

discover_devices(
    mac: str | None = None,
    adapter: str | None = None,
    wait: int = 5,
) -> list[
    tuple[
        bleak.backends.device.BLEDevice,
        bleak.backends.scanner.AdvertisementData,
    ]
]

Discover new devices in pairing mode.

Example:
```python
devices = await discover_devices()
for device, advertisement in devices:
    print(device.address, advertisement)
```
Source code in ember_mug/scanner.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
async def discover_devices(
    mac: str | None = None,
    adapter: str | None = None,
    wait: int = 5,
) -> list[tuple[BLEDevice, AdvertisementData]]:
    """
    Discover new devices in pairing mode.

    Example:
    -------
        ```python
        devices = await discover_devices()
        for device, advertisement in devices:
            print(device.address, advertisement)
        ```

    """
    async with BleakScanner(**build_scanner_kwargs(adapter, service_uuids=DEVICE_SERVICE_UUIDS)) as scanner:
        await asyncio.sleep(wait)
        return [
            (d, a)
            for (d, a) in scanner.discovered_devices_and_advertisement_data.values()
            if mac is None or d.address.lower() == mac.lower()
        ]

find_device async 

find_device(
    mac: str | None = None,
    adapter: str | None = None,
    timeout: int = scanner.DEFAULT_TIMEOUT,
) -> (
    tuple[
        bleak.backends.device.BLEDevice,
        bleak.backends.scanner.AdvertisementData,
    ]
    | tuple[None, None]
)

Find a device that has previously been discovered.

Example:
```python
device = await find_device("my:mac:addr")
```
Source code in ember_mug/scanner.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
async def find_device(
    mac: str | None = None,
    adapter: str | None = None,
    timeout: int = DEFAULT_TIMEOUT,  # noqa: ASYNC109
) -> tuple[BLEDevice, AdvertisementData] | tuple[None, None]:
    """
    Find a device that has previously been discovered.

    Example:
    -------
        ```python
        device = await find_device("my:mac:addr")
        ```

    """
    if mac is not None:
        mac = mac.lower()
    async with BleakScanner(**build_scanner_kwargs(adapter)) as scanner:
        with contextlib.suppress(asyncio.TimeoutError):
            async with asyncio.timeout(timeout):
                async for device, advertisement in scanner.advertisement_data():
                    if (not mac and device.name and device.name.startswith("Ember")) or (
                        mac and device.address.lower() == mac
                    ):
                        return device, advertisement
    return None, None