class QLowEnergyController#

QLowEnergyController 类提供了对低功耗蓝牙设备的访问。详情...

Inheritance diagram of PySide6.QtBluetooth.QLowEnergyController

简述

方法

信号#

静态函数#

备注

此文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译中的问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单的方式告诉我们

详细描述#

QLowEnergyController 充当蓝牙低功耗开发的入口点。

蓝牙低功耗定义了两种类型的设备：外围设备和中心设备。每个角色执行不同的任务。外围设备提供由中心设备使用的数据。一个例子是湿度传感器，该传感器测量冬季花园中的水分。如手机之类的设备可以读取传感器的值，并在同一环境中的所有传感器的更大范围内将其显示给用户。在这种情况下，传感器是外围设备，手机充当中心设备。

通过 createCentral() 生产方法创建一个中心角色的控制器。这样一个对象在本质上作为一个远程低功耗外围设备的占位符，允许服务发现和状态跟踪等功能。

在创建一个在中央起作用的控制器对象之后，第一步是通过connectToDevice() 方法建立连接。一旦连接建立，控制器的state() 状态会变为ConnectedState，并发出connected() 信号。需要注意的是，一些平台如基于BlueZ的Linux不能维护同一个远程设备的两个QLowEnergyController 实例的连接。在这种情况下，对connectToDevice() 的第二次调用可能会失败。这种限制在未来某个阶段可能会消失。使用disconnectFromDevice() 函数用于断开现有连接。

在建立连接后，第二步是发现远程外围设备提供的服务。此过程通过discoverServices() 方法启动，一次当发出discoveryFinished() 信号时，这个过程就完成了。已发现的服务可以通过services() 进行枚举。

最后一步是创建服务对象。createServiceObject() 方法充当每个服务对象的工厂，并期望将服务UUID作为参数。调用上下文应负责返回的QLowEnergyService 实例的所有权。

从这个控制器连接随后创建的任何QLowEnergyService ，QLowEnergyCharacteristic 或 QLowEnergyDescriptor 实例在控制器从远程低功耗蓝牙设备断开连接后立即失效。

应用外部角色的控制器通过createPeripheral() 工厂方法创建。此类对象本身充当外围设备，启用广告服务等功能，并允许客户端在特征值发生变化时接收通知。

在外部角色创建控制器对象后，第一步是调用 addService() 方法来填充客户端设备提供的 GATT 服务集。之后，将调用 startAdvertising() 方法，让设备广播一些数据，并根据正在进行的广告类型，也侦听来自 GATT 客户端的传入连接。

class 错误#

表示在控制器存在期间找到的所有可能的错误条件。

常量

描述

QLowEnergyController.NoError

未发生错误。

QLowEnergyController.UnknownError

发生了未知错误。

QLowEnergyController.UnknownRemoteDeviceError

在构造函数传入的地址中找不到远程低功耗蓝牙设备。

QLowEnergyController.NetworkError

尝试从远程设备读取或写入失败。

QLowEnergyController.InvalidBluetoothAdapterError

找不到构造函数传入地址的本地蓝牙设备，或没有本地蓝牙设备。

QLowEnergyController.ConnectionError

尝试连接到远程设备失败。

QLowEnergyController.AdvertisingError

启动广告失败。

QLowEnergyController.RemoteHostClosedError

远程设备关闭了连接。

QLowEnergyController.AuthorizationError

由于授权不足，本地蓝牙设备关闭了连接。

QLowEnergyController.MissingPermissionsError

操作系统请求未经用户授权的权限。

QLowEnergyController.RssiReadError

读取远程设备的 RSSI（接收信号强度指示器）失败。
class ControllerState#

表示控制器对象的状态。

常量

描述

QLowEnergyController.UnconnectedState

控制器未连接到远程设备。

QLowEnergyController.ConnectingState

控制器正在尝试连接到远程设备。

QLowEnergyController.ConnectedState

控制器已连接到远程设备。

QLowEnergyController.DiscoveringState

控制器正在获取远程设备提供的服务的列表。

QLowEnergyController.DiscoveredState

控制器已经发现远程设备提供的所有服务。

QLowEnergyController.ClosingState

控制器即将与远程设备断开连接。

QLowEnergyController.AdvertisingState

控制器正在广播数据。
class RemoteAddressType#

指示远程设备使用的蓝牙地址类型。

常量

描述

QLowEnergyController.PublicAddress

远程设备使用公共蓝牙地址。

QLowEnergyController.RandomAddress

随机地址是蓝牙低功耗的一个安全特性。使用这种地址的外设可能会频繁更改其蓝牙地址。在尝试连接到外设时需要此信息。
class Role#

