_bleio –低功耗蓝牙 (BLE) 通信¶
该 _bleio模块为使用蓝牙低功耗 (BLE) 进行通信提供了必要的低级功能。'_' 前缀表示该模块供图书馆内部使用，但不供最终用户使用。它的 API 可能会在 CircuitPython 的次要版本之间发生不兼容的变化。请改用
adafruit_bleCircuitPython 库，该库基于_bleio，并提供更高级别的便利功能，包括预定义的信标、客户端、服务器。
在这些板上可用
-
_bleio.adapter:Adapter¶ BLE 适配器用于管理设备发现和连接。该对象是 的唯一实例
_bleio.Adapter.
-
exception
_bleio.BluetoothError¶ 基地：
Exception蓝牙相关错误的 Catchall 异常。
初始化自我。请参阅 help(type(self)) 以获得准确的签名。
-
exception
_bleio.RoleError¶ 基地:
BluetoothError当资源用作不匹配的角色时引发。例如，如果尝试设置本地 CCCD，但只能在远程设置时才能设置。
初始化自我。请参阅 help(type(self)) 以获得准确的签名。
-
exception
_bleio.SecurityError¶ -
发生与安全相关的错误时引发。
初始化自我。请参阅 help(type(self)) 以获得准确的签名。
-
_bleio.set_adapter(adapter: Optional[Adapter]) → None¶ 将适配器设置为用于 BLE，例如在使用 HCI 适配器时。
NotImplementedError当适配器为单例且无法设置时引发。
-
class
_bleio.Adapter(*, uart: busio.UART, rts: digitalio.DigitalInOut, cts: digitalio.DigitalInOut)¶ BLE 适配器对象管理与附近其他低功耗蓝牙设备的发现和连接。低功耗蓝牙规范的这一部分称为通用访问配置文件 (GAP)。
其他设备的发现发生在扫描过程中，该过程会侦听未加密广播的小信息包（称为广告）。广告数据包有两种不同的用途。第一种是向任何关心的人广播一小段数据，仅此而已。这些被称为信标。第二类广告是在设备建立连接后宣传可用的附加功能。例如，BLE 心率监测器会宣传它提供标准的 BLE 心率服务。
适配器可以完成此过程的两个部分：它可以扫描其他设备广告，也可以广告自己的数据。此外，适配器可以接受传入连接并启动连接。
在没有本地 BLE 的板上，您可以使用 HCI 协处理器。传递用于与协处理器（例如 Adafruit AirLift）通信的 UART 和引脚。协处理器必须事先通过适当的引脚操作复位并进入 BLE 模式。这
uart,rts, 和cts对象用于与HCI协处理器在HCI模式进行通信。Adapter在此调用期间启用该对象。实例化一个Adapter后，调用
_bleio.set_adapter()set_bleio.adapter在带有本机 BLE 的板上，您不能创建
_bleio.Adapter; 此构造函数将引发NotImplementedError使用_bleio.adapter访问的唯一实例已经可用。-
enabled:bool¶ BLE 适配器的状态。
-
address:Address¶ BLE 适配器的 MAC 地址。
-
name:str¶ 连接后使用的 BLE 适配器的名称。名称是“CIRCUITPY”+ 的最后四位十六进制数字
adapter.address, t以便于区分多个 CircuitPython 板。
-
advertising:bool¶ 当适配器当前正在做广告时为真。（只读）
-
connected:bool¶ 当适配器连接到另一台设备时为真，而不管是谁发起了连接。（只读）
-
connections:Tuple[Connection]¶ 活动连接的元组，包括通过
_bleio.Adapter.connect(). （只读）
-
start_advertising(self, data: _typing.ReadableBuffer, *, scan_response: Optional[_typing.ReadableBuffer] = None, connectable: bool = True, anonymous: bool = False, timeout: int = 0, interval: float = 0.1, tx_power: int = 0, directed_to: Optional[Address] = None) → None¶ 开始广告直到
stop_advertising被调用或如果可连接，另一个设备连接到我们。警告
如果数据长于 31 字节，则这将自动作为扩展广告进行广告，旧的 BLE 4.x 客户端将无法扫描。
笔记
如果设置
anonymous=True, 则必须指定超时。如果未指定超时，则将自动选择允许的最大超时。- Parameters
data (ReadableBuffer) – 广告数据包字节
scan_response (ReadableBuffer) – 扫描响应数据包字节。
None如果不需要扫描响应。timeout (int) – 如果设置，我们将只广告这么多秒。零表示没有超时。
interval (float) – 广告间隔，以秒为单位
int (tx_power) – 以 dBm 为单位广播时的发射机功率
Address (directed_to) – 直接向对等点做广告
-
start_scan(self, prefixes: _typing.ReadableBuffer = b'', *, buffer_size: int = 512, extended: bool = False, timeout: Optional[float] = None, interval: float = 0.1, window: float = 0.1, minimum_rssi: int = - 80, active: bool = True) → Iterable[ScanEntry]¶ 启动 BLE 扫描并返回结果迭代器。广告和扫描响应被分别过滤和返回。
- Parameters
prefixes (ReadableBuffer) – 用于过滤广告数据包的字节字符串前缀序列。没有匹配前缀之一的广告结构的数据包将被忽略。格式为长度（n）一个字节和前缀n个字节，并且可以重复。
buffer_size (int) – 要缓冲的最大广告字节数。
extended (bool) – 为 True 时，支持扩展广告数据包。设置时建议增加 buffer_size。
interval (float) – 两个连续扫描窗口开始之间的间隔（以秒为单位）必须在 0.0025 - 40.959375 秒的范围内。
window (float) – 扫描单个 BLE 通道的持续时间（以秒为单位）。窗口必须 <= 间隔。
minimum_rssi (int) – 要返回的条目的最小 rssi。
active (bool) – 检索可扫描广告的扫描响应。
- Returns
一个可迭代的
_bleio.ScanEntry对象- 返回类型
可迭代的
-
connect(self, address: Address, *, timeout: float) → Connection¶ 尝试连接到具有给定地址的设备。
- Parameters
address (Address) – 要连接的外设的地址
timeout (float/int) – 尝试连接超时秒。
-
-
class
_bleio.Address(address: _typing.ReadableBuffer, address_type: int)¶ 封装BLE设备的地址。
创建一个封装地址值的新地址对象。值本身可以是以下之一：
- Parameters
address (ReadableBuffer) – 要封装的地址值。一个 6 字节的缓冲区对象 (bytearray, bytes)。
address_type (int) – 整数值中的一个：
PUBLIC,RANDOM_STATIC,RANDOM_PRIVATE_RESOLVABLE, 或RANDOM_PRIVATE_NON_RESOLVABLE.
-
address_bytes:bytes¶ 构成设备地址的字节（只读）。
请注意，
bytes返回的对象是小端顺序：最低有效字节是address_bytes[0]。因此，如果您打印原始bytes对象，地址将被颠倒。如果您str()在Attribute对象本身上打印或使用，地址将按预期顺序打印。例如：>>> 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:int¶ 地址类型（只读）。
一个整数值的:
PUBLIC,RANDOM_STATIC,RANDOM_PRIVATE_RESOLVABLE, 或RANDOM_PRIVATE_NON_RESOLVABLE。
-
PUBLIC:int¶ 一个公开的地址，带有公司 ID（高 24 位）和公司分配的部分（低 24 位）。
-
RANDOM_STATIC:int¶ 不经常更改的随机生成的地址。它可能永远不会改变，或者可能会在电源循环后改变。
-
RANDOM_PRIVATE_RESOLVABLE:int¶ 当对等方知道其他设备的秘密身份解析密钥 (IRK) 时可用的地址。
-
RANDOM_PRIVATE_NON_RESOLVABLE:int¶ 随机生成的地址，每次连接都会改变。
-
class
_bleio.Attribute¶ 与所有 BLE 属性相关的定义：特性、描述符等。
Attribute理论上是Characteristic和Descriptor的超类， ，但没有定义为这些类的 Python 超类。您不能创建 的实例
Attribute.-
NO_ACCESS:int¶ 安全模式：不允许访问
-
OPEN:int¶ security_mode: 无安全性（链接未加密）
-
ENCRYPT_NO_MITM:int¶ security_mode: 未经身份验证的加密，没有中间人保护
-
ENCRYPT_WITH_MITM:int¶ security_mode: 经过身份验证的加密，具有中间人保护
-
LESC_ENCRYPT_WITH_MITM:int¶ security_mode: LESC 加密，具有中间人保护
-
SIGNED_NO_MITM:int¶ security_mode: 未经身份验证的数据签名，没有中间人保护
-
SIGNED_WITH_MITM:int¶ security_mode: 经过身份验证的数据签名，没有中间人保护
-
-
class
_bleio.Characteristic¶ 存储有关 BLE 服务特性的信息并允许读取和写入特性值。
特征没有常规的构造函数。可以通过调用创建新的本地特性并将其附加到服务
add_to_service()。远程特征对象是Connection.discover_remote_services()作为远程服务的一部分创建的。-
properties:int¶ 表示设置了哪些属性的 int 位掩码，指定为这些可能值的按位或运算。
BROADCAST,INDICATE,NOTIFY,READ,WRITE,WRITE_NO_RESPONSE.
-
uuid:Optional[UUID]¶ 此特性的 UUID。（只读）
将是
None如果这种特征的128位UUID是不知道。
-
value:bytearray¶ 这个特性的价值。
-
max_length:int¶ 此特征的最大长度。
-
descriptors:Descriptor¶ Descriptor与此特征相关的对象元组。（只读）
-
service:Service¶ 此特性所属的服务。
-
BROADCAST:int¶ 属性：允许在广告包中
-
INDICATE:int¶ 属性：服务器将在设置值时向客户端指示并等待响应
-
NOTIFY:int¶ 属性：服务器会在设置值时通知客户端
-
READ:int¶ 属性：客户端可以读取这个特性
-
WRITE:int¶ 属性：客户端可以写这个特性；回复将被发回
-
WRITE_NO_RESPONSE:int¶ 属性：客户端可以写这个特性；不会回复任何回复
-
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: Optional[_typing.ReadableBuffer] = None, user_description: Optional[str] = None) → Characteristic¶ 创建一个新的 Characteristic 对象，并将其添加到此服务中。
- Parameters
service (Service) –将提供此特性的服务
uuid (UUID) –特征的 uuid
properties (int) – 特性的属性，指定为这些值的位掩码按位或组合在一起：
BROADCAST,INDICATE,NOTIFY,READ,WRITE,WRITE_NO_RESPONSE。read_perm (int) –指定客户端是否可以读取特征，如果可以，需要哪种安全模式。必须是整数值
Attribute.NO_ACCESS,Attribute.OPEN,Attribute.ENCRYPT_NO_MITM,Attribute.ENCRYPT_WITH_MITM,Attribute.LESC_ENCRYPT_WITH_MITM,Attribute.SIGNED_NO_MITM, 或 之一Attribute.SIGNED_WITH_MITM.write_perm (int) – 指定客户端是否可以写入特征，如果可以，需要哪种安全模式。允许的值与 相同
read_perm.max_length (int) – 特征值的最大长度（以字节为单位）。允许的最大值为 512，如果
fixed_length为 False ，则可能为 510 。默认值 20 是适合单个 BLE 4.x ATT 数据包的最大数据字节数。fixed_length (bool) – 如果特征值是固定长度，则为真。
initial_value (ReadableBuffer) – 此特性的初始值。如果没有给出，将用零填充。
user_description (str) – 用户友好的特征描述
- Returns
新特性。
-
-
class
_bleio.CharacteristicBuffer(characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64)¶ 在 FIFO 缓冲区中累积特性的传入值。
监视给定的特征。每次向特性写入新值时，都会将新写入的字节添加到 FIFO 缓冲区。
- Parameters
characteristic (Characteristic) – 要监控的特性。它可能是由外围服务提供的本地特征，或者是中央已连接到的远程服务中的远程特征。
timeout (int) – 等待第一个字符和后续字符之间的超时时间（以秒为单位）。
buffer_size (int) – 存储来自客户端的传入数据的环形缓冲区的大小。必须 >= 1。
-
in_waiting:int¶ 输入缓冲区中可供读取的字节数
-
read(self, nbytes: Optional[int] = None) → Optional[bytes]¶ 读取字符。如果
nbytes指定，则最多读取那么多字节。否则，读取到达的所有内容，直到连接超时。强烈建议提供预期的字节数，因为它会更快。
-
readinto(self, buf: _typing.WriteableBuffer) → Optional[int]¶ 将字节读入
buf. 最多读取len(buf)字节。
-
class
_bleio.Connection¶ 到另一台设备的 BLE 连接。用于发现其他设备上的服务并与之交互。
用法：
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)
不能直接建立连接。相反，要启动连接，请使用
Adapter.connect当另一个设备发起连接时，也可以建立连接。要使用由对等方创建的连接，请阅读该Adapter.connections属性。-
connected:bool¶ 如果连接到远程对等方，则为真。
-
paired:bool¶ 如果与远程对等方配对，则为真。
-
connection_interval:float¶ 传输之间的时间（以毫秒为单位）。将是 1.25ms 的倍数。较低的数字会提高速度并减少延迟，但会增加功耗。
设置 connection_interval 时，对等方可能会拒绝新的时间间隔，
connection_interval然后将保持不变。Apple 有额外的指导方针，规定应该是 15 毫秒的倍数，除非 HID 可用。当 HID 可用时，Apple 设备可能接受 11.25 毫秒的间隔。
-
max_packet_length:int¶ 在单次传输中可以发送的最大数据字节数，不包括开销字节。
这是通知中可以发送的最大字节数，必须在单个数据包中发送。但是对于一个普通的特征读或者写，可能会分多个包发送，所以这个限制不适用。
-
discover_remote_services(self, service_uuids_whitelist: Optional[Iterable[UUID]] = None) → Tuple[Service, Ellipsis]¶ 对所有服务或给定服务 UUIDS 进行 BLE 发现，以找到它们的句柄和特征，并返回发现的服务。
Connection.connected必须是 True。- Parameters
service_uuids_whitelist (iterable) –
an iterable of
UUID您要使用的外围设备提供的服务的对象的可迭代对象。外设可能提供更多服务，但未列出的服务将被忽略且不会返回。
如果 service_uuids_whitelist 为 None，则所有服务都将进行发现，这可能会很慢。
如果服务 UUID 是 128 位，或其特征 UUID 是 128 位，您必须已经
UUID为该 UUID创建了一个对象，以便发现服务或特征。创建 UUID 会导致注册 UUID 以供使用。（未来可能会取消此限制。）- Returns
_bleio.Service远程外围设备提供的对象元组。
-
-
class
_bleio.Descriptor¶ 存储有关 BLE 描述符的信息。
描述符附加到 BLE 特性并提供有关特性的上下文信息。
描述符没有常规的构造函数。可以通过调用创建新的本地描述符并将其附加到特征
add_to_characteristic()。远程描述符对象是由Connection.discover_remote_services()发现的远程服务中的远程特征的一部分创建的。-
uuid:UUID¶ 描述符 uuid。（只读）
-
characteristic:Characteristic¶ 此描述符所属的特征。
-
value:bytearray¶ 此描述符的值。
-
classmethod
add_to_characteristic(cls, characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: _typing.ReadableBuffer = b'') → Descriptor¶ 创建一个新的 Descriptor 对象，并将其添加到此服务中。
- Parameters
characteristic (Characteristic) – 将保存此描述符的特征
uuid (UUID) – 描述符的 uuid
read_perm (int) – 指定客户端是否可以读取描述符，如果可以，需要哪种安全模式。必须是整数值
Attribute.NO_ACCESS,Attribute.OPEN,Attribute.ENCRYPT_NO_MITM,Attribute.ENCRYPT_WITH_MITM,Attribute.LESC_ENCRYPT_WITH_MITM,Attribute.SIGNED_NO_MITM, 或 之一Attribute.SIGNED_WITH_MITM。write_perm (int) – 指定描述符是否可以由客户端写入，如果可以，需要哪种安全模式。允许的值与 相同
read_perm。max_length (int) – 描述符值的最大长度（以字节为单位）。允许的最大值为 512，如果
fixed_length为 False ，则可能为 510 。默认值 20 是适合单个 BLE 4.x ATT 数据包的最大数据字节数fixed_length (bool) – 如果描述符值为固定长度，则为真。
initial_value (ReadableBuffer) – 此描述符的初始值。
- Returns
新的描述符。
-
-
class
_bleio.PacketBuffer(characteristic: Characteristic, *, buffer_size: int, max_packet_size: Optional[int] = None)¶ 在 FIFO 缓冲区中累积特性的传入数据包，并促进数据包感知传出写入。数据包的大小是特征长度或最大传输单元 (MTU) 减去开销，以较小者为准。MTU值可以改变，因此检查
incoming_packet_length并outgoing_packet_length创建一个缓冲区来存储数据之前。当我们是服务器时，除了第一个订阅通知的连接之外，我们会忽略所有连接。
监视给定的特征。每次向特性写入新值时，都会将新写入的字节添加到 FIFO 缓冲区。
监视给定的特征。每次向特性写入新值时，都会将新写入的字节数据包添加到 FIFO 缓冲区。
- Parameters
characteristic (Characteristic) – 要监控的特性。它可能是由外围服务提供的本地特征，或者是中央已连接到的远程服务中的远程特征。
buffer_size (int) – 环形缓冲区的大小（以特征最大长度的数据包为单位），用于存储来自对等方的传入数据包。
max_packet_size (int) – 数据包的最大大小。覆盖特征中的值。（远程特征可能没有正确的长度。）
-
incoming_packet_length:int¶ 我们正在读取的数据包的最大长度（以字节为单位）。
-
outgoing_packet_length:int¶ 我们正在写入的数据包的最大长度（以字节为单位）。
-
readinto(self, buf: _typing.WriteableBuffer) → int¶ 将单个 BLE 数据包读入
buf. 如果下一个数据包比给定的缓冲区长，则引发异常。使用incoming_packet_length读取单个数据包的最大长度。- Returns
读取和存储的字节数
buf- 返回类型
-
write(self, data: _typing.ReadableBuffer, *, header: Optional[bytes] = None) → int¶ 将数据中的所有字节写入同一个传出数据包。当挂起的数据包当前为空时，报头中的字节包含在数据之前。
在发送数据之前这不会阻塞。它只会阻塞直到数据挂起。
- Returns
写入的字节数。当数据包为空时，可能包括报头字节。
- 返回类型
-
class
_bleio.ScanEntry¶ 封装有关在扫描期间收到的设备的信息。它可以是广告或扫描响应数据。此对象只能由 a 创建
_bleio.ScanResults：它没有用户可见的构造函数。不能直接实例化。使用
_bleio.Adapter.start_scan.-
address:Address¶ 设备的地址（只读），类型为
_bleio.Address.
-
advertisement_bytes:bytes¶ 数据包中存在的所有广告数据，作为
bytes对象返回。（只读）
-
rssi:int¶ 扫描时设备的信号强度，以整数 dBm 为单位。（只读）
-
connectable:bool¶ 如果设备可以连接到，则为真。（只读）
-
scan_response:bool¶ 如果条目是扫描响应，则为真。（只读）
-
-
class
_bleio.ScanResults¶ 迭代扫描时收到的广告数据。此对象始终由 a 创建
_bleio.Adapter:它没有用户可见的构造函数。不能直接实例化。使用
_bleio.Adapter.start_scan.-
__next__(self) → ScanEntry¶ 返回下一个
_bleio.ScanEntry。如果没有收到并且扫描仍处于活动状态，则阻止。StopIteration如果扫描完成且没有其他可用结果，则引发。
-
-
class
_bleio.Service(uuid: UUID, *, secondary: bool = False)¶ 存储有关 BLE 服务及其特征的信息。
创建由指定的 UUID 标识的新服务。它可以被所有连接访问。这称为服务服务器。客户服务对象是通过
Connection.discover_remote_services.要将服务标记为次要服务，请将其
True作为secondary.-
characteristics:Tuple[Characteristic, Ellipsis]¶ Characteristic指定此服务提供的特征的元组。（只读）
-
remote:bool¶ 如果这是远程设备提供的服务，则为真。（只读）
-
secondary:bool¶ 如果这是次要服务，则为真。（只读）
-
uuid:Optional[UUID]¶ 此服务的 UUID。（只读）
会
None如果该服务的128-bit的UUID是不知道。
-
-
class
_bleio.UUID(value: Union[int, _typing.ReadableBuffer, str])¶ 16 位或 128 位 UUID。可用于服务、特征、描述符等。
创建一个新的 UUID 或 UUID 对象来封装 uuid 值。该值可以是以下之一：
int0 到 0xFFFF 范围内的值（蓝牙 SIG 16 位 UUID）按小端顺序（128 位 UUID）的 16 字节缓冲区对象（字节数组、字节）
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' 形式的一串十六进制数字
创建 128 位 UUID 会将 UUID 注册到板载 BLE 软件，并提供一个临时的 16 位 UUID，可用于代替完整的 128 位 UUID。
- 参数
value (int, ReadableBuffer 或 str) – 要封装的 uuid 值
-
size:int¶ 128 如果此 UUID 表示 128 位供应商特定的 UUID。16 如果此 UUID 表示 16 位蓝牙 SIG 分配的 UUID。（只读）当前不支持 32 位 UUID。
- Type
-
pack_into(self, buffer: _typing.WriteableBuffer, offset: int = 0) → None¶ 在给定的偏移量处将 UUID 打包到给定的缓冲区中。