_bleio

The _bleio module provides necessary low-level functionality for communicating using Bluetooth Low Energy (BLE). The ‘_’ prefix indicates this module is meant for internal use by libraries but not by the end user. Its API may change incompatibly between minor versions of CircuitPython. Please use the adafruit_ble CircuitPython library instead, which builds on _bleio, and provides higher-level convenience functionality, including predefined beacons, clients, servers.

_bleio.adapter

BLE Adapter used to manage device discovery and connections. This object is the sole instance of _bleio.Adapter.

class _bleio.BluetoothError(Exception: Any)

class _bleio.ConnectionError(BluetoothError: Any)

class _bleio.RoleError(BluetoothError: Any)

class _bleio.SecurityError(BluetoothError: Any)

class _bleio.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.

enabled :Any

State of the BLE adapter.

address :Any

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

name :Any

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.

advertising :Any

True when the adapter is currently advertising. (read-only)

connected :Any

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

connections :Any

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

start_advertising(self, data: buf, *, scan_response: buf = None, connectable: bool = True, anonymous: bool = False, timeout: int = 0, interval: float = 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.

• anonymous (bool) – If True then this device’s MAC address is randomized before advertising.

• timeout (int) – If set, we will only advertise for this many seconds.

• interval (float) – advertising interval, in seconds

stop_advertising(self)

Stop sending advertising packets.

start_scan(self, prefixes: sequence = b'', *, buffer_size: int = 512, extended: bool = False, timeout: float = None, interval: float = 0.1, window: float = 0.1, minimum_rssi: int = - 80, active: bool = 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(self)

Stop the current scan.

connect(self, address: Address, *, timeout: float / int = None)

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

Erase all bonding information stored in flash memory.

class _bleio.Address(address: buf, address_type: Any)

Encapsulates the address of a BLE device.

address_bytes :Any

The bytes that make up the device address (read-only).

Note that the bytes object returned is in little-endian order: The least significant byte is address_bytes[0]. So the address will appear to be reversed if you print the raw bytes object. If you print or use str() on the Attribute object itself, the address will be printed in the expected order. For example:

>>> import _bleio
>>> _bleio.adapter.address
<Address c8:1d:f5:ed:a8:35>
>>> _bleio.adapter.address.address_bytes
b'5\\xa8\\xed\\xf5\\x1d\\xc8'

type :Any

The address type (read-only).

One of the integer values: PUBLIC, RANDOM_STATIC, RANDOM_PRIVATE_RESOLVABLE, or RANDOM_PRIVATE_NON_RESOLVABLE.

PUBLIC :Any

A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits).

RANDOM_STATIC :Any

A randomly generated address that does not change often. It may never change or may change after a power cycle.

RANDOM_PRIVATE_RESOLVABLE :Any

An address that is usable when the peer knows the other device’s secret Identity Resolving Key (IRK).

RANDOM_PRIVATE_NON_RESOLVABLE :Any

A randomly generated address that changes on every connection.

__eq__(self, other: Any)

Two Address objects are equal if their addresses and address types are equal.

__hash__(self)

Returns a hash for the Address data.

class _bleio.Attribute

Definitions associated with all BLE attributes: characteristics, descriptors, etc.

Attribute is, notionally, a superclass of Characteristic and Descriptor, but is not defined as a Python superclass of those classes.

NO_ACCESS :Any

security mode: access not allowed

OPEN :Any

security_mode: no security (link is not encrypted)

ENCRYPT_NO_MITM :Any

security_mode: unauthenticated encryption, without man-in-the-middle protection

ENCRYPT_WITH_MITM :Any

security_mode: authenticated encryption, with man-in-the-middle protection

LESC_ENCRYPT_WITH_MITM :Any

security_mode: LESC encryption, with man-in-the-middle protection

SIGNED_NO_MITM :Any

security_mode: unauthenticated data signing, without man-in-the-middle protection

SIGNED_WITH_MITM :Any

security_mode: authenticated data signing, without man-in-the-middle protection

class _bleio.Characteristic

Stores information about a BLE service characteristic and allows reading and writing of the characteristic’s value.

properties :Any

An int bitmask representing which properties are set, specified as bitwise or’ing of of these possible values. BROADCAST, INDICATE, NOTIFY, READ, WRITE, WRITE_NO_RESPONSE.

uuid :Any

The UUID of this characteristic. (read-only)

Will be None if the 128-bit UUID for this characteristic is not known.

value :Any

The value of this characteristic.

descriptors :Any

A tuple of Descriptor that describe this characteristic. (read-only)

service :Any

The Service this Characteristic is a part of.

BROADCAST :Any

property: allowed in advertising packets

INDICATE :Any

property: server will indicate to the client when the value is set and wait for a response

NOTIFY :Any

property: server will notify the client when the value is set

READ :Any

property: clients may read this characteristic

WRITE :Any

property: clients may write this characteristic; a response will be sent back

WRITE_NO_RESPONSE :Any

property: clients may write this characteristic; no response will be sent back

add_to_service(self, service: Service, uuid: UUID, *, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: buf = None)

Create a new Characteristic object, and add it to this Service.

Parameters

• service (Service) – The service that will provide this characteristic

• uuid (UUID) – The uuid of the characteristic

• properties (int) – The properties of the characteristic, specified as a bitmask of these values bitwise-or’d together: BROADCAST, INDICATE, NOTIFY, READ, WRITE, WRITE_NO_RESPONSE.

• read_perm (int) – Specifies whether the characteristic can be read by a client, and if so, which security mode is required. Must be one of the integer values Attribute.NO_ACCESS, Attribute.OPEN, Attribute.ENCRYPT_NO_MITM, Attribute.ENCRYPT_WITH_MITM, Attribute.LESC_ENCRYPT_WITH_MITM, Attribute.SIGNED_NO_MITM, or Attribute.SIGNED_WITH_MITM.

• write_perm (int) – Specifies whether the characteristic can be written by a client, and if so, which security mode is required. Values allowed are the same as read_perm.

• max_length (int) – Maximum length in bytes of the characteristic value. The maximum allowed is is 512, or possibly 510 if fixed_length is False. The default, 20, is the maximum number of data bytes that fit in a single BLE 4.x ATT packet.

• fixed_length (bool) – True if the characteristic value is of fixed length.

• initial_value (buf) – The initial value for this characteristic. If not given, will be filled with zeros.

Returns

the new Characteristic.

set_cccd(self, *, notify: bool = False, indicate: float = False)

Set the remote characteristic’s CCCD to enable or disable notification and indication.

Parameters

• notify (bool) – True if Characteristic should receive notifications of remote writes

• indicate (float) – True if Characteristic should receive indications of remote writes

class _bleio.CharacteristicBuffer(characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64)

Accumulates a Characteristic’s incoming values in a FIFO buffer.

in_waiting :Any

The number of bytes in the input buffer, available to be read

read(self, nbytes: Any = None)

Read characters. If nbytes is specified then read at most that many bytes. Otherwise, read everything that arrives until the connection times out. Providing the number of bytes expected is highly recommended because it will be faster.

Returns

Data read

Return type

bytes or None

readinto(self, buf: Any)

Read bytes into the buf. Read at most len(buf) bytes.

Returns

number of bytes read and stored into buf

Return type

int or None (on a non-blocking error)

readline(self)

Read a line, ending in a newline character.

Returns

the line read

Return type

int or None

reset_input_buffer(self)

Discard any unread characters in the input buffer.

deinit(self)

Disable permanently.

class _bleio.Connection

A BLE connection to another device. Used to discover and interact with services on the other device.

Usage:

import _bleio

my_entry = None
for entry in _bleio.adapter.scan(2.5):
    if entry.name is not None and entry.name == 'InterestingPeripheral':
        my_entry = entry
        break

if not my_entry:
    raise Exception("'InterestingPeripheral' not found")

connection = _bleio.adapter.connect(my_entry.address, timeout=10)

connected :Any

True if connected to the remote peer.

paired :Any

True if paired to the remote peer.

connection_interval :Any

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.

attribute :Any

The maximum number of data bytes that can be sent in a single transmission, not including overhead bytes.

This is the maximum number of bytes that can be sent in a notification, which must be sent in a single packet. But for a regular characteristic read or write, may be sent in multiple packets, so this limit does not apply.

pair(self, *, bond: Any = True)

Pair to the peer to improve security.

discover_remote_services(self, service_uuids_whitelist: iterable = None)

Do BLE discovery for all services or for the given service UUIDS,

to find their handles and characteristics, and return the discovered services. Connection.connected must be True.

Parameters

service_uuids_whitelist (iterable) –

an iterable of :py:class:~`UUID` objects for the services provided by the peripheral that you want to use.

The peripheral may provide more services, but services not listed are ignored and will not be returned.

If service_uuids_whitelist is None, then all services will undergo discovery, which can be slow.

If the service UUID is 128-bit, or its characteristic UUID’s are 128-bit, you you must have already created a :py:class:~`UUID` object for that UUID in order for the service or characteristic to be discovered. Creating the UUID causes the UUID to be registered for use. (This restriction may be lifted in the future.)

Returns

A tuple of _bleio.Service objects provided by the remote peripheral.

class _bleio.Descriptor

Stores information about a BLE descriptor.

Descriptors are attached to BLE characteristics and provide contextual information about the characteristic.

uuid :Any

The descriptor uuid. (read-only)

characteristic :Any

The Characteristic this Descriptor is a part of.

value :Any

The value of this descriptor.

class _bleio.PacketBuffer(characteristic: Characteristic, *, buffer_size: int = None)

Accumulates a Characteristic’s incoming packets in a FIFO buffer and facilitates packet aware outgoing writes. A packet’s size is either the characteristic length or the maximum transmission unit (MTU) minus overhead, whichever is smaller. The MTU can change so check incoming_packet_length and outgoing_packet_length before creating a buffer to store data.

When we’re the server, we ignore all connections besides the first to subscribe to notifications.

packet_size :int

packet_size is the same as incoming_packet_length. The name packet_size is deprecated and will be removed in CircuitPython 6.0.0.

incoming_packet_length :Any

Maximum length in bytes of a packet we are reading.

outgoing_packet_length :int

Maximum length in bytes of a packet we are writing.

readinto(self, buf: Any)

Reads a single BLE packet into the buf. Raises an exception if the next packet is longer than the given buffer. Use packet_size to read the maximum length of a single packet.

Returns

number of bytes read and stored into buf

Return type

int

write(self, data: Any, *, header: Any = None)

Writes all bytes from data into the same outgoing packet. The bytes from header are included before data when the pending packet is currently empty.

This does not block until the data is sent. It only blocks until the data is pending.

Returns

number of bytes written. May include header bytes when packet is empty.

Return type

int

deinit(self)

Disable permanently.

class _bleio.ScanEntry

Encapsulates information about a device that was received during scanning. It can be advertisement or scan response data. This object may only be created by a _bleio.ScanResults: it has no user-visible constructor.

address :Any

The address of the device (read-only), of type _bleio.Address.

advertisement_bytes :Any

All the advertisement data present in the packet, returned as a bytes object. (read-only)

rssi :Any

The signal strength of the device at the time of the scan, in integer dBm. (read-only)

connectable :Any

True if the device can be connected to. (read-only)

scan_response :Any

True if the entry was a scan response. (read-only)

matches(self, prefixes: Any, *, all: Any = True)

Returns True if the ScanEntry matches all prefixes when all is True. This is stricter than the scan filtering which accepts any advertisements that match any of the prefixes where all is False.

class _bleio.ScanResults

Iterates over advertising data received while scanning. This object is always created by a _bleio.Adapter: it has no user-visible constructor.

__iter__(self)

Returns itself since it is the iterator.

__next__(self)

Returns the next _bleio.ScanEntry. Blocks if none have been received and scanning is still active. Raises StopIteration if scanning is finished and no other results are available.

class _bleio.Service(uuid: UUID, *, secondary: bool = False)

Stores information about a BLE service and its characteristics.

characteristics :Any

A tuple of Characteristic designating the characteristics that are offered by this service. (read-only)

remote :Any

True if this is a service provided by a remote device. (read-only)

secondary :Any

True if this is a secondary service. (read-only)

uuid :Any

The UUID of this service. (read-only)

Will be None if the 128-bit UUID for this service is not known.

class _bleio.UUID(value: Any)

A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.

uuid16 :Any

The 16-bit part of the UUID. (read-only)

Type

int

uuid128 :Any

The 128-bit value of the UUID Raises AttributeError if this is a 16-bit UUID. (read-only)

Type

bytes

size :Any

128 if this UUID represents a 128-bit vendor-specific UUID. 16 if this UUID represents a 16-bit Bluetooth SIG assigned UUID. (read-only) 32-bit UUIDs are not currently supported.

Type

int

pack_into(self, buffer: Any, offset: Any = 0)

Packs the UUID into the given buffer at the given offset.

__eq__(self, other: Any)

Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit.