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.
State of the BLE adapter.
MAC address of the BLE adapter. (read-only)
name of the BLE adapter used once connected. Not used in advertisements. 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_advertisingis called or if connectable, another device connects to us.
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.
- 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
- 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.
an iterable of
Stop the current scan.
True when the adapter is connected to another device regardless of who initiated the connection. (read-only)
Tuple of active connections including those initiated through
connect(address, *, timeout)¶
Attempts a connection to the device with the given address.
- address (Address) – The address of the peripheral to connect to
- timeout (float/int) – Try to connect for timeout seconds.
Erase all bonding information stored in flash memory.