指示控制器对象的角色。

常量

描述

QLowEnergyController.CentralRole

控制器作为客户端与处于外设角色的远程设备交互。控制器可以发起连接、发现服务和读取/写入特性。

QLowEnergyController.PeripheralRole

控制器可以用来广播服务并处理传入的连接和客户端请求，作为GATT服务器。连接到控制器的远程设备处于中心角色。

备注

在外设角色不受Windows支持。另外，在Linux上，处理服务器端的“签名写入”ATT命令需要BlueZ 5和内核版本3.7或更高。

参阅

createCentral() createPeripheral()

addService(service[, parent=None])#
参数:
返回类型:

QLowEnergyService

从service构建并返回一个具有parent的QLowEnergyService对象。控制器必须在PeripheralRole和UnconnectedState。服务对象必须是有效的。

备注

一旦外围实例从远程中心设备断开连接，或者如果手动调用了disconnectFromDevice()，那么通过此函数之前添加的所有服务定义都将从外围设备中删除。因此，在此外围控制器实例重新广播之前，必须再次调用此函数。描述的行为是针对特定连接的，因此不依赖于是否调用了stopAdvertising()。

参阅

stopAdvertising() disconnectFromDevice() addIncludedService

connectToDevice()#

连接到远程低功耗蓝牙设备。

如果控制器的状态不等于UnconnectedState，则此函数不做任何操作。一旦连接成功建立，将发出connected()信号。

在Linux/BlueZ系统上，不能使用此类的两个实例连接到同一远程设备。此函数的第二次调用可能失败，并出现错误。这种限制可能在未来的版本中取消。

connected()#

当控制器成功连接到远程低能耗设备（如果控制器处于CentralRole）或者如果一个远程低能耗设备连接到了控制器（如果控制器处于PeripheralRole）时，将发出此信号。在iOS、macOS和Android上，如果控制器处于PeripheralRole，此信号不可靠。在iOS和macOS上，控制器只是在中心尝试写入/读取特征/描述符时猜测连接到了我们的外围。在Android上，控制器监视所有已连接的GATT设备。在Linux BlueZ DBus外围后端，当远程设备第一次读取/写入特征或描述符时，它被视为已连接。

connectionUpdated(parameters)#
参数:

parameters – QLowEnergyConnectionParameters

此信号在连接参数发生变化时发出。这可能是调用requestConnectionUpdate()的结果，也可能是由于其他原因，例如，因为连接的对方请求了新的参数。新的值可以从newParameters中检索。

static createCentral(remoteDevice[, parent=None])#
参数:
返回类型:

QLowEnergyController

返回一个新对象，处于CentralRole并且具有父对象parent。参数remoteDevice是指稍后将要建立连接的设备。

控制器使用本地默认的蓝牙适配器进行连接管理。

参阅

CentralRole

static createCentral(remoteDevice, localDevice[, parent=None])
参数:
返回类型:

QLowEnergyController

返回一个新实例，具有parent。

参数remoteDevice必须包含要与其后面连接的远程蓝牙低功耗设备的地址。

通过localDevice建立连接。如果localDevice无效，则自动选择本地默认设备。如果localDevice指定了不是本地蓝牙适配器的本地设备，则在调用connectToDevice()时，error()被设置为InvalidBluetoothAdapterError。

请注意，在非BlueZ平台上，无法指定用于连接的本地设备。所有其他平台都不支持此功能。

静态 createPeripheral([parent=None])#
参数:

parent – QObject

返回类型:

QLowEnergyController

返回一个新的对象，该对象属于 PeripheralRole 角色并且具有父对象 parent。通常，接下来的步骤是添加一些服务，最后在返回的对象上调用 startAdvertising()。

控制器使用本地默认的蓝牙适配器进行连接管理。

静态 createPeripheral(localDevice[, parent=None])
参数:
返回类型:

QLowEnergyController

返回一个新对象，该对象属于 PeripheralRole 角色以及具有父对象 parent 和正在使用 localDevice。通常，接下来的步骤是添加一些服务，最后在返回的对象上调用 startAdvertising()。

外围设备在 localDevice 上创建。如果 localDevice 无效，则自动选择本地默认设备。如果 localDevice 指定了一个不是本地蓝牙适配器的本地设备，则 error() 设置为 InvalidBluetoothAdapterError。

localDevice 的选择仅在 Linux 上受支持。在其他平台上，该参数将被忽略。

createServiceObject(service[, parent=None])#
参数:
返回类型:

QLowEnergyService

