QBluetoothLocalDevice#
The QBluetoothLocalDevice
class enables access to the local Bluetooth device. More…
Synopsis#
Functions#
def
address
()def
connectedDevices
()def
hostMode
()def
isValid
()def
name
()def
pairingStatus
(address)def
powerOn
()def
requestPairing
(address, pairing)def
setHostMode
(mode)
Signals#
def
deviceConnected
(address)def
deviceDisconnected
(address)def
errorOccurred
(error)def
hostModeStateChanged
(state)def
pairingFinished
(address, pairing)
Static functions#
def
allDevices
()
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
Detailed Description#
QBluetoothLocalDevice
provides functions for getting and setting the state of local Bluetooth devices.
On iOS, this class cannot be used because the platform does not expose any data or API which may provide information on the local Bluetooth device.
- class PySide6.QtBluetooth.QBluetoothLocalDevice([parent=None])#
PySide6.QtBluetooth.QBluetoothLocalDevice(address[, parent=None])
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
parent –
PySide6.QtCore.QObject
Constructs a QBluetoothLocalDevice
with parent
.
Note
Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also
Construct new QBluetoothLocalDevice
for address
. If address
is default constructed the resulting local device selects the local default device.
Note
Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also
- PySide6.QtBluetooth.QBluetoothLocalDevice.Pairing#
This enum describes the pairing state between the two Bluetooth devices.
Constant
Description
QBluetoothLocalDevice.Unpaired
The Bluetooth devices are not paired.
QBluetoothLocalDevice.Paired
The Bluetooth devices are paired. The system will prompt the user for authorization when the remote device initiates a connection to the local device.
QBluetoothLocalDevice.AuthorizedPaired
The Bluetooth devices are paired. The system will not prompt the user for authorization when the remote device initiates a connection to the local device.
- PySide6.QtBluetooth.QBluetoothLocalDevice.HostMode#
This enum describes the most of the local Bluetooth device.
Constant
Description
QBluetoothLocalDevice.HostPoweredOff
Power off the device
QBluetoothLocalDevice.HostConnectable
Remote Bluetooth devices can connect to the local Bluetooth device if they have previously been paired with it or otherwise know its address. This powers up the device if it was powered off.
QBluetoothLocalDevice.HostDiscoverable
Remote Bluetooth devices can discover the presence of the local Bluetooth device. The device will also be connectable, and powered on. On Android, this mode can only be active for a maximum of 5 minutes.
QBluetoothLocalDevice.HostDiscoverableLimitedInquiry
Remote Bluetooth devices can discover the presence of the local Bluetooth device when performing a limited inquiry. This should be used for locating services that are only made discoverable for a limited period of time. This can speed up discovery between gaming devices, as service discovery can be skipped on devices not in LimitedInquiry mode. In this mode, the device will be connectable and powered on, if required. This mode is is not supported on Android.
Note
On macOS, it is not possible to set the hostMode()
to HostConnectable or HostPoweredOff.
Note
On Windows, it is not possible to set the hostMode()
to HostDiscoverable or HostDiscoverableLimitedInquiry. Using these modes is equivalent to HostConnectable.
Note
Starting from Android 13 (API level 33) the HostPoweredOff state relies on non-public Android API as the public one has been deprecated, see ( disable() ). This may change in a future version of Android.
Note
At least on Android 12 the device’s Bluetooth visibility setting may dictate the result of setting either HostDiscoverable or HostConnectable. For example if the visibility is set off, it may not be possible to enter the HostDiscoverable mode, but HostConnectable will be used instead. This may change in future version of Android.
- PySide6.QtBluetooth.QBluetoothLocalDevice.Error#
This enum describes errors that maybe returned
Constant
Description
QBluetoothLocalDevice.NoError
No known error
QBluetoothLocalDevice.PairingError
Error in pairing
QBluetoothLocalDevice.MissingPermissionsError
The operating system requests permissions which were not granted by the user.
QBluetoothLocalDevice.UnknownError
Unknown error
- PySide6.QtBluetooth.QBluetoothLocalDevice.address()#
- Return type:
Returns the MAC address of this Bluetooth device.
Note
On Android, this function always returns the constant value 02:00:00:00:00:00
as local address starting with Android 6.0. The programmatic access to the device’s local MAC address was removed.
- static PySide6.QtBluetooth.QBluetoothLocalDevice.allDevices()#
- Return type:
.list of QBluetoothHostInfo
Returns a list of all available local Bluetooth devices. On macOS, there is only the “default” local device.
- PySide6.QtBluetooth.QBluetoothLocalDevice.connectedDevices()#
- Return type:
.list of QBluetoothAddress
Returns the list of connected devices. This list is different from the list of currently paired devices.
On Android and macOS, it is not possible to retrieve a list of connected devices. It is only possible to listen to (dis)connect changes. For convenience, this class monitors all connect and disconnect events since its instanciation and returns the current list when calling this function. Therefore it is possible that this function returns an empty list shortly after creating an instance.
See also
- PySide6.QtBluetooth.QBluetoothLocalDevice.deviceConnected(address)#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
This signal is emitted when the local device establishes a connection to a remote device with address
.
See also
- PySide6.QtBluetooth.QBluetoothLocalDevice.deviceDisconnected(address)#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
This signal is emitted when the local device disconnects from a remote Bluetooth device with address
.
See also
Signal emitted if there’s an exceptional error
while pairing.
Returns the current host mode of this local Bluetooth device. On macOS, it is either HostPoweredOff
or HostConnectable
.
See also
The state
of the host has transitioned to a different HostMode
.
- PySide6.QtBluetooth.QBluetoothLocalDevice.isValid()#
- Return type:
bool
Returns true
if the QBluetoothLocalDevice
represents an available local Bluetooth device; otherwise return false.
If the local Bluetooth adapter represented by an instance of this class is removed from the system (e.g. removal of the underlying Bluetooth dongle) then this instance will become invalid. An already invalid QBluetoothLocalDevice
instance remains invalid even if the same Bluetooth adapter is returned to the system.
Note
Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also
- PySide6.QtBluetooth.QBluetoothLocalDevice.name()#
- Return type:
str
Returns the name assgined by the user to this Bluetooth device.
- PySide6.QtBluetooth.QBluetoothLocalDevice.pairingFinished(address, pairing)#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
pairing –
Pairing
Pairing or unpairing has completed with address
. Current pairing status is in pairing
. If the pairing request was not successful, this signal will not be emitted. The errorOccurred()
signal is emitted if the pairing request failed. The signal is only ever emitted for pairing requests which have previously requested by calling requestPairing()
of the current object instance.
- PySide6.QtBluetooth.QBluetoothLocalDevice.pairingStatus(address)#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
- Return type:
Returns the current bluetooth pairing status of address
, if it’s unpaired, paired, or paired and authorized.
- PySide6.QtBluetooth.QBluetoothLocalDevice.powerOn()#
Powers on the device after returning it to the hostMode()
state, if it was powered off.
Note
Due to varying security policies on the supported platforms, this method may have differing behaviors on the various platforms. For example the system may ask the user for confirmation before turning Bluetooth on or off. On macOS it is not possible to power on/off Bluetooth. Please refer to the platform specific Bluetooth documentation for details.
- PySide6.QtBluetooth.QBluetoothLocalDevice.requestPairing(address, pairing)#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
pairing –
Pairing
Set the pairing
status with address
. The results are returned by the signal, pairingFinished()
.
On Android and macOS, AuthorizedPaired
is not possible and will have the same behavior as Paired. On Windows the exact pairing mode decision is up to the operating system.
On macOS, it is not possible to unpair a device. If Unpaired is requested, pairingFinished()
is immediately emitted although the device remains paired. It is possible to request the pairing for a previously unpaired device. In addition AuthorizedPaired
has the same behavior as Paired
.
Caution: creating a pairing may take minutes, and may require the user to acknowledge.
Sets the host mode of this local Bluetooth device to mode
.
Some transitions such as turning the device on or off may take some time. Therefore subsequent calls should only be made once the hostModeStateChanged()
signal has concluded the previous request. If this is ignored the result of such a series of calls is not well defined.
Note
Due to varying security policies on the supported platforms, this method may have differing behaviors on the various platforms. For example the system may ask the user for confirmation before turning Bluetooth on or off and not all host modes may be supported. On macOS, it is not possbile to programmatically change the hostMode()
. A user can only switch Bluetooth on/off in the System Preferences. On Windows this method must be called from the UI thread because it might require user confirmation. Please refer to the platform specific Bluetooth documentation for details.
See also