API Reference

adafruit_ble

This module provides higher-level BLE (Bluetooth Low Energy) functionality, building on the native _bleio module.

class BLEConnection(bleio_connection: Connection)

Represents a connection to a peer BLE device. It acts as a map from a Service type to a Service instance for the connection.

Parameters:

bleio_connection (_bleio.Connection) – the native _bleio.Connection object to wrap

property connected: bool

True if the connection to the peer is still active.

property paired: bool

True if the paired to the peer.

property connection_interval: float

Time between transmissions in milliseconds. Will be multiple of 1.25ms. Lower numbers increase speed and decrease latency but increase power consumption.

When setting connection_interval, the peer may reject the new interval and connection_interval will then remain the same.

Apple has additional guidelines that dictate should be a multiple of 15ms except if HID is available. When HID is available Apple devices may accept 11.25ms intervals.

pair(*, bond: bool = True) → None

Pair to the peer to increase security of the connection.

disconnect() → None

Disconnect from peer.

class BLERadio(adapter: Adapter | None = None)

BLERadio provides the interfaces for BLE advertising, scanning for advertisements, and connecting to peers. There may be multiple connections active at once.

It uses this library’s Advertisement classes and the BLEConnection class.

start_advertising(advertisement: Advertisement, scan_response: ReadableBuffer | None = None, interval: float = 0.1, timeout: int | None = None) → None

Starts advertising the given advertisement.

Parameters:

  • scan_response (buf) – scan response data packet bytes. If None, a default scan response will be generated that includes BLERadio.name and BLERadio.tx_power.

  • interval (float) – advertising interval, in seconds

  • timeout (int) – advertising timeout in seconds. If None, no timeout.

timeout is not available in CircuitPython 5.x and must be None.

stop_advertising() → None

Stops advertising.

start_scan(*advertisement_types: Type[Advertisement], buffer_size: int = 512, extended: bool = False, timeout: float | None = None, interval: float = 0.1, window: float = 0.1, minimum_rssi: int = -80, active: bool = True) → Iterator[Advertisement]

Starts scanning. Returns an iterator of advertisement objects of the types given in advertisement_types. The iterator will block until an advertisement is heard or the scan times out.

If any advertisement_types are given, only Advertisements of those types are produced by the returned iterator. If none are given then Advertisement objects will be returned.

Advertisements and scan responses are filtered and returned separately.

Parameters:

  • buffer_size (int) – the maximum number of advertising bytes to buffer.

  • extended (bool) – When True, support extended advertising packets. Increasing buffer_size is recommended when this is set.

  • timeout (float) – the scan timeout in seconds. If None, will scan until stop_scan is called.

  • interval (float) – the interval (in seconds) between the start of two consecutive scan windows Must be in the range 0.0025 - 40.959375 seconds.

  • window (float) – the duration (in seconds) to scan a single BLE channel. window must be <= interval.

  • minimum_rssi (int) – the minimum rssi of entries to return.

  • active (bool) – request and retrieve scan responses for scannable advertisements.

Returns:

If any advertisement_types are given, only Advertisements of those types are produced by the returned iterator. If none are given then Advertisement objects will be returned.

Return type:

iterable

stop_scan() → None

Stops any active scan.

The scan results iterator will return any buffered results and then raise StopIteration once empty.

connect(peer: Advertisement | Address, *, timeout: float = 10.0) → BLEConnection

Initiates a BLEConnection to the peer that advertised the given advertisement.

Parameters:
Returns:

the connection to the peer

Return type:

BLEConnection

property connected: bool

True if any peers are connected.

property connections: Tuple[BLEConnection | None, ...]

A tuple of active BLEConnection objects.

property name: str

The name for this device. Used in advertisements and as the Device Name in the Generic Access Service, available to a connected peer.

property tx_power: Literal[0]

Transmit power, in dBm.

property address_bytes: bytes

The device address, as a bytes() object of length 6.

property advertising: bool

The advertising state