创建代表 serviceUuid 的服务的实例。参数 serviceUuid 必须通过 services() 获取。

调用者拥有返回的指针的所有权，并且可以将 parent 参数作为默认所有者传递。

此函数在远程设备中找不到对应 serviceUuid 的服务或控制器断开连接时返回空指针。

此函数还可以返回次要服务的实例。通过 includedServices() 表达服务之间的包含关系。

如果多次调用此函数使用相同的service UUID，则返回的 QLowEnergyService 实例将共享其内部数据。因此，如果其中一个实例启动服务细节的发现，其他实例也会自动进入发现状态。

参阅

services()

disconnectFromDevice()#

断开与远程设备的连接。

任何由当前连接产生的 QLowEnergyService ， QLowEnergyCharacteristic 或 QLowEnergyDescriptor 实例都会自动失效。一旦这些对象之一变得无效，即使控制器对象重新连接，它们仍然无效。

如果控制器处于 UnconnectedState 状态，此函数不会执行任何操作。

如果控制器处于外围角色，它将停止广播并移除所有通过 addService() 添加的服务。为了重用 QLowEnergyController 实例，应用程序必须重新添加服务并通过调用 startAdvertising() 重新启动广播模式。

disconnected()#

当控制器从远程低功耗设备断开连接或反之亦然时，会发出此信号。在iOS和macOS上，如果控制器处于 PeripheralRole 角色，则此信号不可靠。在Android上，该信号在最后一个连接的设备断开连接时发出。在BlueZ DBus后端，当最后访问了属性的客户端断开连接时，将控制器视为断开连接。

discoverServices()#

启动服务发现过程。

发现进度通过 serviceDiscovered() 信号表示。当过程完成时，会发出 discoveryFinished() 信号。

如果控制器实例未连接或控制器已执行过服务发现，则此函数将不会执行任何操作。

备注

一些平台内部缓存了之前发现设备的服务列表。如果远程设备更改了其服务列表或包含的树，则可能会出现问题。如果这种行为是问题，最好的解决方案是暂时关闭蓝牙。这将重置缓存数据。目前Android表现出了这种缓存行为。

discoveryFinished()#

当正在运行的服务发现完成时，会发出此信号。如果发现过程因错误而完成，则不会发出信号。

只有当控制器处于 CentralRole 时才能发出此信号。

error()#
返回类型:

错误

返回最后一个发生的错误或 NoError 。

errorOccurred(newError)#
参数:

**newError** – Error

当发生错误时，会发出此信号。`newError` 参数描述了发生的错误。

errorString()#
返回类型:

str

返回最后一个发生的错误的文本表示形式。字符串已翻译。

localAddress()#
返回类型:

QBluetoothAddress

返回用于通信的本地蓝牙适配器的地址。

如果此类实例请求使用默认适配器，但在创建此类实例时没有默认适配器，则返回的 QBluetoothAddress 将为 null。

参阅

isNull()

mtu()链接到该定义
返回类型:

int

返回MTU大小。

在连接设置期间，ATT MTU大小会被协商。此方法提供协商的结果。在某些情况下，可以利用此方法优化包大小。单个数据包可以传输的最大数据量为mtu-3字节（3个字节用于ATT协议头）。

在设置连接和MTU协商之前，将返回默认值23。

并非每个平台都公开MTU值。在这些平台（例如Linux）上，此函数总是返回-1。

如果控制器处于PeripheralRole角色，可能连接了几个中心设备。在这些情况下，此函数返回最后协商的连接的MTU值。

mtuChanged(mtu)链接到该定义
参数:

mtu - int

此信号会在MTU更改成功时发出。<code class="docutils literal notranslate"><span class="pre">mtu</span></code>代表新的值。

备注

如果控制器处于PeripheralRole角色，每个客户端/中心设备的MTU值都会单独协商。因此，对于一台或几台设备，这种信号可能会连续发出多次。

参阅

mtu()

readRssi()链接到该定义

readRssi()读取已连接远程设备的RSSI（接收信号强度指示）。如果读取成功，RSSI将通过rssiRead()信号报告。

备注

在调用readRssi()之前，此控制器必须连接到一个外围设备。此控制器必须使用createCentral()方法创建。

备注

如果您使用的蓝牙后端不支持读取RSSI，将发出带有错误代码RssiReadError的errorOccurred()信号。目前支持读取RSSI的平台包括Android、iOS和macOS。

参阅

返回类型:

QBluetoothAddress

返回远程低功耗蓝牙设备的地址。

对于处于

返回类型:

远程地址类型

返回

返回类型:

