Skip to content

Bluetooth

aio_rfcomm.open_bluetooth 

open_bluetooth() -> AbstractAsyncContextManager[Bluetooth]

Open Bluetooth.

This succeeds even when Bluetooth is turned off or missing. Use Bluetooth.watch_availability to find out whether it can be used.

Open it once in a program, and pass the object to the functions that need it.

Returns:

  • AbstractAsyncContextManager[Bluetooth] –

    An async context manager that gives the Bluetooth object. Leaving the block closes everything that was opened through it.

Raises:

aio_rfcomm.Bluetooth

Bluetooth on this computer.

Made by open_bluetooth. Everything else is opened through it.

watch_availability 

watch_availability() -> AvailabilityWatcher

Watch whether Bluetooth can be used.

The first value is the current state, given straight away. After that, a new value comes each time it changes. A watcher always gives the latest value, so a change that is undone before you ask for the next value is not seen.

Each call makes a separate watcher. If two tasks need to watch, give each one its own.

Returns:

list_known_devices async 

list_known_devices(
    *, service: UUID | Collection[UUID] | None = None
) -> list[RfcommDeviceInfo]

List the devices the system knows, which means the paired ones.

Pair devices in the system's own settings.

Parameters:

  • service (UUID | Collection[UUID] | None, default: None ) –

    List only the devices with a service record of this service class, or of any of these. A UUID the record only mentions, such as a profile it follows, does not count. None lists every known device.

Returns:

Raises:

open_service 

open_service(
    device: RfcommDeviceInfo, service: UUID
) -> AbstractAsyncContextManager[RfcommChannel]

Open a channel to a service on a device.

The library looks up which channel the device offers the service on.

Parameters:

  • device (RfcommDeviceInfo) –

    The device. To start from an address, make one with RfcommDeviceInfo("00:1A:7D:DA:71:0C").

  • service (UUID) –

    The service's UUID.

Returns:

  • AbstractAsyncContextManager[RfcommChannel] –

    An async context manager that gives the open channel, and closes it when the block ends.

Raises:

open_channel 

open_channel(
    device: RfcommDeviceInfo, channel: int
) -> AbstractAsyncContextManager[RfcommChannel]

Open a channel to a device by its number, without looking up a service.

Use it when the device's channel number is fixed and known. It is faster than open_service.

Parameters:

  • device (RfcommDeviceInfo) –

    The device.

  • channel (int) –

    The RFCOMM channel number, from 1 to 30.

Returns:

  • AbstractAsyncContextManager[RfcommChannel] –

    An async context manager that gives the open channel, and closes it when the block ends.

Raises:

serve 

serve(
    service: UUID, *, name: str, channel: int | None = None
) -> AbstractAsyncContextManager[RfcommService]

Publish a service and listen for devices that connect to it.

async with bluetooth.serve(CHAT, name="chat") as service:
    async for request in service.connection_requests():
        ...

Leaving the block stops new connections. Channels already accepted carry on until their own blocks end.

Parameters:

  • service (UUID) –

    The service's UUID. Devices look it up to find the channel.

  • name (str) –

    The service's name, which people see when they browse this computer's services.

  • channel (int | None, default: None ) –

    The RFCOMM channel to listen on, from 1 to 30. Leave it out to let the library choose a free one.

Returns:

  • AbstractAsyncContextManager[RfcommService] –

    An async context manager that gives the service, and stops it when the block ends.

Raises:

aio_rfcomm.AvailabilityWatcher

Gives whether Bluetooth can be used: the current state first, then each change.

Made by Bluetooth.watch_availability.

aio_rfcomm.Availability

Bases: Enum

Whether Bluetooth on this computer can be used, and if not, why not.

USABLE class-attribute instance-attribute 

USABLE = enum.auto()

Bluetooth can be used.

SWITCHED_OFF class-attribute instance-attribute 

SWITCHED_OFF = enum.auto()

Bluetooth is turned off. The user can turn it on.

NO_ADAPTER class-attribute instance-attribute 

NO_ADAPTER = enum.auto()

The computer has no Bluetooth adapter. The user can plug one in.

NOT_ALLOWED class-attribute instance-attribute 

NOT_ALLOWED = enum.auto()

This program does not have permission to use Bluetooth. The user can usually give it permission in the system settings.

SERVICE_UNAVAILABLE class-attribute instance-attribute 

SERVICE_UNAVAILABLE = enum.auto()

The system's Bluetooth service is not running. Wait a moment. It usually restarts by itself.

UNSUPPORTED class-attribute instance-attribute 

UNSUPPORTED = enum.auto()

This system cannot use Bluetooth at all.

AWAITING_PERMISSION class-attribute instance-attribute 

AWAITING_PERMISSION = enum.auto()

The system is asking the user whether this program may use Bluetooth. The availability changes when they answer.

aio_rfcomm.UnavailableReason module-attribute 

UnavailableReason: TypeAlias = Literal[
    Availability.SWITCHED_OFF,
    Availability.NO_ADAPTER,
    Availability.NOT_ALLOWED,
    Availability.AWAITING_PERMISSION,
    Availability.SERVICE_UNAVAILABLE,
    Availability.UNSUPPORTED,
]

Every Availability except USABLE: the reasons Bluetooth cannot be used. A type checker can confirm that a match on one covers every case.