209 lines
6.8 KiB
Python
209 lines
6.8 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
import sys
|
|
import _bleio
|
|
from .services import Service
|
|
from .advertising import Advertisement
|
|
|
|
"""
|
|
|
|
This module provides higher-level BLE (Bluetooth Low Energy) functionality,
|
|
building on the native `_bleio` module.
|
|
|
|
"""
|
|
if sys.implementation.name == "circuitpython" and sys.implementation.version[0] <= 4:
|
|
...
|
|
__version__ = ...
|
|
__repo__ = ...
|
|
class BLEConnection:
|
|
"""
|
|
Represents a connection to a peer BLE device.
|
|
It acts as a map from a `Service` type to a `Service` instance for the connection.
|
|
|
|
:param bleio_connection _bleio.Connection: the native `_bleio.Connection` object to wrap
|
|
|
|
"""
|
|
def __init__(self, bleio_connection) -> None:
|
|
...
|
|
|
|
def __contains__(self, key): # -> bool:
|
|
"""
|
|
Allows easy testing for a particular Service class or a particular UUID
|
|
associated with this connection.
|
|
|
|
Example::
|
|
|
|
if UARTService in connection:
|
|
# do something
|
|
|
|
if StandardUUID(0x1234) in connection:
|
|
# do something
|
|
"""
|
|
...
|
|
|
|
def __getitem__(self, key): # -> None:
|
|
"""Return the Service for the given Service class or uuid, if any."""
|
|
...
|
|
|
|
@property
|
|
def connected(self):
|
|
"""True if the connection to the peer is still active."""
|
|
...
|
|
|
|
@property
|
|
def paired(self):
|
|
"""True if the paired to the peer."""
|
|
...
|
|
|
|
@property
|
|
def connection_interval(self):
|
|
"""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."""
|
|
...
|
|
|
|
@connection_interval.setter
|
|
def connection_interval(self, value): # -> None:
|
|
...
|
|
|
|
def pair(self, *, bond=...):
|
|
"""Pair to the peer to increase security of the connection."""
|
|
...
|
|
|
|
def disconnect(self): # -> None:
|
|
"""Disconnect from peer."""
|
|
...
|
|
|
|
|
|
|
|
class BLERadio:
|
|
"""
|
|
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."""
|
|
def __init__(self, adapter=...) -> None:
|
|
"""If no adapter is supplied, use the built-in `_bleio.adapter`.
|
|
If no built-in adapter is available, raise `RuntimeError`.
|
|
"""
|
|
...
|
|
|
|
def start_advertising(self, advertisement, scan_response=..., interval=..., timeout=...): # -> None:
|
|
"""
|
|
Starts advertising the given advertisement.
|
|
|
|
:param buf scan_response: scan response data packet bytes.
|
|
If ``None``, a default scan response will be generated that includes
|
|
`BLERadio.name` and `BLERadio.tx_power`.
|
|
:param float interval: advertising interval, in seconds
|
|
:param int timeout: advertising timeout in seconds.
|
|
If None, no timeout.
|
|
|
|
``timeout`` is not available in CircuitPython 5.x and must be `None`.
|
|
"""
|
|
...
|
|
|
|
def stop_advertising(self): # -> None:
|
|
"""Stops advertising."""
|
|
...
|
|
|
|
def start_scan(self, *advertisement_types, buffer_size=..., extended=..., timeout=..., interval=..., window=..., minimum_rssi=..., active=...): # -> Generator[Advertisement | Unknown, None, None]:
|
|
"""
|
|
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.
|
|
|
|
:param int buffer_size: the maximum number of advertising bytes to buffer.
|
|
:param bool extended: When True, support extended advertising packets.
|
|
Increasing buffer_size is recommended when this is set.
|
|
:param float timeout: the scan timeout in seconds.
|
|
If None, will scan until `stop_scan` is called.
|
|
:param float interval: the interval (in seconds) between the start
|
|
of two consecutive scan windows
|
|
Must be in the range 0.0025 - 40.959375 seconds.
|
|
:param float window: the duration (in seconds) to scan a single BLE channel.
|
|
window must be <= interval.
|
|
:param int minimum_rssi: the minimum rssi of entries to return.
|
|
:param bool active: request and retrieve scan responses for scannable advertisements.
|
|
:return: 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.
|
|
:rtype: iterable
|
|
"""
|
|
...
|
|
|
|
def stop_scan(self): # -> None:
|
|
"""Stops any active scan.
|
|
|
|
The scan results iterator will return any buffered results and then raise StopIteration
|
|
once empty."""
|
|
...
|
|
|
|
def connect(self, advertisement, *, timeout=...):
|
|
"""
|
|
Initiates a `BLEConnection` to the peer that advertised the given advertisement.
|
|
|
|
:param advertisement Advertisement: An `Advertisement` or a subclass of `Advertisement`
|
|
:param timeout float: how long to wait for a connection
|
|
:return: the connection to the peer
|
|
:rtype: BLEConnection
|
|
"""
|
|
...
|
|
|
|
@property
|
|
def connected(self): # -> bool:
|
|
"""True if any peers are connected."""
|
|
...
|
|
|
|
@property
|
|
def connections(self): # -> tuple[None, ...]:
|
|
"""A tuple of active `BLEConnection` objects."""
|
|
...
|
|
|
|
@property
|
|
def name(self): # -> str:
|
|
"""The name for this device. Used in advertisements and
|
|
as the Device Name in the Generic Access Service, available to a connected peer.
|
|
"""
|
|
...
|
|
|
|
@name.setter
|
|
def name(self, value): # -> None:
|
|
...
|
|
|
|
@property
|
|
def tx_power(self): # -> Literal[0]:
|
|
"""Transmit power, in dBm."""
|
|
...
|
|
|
|
@tx_power.setter
|
|
def tx_power(self, value):
|
|
...
|
|
|
|
@property
|
|
def address_bytes(self): # -> bytes:
|
|
"""The device address, as a ``bytes()`` object of length 6."""
|
|
...
|
|
|
|
@property
|
|
def advertising(self): # -> bool:
|
|
"""The advertising state"""
|
|
...
|
|
|
|
|
|
|