adafruit_ble
¶
This module provides higher-level BLE (Bluetooth Low Energy) functionality,
building on the native _bleio
module.
- class BLEConnection(bleio_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 connected¶
True if the connection to the peer is still active.
- property paired¶
True if the paired to the peer.
- property connection_interval¶
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=True)¶
Pair to the peer to increase security of the connection.
- disconnect()¶
Disconnect from peer.
- class BLERadio(adapter=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, scan_response=None, interval=0.1, timeout=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
.
- stop_advertising()¶
Stops advertising.
- start_scan(*advertisement_types, buffer_size=512, extended=False, timeout=None, interval=0.1, window=0.1, minimum_rssi=- 80, active=True)¶
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()¶
Stops any active scan.
The scan results iterator will return any buffered results and then raise StopIteration once empty.
- connect(peer, *, timeout=4.0)¶
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 connected¶
True if any peers are connected.
- property connections¶
A tuple of active
BLEConnection
objects.
- property name¶
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¶
Transmit power, in dBm.
- property address_bytes¶
The device address, as a
bytes()
object of length 6.
- property advertising¶
The advertising state