Adapter — BLE adapter

The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices. This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP).

Discovery of other devices happens during a scanning process that listens for small packets of information, known as advertisements, that are broadcast unencrypted. The advertising packets have two different uses. The first is to broadcast a small piece of data to anyone who cares and and nothing more. These are known as Beacons. The second class of advertisement is to promote additional functionality available after the devices establish a connection. For example, a BLE keyboard may advertise that it can provide key information, but not what the key info is.

The built-in BLE adapter can do both parts of this process: it can scan for other device advertisements and it can advertise its own data. Furthermore, Adapters can accept incoming connections and also initiate connections.

class _bleio.Adapter
You cannot create an instance of _bleio.Adapter. Use _bleio.adapter to access the sole instance available.
enabled

State of the BLE adapter.

address

MAC address of the BLE adapter. (read-only)

name

name of the BLE adapter used once connected. The name is “CIRCUITPY” + the last four hex digits of adapter.address, to make it easy to distinguish multiple CircuitPython boards.

start_advertising(data, *, scan_response=None, connectable=True, interval=0.1)

Starts advertising until stop_advertising is called or if connectable, another device connects to us.

Parameters:
  • data (buf) – advertising data packet bytes
  • scan_response (buf) – scan response data packet bytes. None if no scan response is needed.
  • connectable (bool) – If True then other devices are allowed to connect to this peripheral.
  • interval (float) – advertising interval, in seconds
stop_advertising()

Stop sending advertising packets.

start_scan(prefixes=b"", *, buffer_size=512, extended=False, timeout=None, interval=0.1, window=0.1, minimum_rssi=-80, active=True)

Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are filtered and returned separately.

Parameters:
  • prefixes (sequence) – Sequence of byte string prefixes to filter advertising packets with. A packet without an advertising structure that matches one of the prefixes is ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
  • 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) – retrieve scan responses for scannable advertisements.
Returns:

an iterable of _bleio.ScanEntry objects

Return type:

iterable

stop_scan()

Stop the current scan.

connected

True when the adapter is connected to another device regardless of who initiated the connection. (read-only)

connections

Tuple of active connections including those initiated through _bleio.Adapter.connect(). (read-only)

connect(address, *, timeout)

Attempts a connection to the device with the given address.

Parameters:
  • address (Address) – The address of the peripheral to connect to
  • timeout (float/int) – Try to connect for timeout seconds.
erase_bonding()

Erase all bonding information stored in flash memory.