PySide6.QtBluetooth.QLowEnergyController

class QLowEnergyController

QLowEnergyController 类提供了对蓝牙低功耗设备的访问。更多…

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 Error

指示控制器存在期间发现的所有可能的错误条件。

常量

描述

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 上，处理服务器端的“Signed Write” ATT 命令需要 BlueZ 5 和内核版本 3.7 或更高版本。

另请参阅

createCentral() createPeripheral()

addService(service[, parent=None])
Parameters:
Return type:

QLowEnergyService

构造并返回一个带有parent的QLowEnergyService对象，该对象来自service。控制器必须处于PeripheralRole和UnconnectedState状态。service对象必须有效。

注意

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

另请参阅

stopAdvertising() disconnectFromDevice() addIncludedService

connectToDevice()

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

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

在Linux/BlueZ系统上，无法使用此类的两个实例连接到同一个远程设备。对此函数的第二次调用可能会失败并返回错误。此限制可能会在未来的版本中移除。

另请参阅

disconnectFromDevice()

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])
Parameters:
Return type:

QLowEnergyController

返回此类的一个新对象，该对象位于CentralRole中，并具有父对象parent。remoteDevice指的是稍后将建立连接的设备。

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

另请参阅

CentralRole

static createCentral(remoteDevice, localDevice[, parent=None])
Parameters:
Return type:

QLowEnergyController

返回该类的一个新实例，带有parent。

remoteDevice 必须包含远程蓝牙低功耗设备的地址，该对象稍后应尝试连接到此设备。

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

请注意，只有在使用BlueZ时才能指定用于连接的本地设备。所有其他平台都不支持此功能。

static createPeripheral([parent=None])
Parameters:

父对象 – QObject

Return type:

QLowEnergyController

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

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

另请参阅

PeripheralRole

static createPeripheral(localDevice[, parent=None])
Parameters:
Return type:

QLowEnergyController

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

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

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

另请参阅

PeripheralRole

createServiceObject(service[, parent=None])
Parameters:
Return type:

QLowEnergyService

创建一个由serviceUuid表示的服务实例。serviceUuid参数必须通过services()获得。

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

如果远程设备上找不到具有serviceUuid的服务或控制器断开连接，此函数将返回空指针。

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

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

另请参阅

services()

disconnectFromDevice()

断开与远程设备的连接。

任何由当前连接产生的QLowEnergyService、QLowEnergyCharacteristic或QLowEnergyDescriptor实例将自动失效。一旦这些对象中的任何一个失效，即使此控制器对象重新连接，它们也将保持失效状态。

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

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

另请参阅

connectToDevice()

disconnected()

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

discoverServices()

启动服务发现过程。

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

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

注意

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

discoveryFinished()

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

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

error()
Return type:

错误

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

errorOccurred(newError)
Parameters:

newError – Error

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

另请参阅

error() errorString()

errorString()
Return type:

字符串

返回最后一次发生错误的文本表示。该字符串已被翻译。

localAddress()
Return type:

QBluetoothAddress

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

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

另请参阅

isNull()

mtu()
Return type:

整数

返回MTU大小。

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

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

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

如果控制器处于PeripheralRole，可能会有多个中央设备连接到它。在这种情况下，此函数返回最后协商的连接的MTU。

mtuChanged(mtu)
Parameters:

mtu – int

此信号是在MTU成功更改后发出的。mtu 表示新值。

注意

如果控制器处于PeripheralRole，MTU值会为每个客户端/中央设备单独协商。因此，对于一个或多个设备，此信号可能会连续多次发出。

另请参阅

mtu()

readRssi()

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

注意

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

注意

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

另请参阅

rssiRead() connectToDevice() state() createCentral() errorOccurred()

remoteAddress()
Return type:

QBluetoothAddress

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

对于CentralRole中的控制器，此值将始终是创建控制器对象时传入的值。对于PeripheralRole中的控制器，此值是当前连接的客户端设备地址之一。如果控制器当前不在ConnectedState中，则此地址将无效。

remoteAddressType()
Return type:

RemoteAddressType

返回remoteAddress()的类型。默认情况下，此值初始化为PublicAddress。

另请参阅

setRemoteAddressType()

remoteDeviceUuid()
Return type:

QBluetoothUuid

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

在macOS/iOS/tvOS上，CoreBluetooth不暴露/接受LE设备的硬件地址；相反，开发人员应该使用由CoreBluetooth生成的唯一128位UUID。这些UUID对于相同的中枢<->外设对将保持不变，我们在连接到远程设备时使用它们。对于处于CentralRole的控制器，此值将始终是创建控制器对象时传入的值。对于处于PeripheralRole的控制器，此值无效。

remoteName()
Return type:

字符串

如果控制器处于CentralRole，则返回远程蓝牙低功耗设备的名称。否则结果未指定。

requestConnectionUpdate(parameters)
Parameters:

参数 – QLowEnergyConnectionParameters

请求控制器根据parameters更新连接。如果请求成功，将会发出connectionUpdated()信号，并附带实际的新参数。有关连接参数的更多信息，请参见QLowEnergyConnectionParameters类。

Android 仅间接允许调整此参数集。连接参数分为三类（高、低和平衡优先级）。每个类别都暗示了 minimumInterval()、maximumInterval() 和 latency() 的预配置值集。尽管连接请求是一个异步操作，但 Android 并未提供说明请求结果的回调。这是一个公认的 Android 错误。由于此错误，Android 不会发出 connectionUpdated() 信号。

注意

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

另请参阅

connectionUpdated()

role()
Return type:

角色

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

角色在构造QLowEnergyController实例时确定，使用createCentral()或createPeripheral()。

rssiRead(rssi)
Parameters:

rssi – int

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

另请参阅

readRssi()

serviceDiscovered(newService)
Parameters:

newService – QBluetoothUuid

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

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

services()
Return type:

QBluetoothUuid的列表

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

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

另请参阅

createServiceObject()

setRemoteAddressType(type)
Parameters:

类型 – 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()])
Parameters:

开始使用parameters中设置的参数来广告advertisingData和scanResponseData中的数据。控制器必须处于PeripheralRole角色。如果parameters指示广告应该是可连接的，那么此函数还会开始监听传入的客户端连接。

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

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

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

另请参阅

stopAdvertising()

state()
Return type:

ControllerState

返回控制器的当前状态。

另请参阅

stateChanged()

stateChanged(state)
Parameters:

状态 – ControllerState

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

另请参阅

state()

stopAdvertising()

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

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

另请参阅

startAdvertising()