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 a Service instance for the connection.

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

True if the connection to the peer is still active.

paired

True if the paired to the peer.

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 the BLEConnection class.

start_advertising(advertisement, scan_response=None, interval=0.1)

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
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 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()

Stops any active scan.

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

connect(advertisement, *, timeout=4)

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

Parameters:
  • Advertisement (advertisement) – An Advertisement or a subclass of Advertisement
  • float (timeout) – how long to wait for a connection
Returns:

the connection to the peer
Return type:

BLEConnection
connected

True if any peers are connected.

connections

A tuple of active BLEConnection objects.

name

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

tx_power

Transmit power, in dBm.

address_bytes

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