_bleio

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

_bleio.set_adapter(new_adapter: Adapter | None) → None

Set the adapter to use for BLE, such as when using an HCI adapter. Raises NotImplementedError when the adapter is a singleton and cannot be set.

_bleio.common

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

class _bleio.common.Adapter

Singleton _bleio.adapter is defined after class Adapter.

await_bleak(coro, timeout: float | None = None)

Call an async routine in the bleak thread from sync code, and await its result.

delete_connection(connection: Connection) → None

Remove the specified connection of the list of connections held by the adapter. (Blinka _bleio only).

start_scan(prefixes: bytes | bytearray | memoryview = b'', *, buffer_size: int = 512, extended: bool = False, timeout: float | None = None, interval: float = 0.1, window: float = 0.1, minimum_rssi: int = -80, active: bool = True) → Iterable[ScanEntry]

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 ScanEntry objects

Return type:

iterable

stop_advertising() → None

Stop sending advertising packets.

stop_scan() → None

Stop scanning before timeout may have occurred.

class _bleio.common.Characteristic(*, 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: bytes | bytearray | memoryview | None = None)

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

There is no regular constructor for a Characteristic. A new local Characteristic can be created and attached to a Service by calling add_to_service(). Remote Characteristic objects are created by _bleio.Connection.discover_remote_services as part of remote Services.

BROADCAST = 1

allowed in advertising packets

Type:

property

INDICATE = 2

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

Type:

property

NOTIFY = 4

server will notify the client when the value is set

Type:

property

READ = 8

clients may read this characteristic

Type:

property

WRITE = 16

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

Type:

property

WRITE_NO_RESPONSE = 32

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

Type:

property

classmethod add_to_service(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: bytes | bytearray | memoryview | None = None) → Characteristic

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

Parameters:
Returns:

the new Characteristic.

property descriptors: Tuple['Descriptor']

py:class:~`Descriptor` that describe this characteristic. (read-only)

Type:

A tuple of

property properties: int

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.

property service: Service

The Service this Characteristic is a part of.

set_cccd(*, notify: bool = False, indicate: bool = False) → None

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

property uuid: UUID

The UUID of this characteristic. (read-only) Will be None if the 128-bit UUID for this characteristic is not known.

property value: bytes | None

The value of this characteristic.

class _bleio.common.Connection(address: Address)

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)

Connections should not be created directly. Instead, to initiate a connection use _bleio.Adapter.connect. Connections may also be made when another device initiates a connection. To use a Connection created by a peer, read the _bleio.Adapter.connections property.

Parameters:

address (Address) – Address of device to connect to

property connected: bool

True if connected to the remote peer.

property connection_interval: float

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.

disconnect() → None

Disconnects from the remote peripheral. Does nothing if already disconnected.

property max_packet_length: int

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(*, bond: bool = True) → None

Pair to the peer to improve security.

property paired: bool

True if paired to the remote peer.

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

Stores information about a BLE service and its characteristics.

Create a new Service identified by the specified UUID. It can be accessed by all connections. This is known as a Service server. Client Service objects are created via _bleio.Connection.discover_remote_services.

To mark the Service as secondary, pass True as secondary.

Parameters:

  • uuid (UUID) – The uuid of the service

  • secondary (bool) – If the service is a secondary one

Returns:

the new Service

property characteristics: Tuple[Characteristic]

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

property connection: Connection

Connection associated with this service, if any.

property remote: bool

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

property secondary: bool

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

property uuid: UUID | None

The UUID of this service. (read-only) Will be None if the 128-bit UUID for this service is not known.

_bleio.address

_bleio for Blinka based on bleak

  • Author(s): Dan Halbert

_bleio.attribute

_bleio for Blinka based on bleak

  • Author(s): Dan Halbert

class _bleio.attribute.Attribute(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

_bleio.characteristic_buffer

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

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

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

Monitor the given Characteristic. Each time a new value is written to the Characteristic add the newly-written bytes to a FIFO buffer.

Parameters:

  • characteristic (Characteristic) – The Characteristic to monitor. It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic in a remote Service that a Central has connected to.

  • timeout (int) – the timeout in seconds to wait for the first character and between subsequent characters.

  • buffer_size (int) – Size of ring buffer that stores incoming data coming from client. Must be >= 1.

deinit() → None

Disable permanently.

property in_waiting: int

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

read(nbytes: int | None = None) → bytes | bytearray | memoryview | 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

readinto(buf: bytes | bytearray | memoryview) → int | None

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

Returns:

number of bytes read and stored into buf

readline() → bytes | bytearray | memoryview

Read a line, ending in a newline character.

Returns:

the line read

reset_input_buffer() → None

Discard any unread characters in the input buffer.

_bleio.descriptor

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

class _bleio.descriptor.Descriptor(*, uuid: UUID, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: bytes | bytearray | memoryview = b'')

Stores information about a BLE descriptor.

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

There is no regular constructor for a Descriptor. A new local Descriptor can be created and attached to a Characteristic by calling add_to_characteristic(). Remote Descriptor objects are created by _bleio.Connection.discover_remote_services as part of remote Characteristics in the remote Services that are discovered.

classmethod add_to_characteristic(characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: bytes | bytearray | memoryview = b'')

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

Parameters:
Returns:

the new Descriptor.

property characteristic: Characteristic

The Characteristic this Descriptor is a part of.

property uuid: UUID

The descriptor uuid. (read-only)

property value: bytes

The value of this descriptor.

_bleio.exceptions

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

exception _bleio.exceptions.BluetoothError

Catch-all exception for Bluetooth related errors.

exception _bleio.exceptions.ConnectionError

Raised when a connection is unavailable.

exception _bleio.exceptions.RoleError

Raised when a resource is used as the mismatched role. For example, if a local CCCD is attempted to be set but it can only be set when remote.

exception _bleio.exceptions.SecurityError

Raised when a security related error occurs.

_bleio.packet_buffer

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

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

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.

Monitor the given Characteristic. Each time a new value is written to the Characteristic add the newly-written bytes to a FIFO buffer.

Parameters:

  • characteristic (Characteristic) – The Characteristic to monitor. It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic in a remote Service that a Central has connected to.

  • buffer_size (int) – Size of ring buffer (in packets of the Characteristic’s maximum length) that stores incoming packets coming from the peer.

deinit() → None

Disable permanently.

property incoming_packet_length: int

Maximum length in bytes of a packet we are reading.

property outgoing_packet_length

Maximum length in bytes of a packet we are writing.

property 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.

readinto(buf: bytes | bytearray | memoryview) → int

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(data: bytes | bytearray | memoryview, *, header: bytes | bytearray | memoryview | None = None) → int

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

_bleio.scan_entry

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries

_bleio.uuid_

_bleio implementation for Adafruit_Blinka_bleio

  • Author(s): Dan Halbert for Adafruit Industries