Migration guide

There are only some small breaking changes, so hopefully most users can upgrade without any changes.

The exception is if your project is handling OS-specific exceptions on the GATT read and write methods. These exceptions are now wrapped in BleakGATTProtocolError to have a consistent cross-platform exception. If you need to support multiple versions of Bleak, you can catch both exceptions.

For example, if you caught BleakDBusError and parsed the string to get the GATT error, you can now catch BleakGATTProtocolError instead and it has a code property to get the actual error code.

Another change of note is the deprecation of the adapter keyword argument. We know there are lots of users of this, so we intend to have a long deprecation cycle for this (several years). If you need to support multiple versions of Bleak, you can pass both the old kwarg adapter="hci0" and the new bluez={"adapter": "hci0"} and optionally suppress the deprecation warning. Otherwise, you can just replace the old arg with the new arg as seen in the previous example.

Changelog

Added

• Added adapter attribute to bleak.args.bluez.BlueZClientArgs and bleak.args.bluez.BlueZScannerArgs.
• Added bluez keyword argument to BleakClient.
• Added new bleak.args.bluez.BlueZClientArgs class.
• Added bleak.exc.BleakGATTProtocolError and bleak.exc.BleakGATTProtocolErrorCode classes.
• Added type hints and documentation for use_cached kwarg for read_gatt_char() and read_gatt_descriptor() methods in BleakClient.
• Added support for "use_cached" kwarg to read_gatt_char() and read_gatt_descriptor() methods in BlueZ backend.

Changed

• Deprecated adapter keyword argument in BleakScanner and BleakClient.
• Changed GATT read and write methods to raise BleakGATTProtocolError when a GATT protocol error occurs.
• Changed start/stop scanning on CoreBluetooth so that the isScanning property is not checked anymore.
• Changed BleakClient.write_gatt_descriptor() to raise ValueError when attempting to write to the descriptor 0x2902 (Client Characteristic Configuration Descriptor, CCCD). Use start_notify() and stop_notify() instead.

Fixed

• Fixed occasional EOFError when disconnecting in BlueZ backend. Fixes #1921.
• Fixed a potential deadlock when turning off Bluetooth manually while starting scanning on CoreBluetooth.
• Fixed reading descriptors 0x2900, 0x2902 and 0x2903 on CoreBluetooth backend.
• Fixed cyclic references problem in CoreBluetooth backend causing memory leaks.
• Fixed typehint for BleakScanner.__aexit__().

Removed

• Removed undocumented/deprecated device keyword argument from BleakScannerBlueZDBus and BleakClientBlueZDBus.