QBluetoothUuid

返回远程低功耗蓝牙设备的唯一标识符。

在macOS/iOS/tvOS上，CoreBluetooth不会公开或接受LE设备的硬件地址；相反，开发人员应使用由CoreBluetooth生成的唯一128位UUID。这些UUID对于相同的中心 <-> 外围设备对将保持一致，并在连接到远程设备时使用。对于处于

返回类型:

str

如果控制器处于

requestConnectionUpdate(parameters)#
参数:

parameters – QLowEnergyConnectionParameters

请求控制器根据 parameters 更新连接。如果请求成功，则将发射一个带有实际新参数的 connectionUpdated() 信号。有关连接参数的更多信息，请参阅 QLowEnergyConnectionParameters 类。

在 Android 上，仅允许间接调整此参数集。连接参数分为三类（高、低 & 平衡优先级）。每一类意味着 minimumInterval() 、maximumInterval() 和 latency() 的预配置值集合。尽管连接请求是一个异步操作，但 Android 不提供表示请求结果的回调。这是一个公认的 Android 错误。由于这个错误，Android 不发射 connectionUpdated() 信号。

备注

目前，此功能仅在 Linux 内核后端和 Android 上实现。

参阅

connectionUpdated()

role()#
返回类型:

角色

返回此控制器对象所处的角色。

当一个 QLowEnergyController 实例使用 createCentral() 或 createPeripheral() 创建时，将确定角色。

rssiRead(rssi)#
参数:

rssi – int

成功读取连接远程设备的 RSSI（接收信号强度指示器）后，会发射此信号。参数 rssi 表示新值。

参阅

readRssi()

serviceDiscovered(newService)#
参数:

newService – QBluetoothUuid

每次发现新的服务时都会发射此信号。newService 参数包含找到的服务的 UUID。

只有当控制器处于 CentralRole 时，此信号才能发射。

services()#
返回类型:

列表包含 QBluetoothUuid

如果控制器处于 CentralRole，则返回由远程设备提供的服务的列表。否则，结果是不确定的。

列表包含所有主要和次要服务。

setRemoteAddressType(type)#
参数:

type – RemoteAddressType

设置远程地址 type。该类型是连接到远程蓝牙低功耗设备所必需的。

此属性仅在较旧的 Linux 内核（v3.3 或更低版本）的 Linux/BlueZ 系统上以及在可执行文件未设置 CAP_NET_ADMIN 的系统上才需要。属性的默认值是 RandomAddress。

备注

所有其他平台都透明地处理此标志，因此应用程序可以完全忽略它。在 Linux 上，BlueZ 不会直接公开地址类型标志，尽管一些用例需要此信息。检测标志的唯一方法是通过 Linux 内核的蓝牙管理 API（需要内核版本 3.4+）。此 API 需要 CAP_NET_ADMIN 权限。如果本地的 QtBluetooth 进程设置了此功能，则 QtBluetooth 将使用此 API。这假定在调用 connectToDevice() 之前使用了 QBluetoothDeviceDiscoveryAgent。

参阅

remoteAddressType()

startAdvertising(parameters, advertisingData[, scanResponseData=QLowEnergyAdvertisingData()])#
参数:

开始广播在 advertisingData 和 scanResponseData 中的数据，使用在 parameters 中设置的参数。控制器必须处于 PeripheralRole 状态。如果 parameters 指示广告应为可连接的，则此函数还开始监听传入的客户端连接。

提供 scanResponseData 不是必需的，因为对于某些配置的 parameters，它不适用。advertisingData 和 scanResponseData 用户数据限制为 31 个字节。例如，如果将多个 128 位 uuid 添加到 advertisingData 中，则广告包可能不包含所有 uuid。现有的限制可能已导致 uuid 的截断。在这些情况下，可以使用 scanResponseData 来提供更多信息。

在 BlueZ DBus 后端，BlueZ 决定在扫描响应中使用哪些数据，以及使用哪些数据。因此，建议在主 advertisingData 参数中设置所有广告数据。如果同时设置了广告和扫描响应数据，则优先考虑扫描响应数据。

如果此对象当前不在 UnconnectedState 状态，则不会发生任何操作。

state()#
返回类型:

ControllerState

返回控制器的当前状态。

stateChanged(state)#
参数:

state – ControllerState

当控制器状态改变时，会发出此信号。新的 state 也可以通过 state() 方法获取。

参阅

state()

stopAdvertising()#

停止广播，如果此对象当前处于广告状态。

控制器必须处于PeripheralRole，此功能才能正常工作。它不会使之前通过addService()添加的服务失效。