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 aService
instance for the connection.- Parameters:
bleio_connection (_bleio.Connection) – the native
_bleio.Connection
object to wrap
- 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.
- 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 theBLEConnection
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 includesBLERadio.name
andBLERadio.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 beNone
.
- 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 thenAdvertisement
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 thenAdvertisement
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:
peer – An
Advertisement
, a subclass ofAdvertisement
or_bleio.Address
timeout (float) – how long to wait for a connection
- Returns:
the connection to the peer
- Return type:
- property connections: Tuple[BLEConnection | None, ...]
A tuple of active
BLEConnection
objects.