client.write_gatt_char() not exposing GATT error code to user

[Matt-Hicks-Bose]

• bleak version: 0.6.1
• Python version: 3.7.6
• Operating System: Windows 10.0.18363
• BlueZ version (bluetoothctl -v) in case of Linux: N/A

Description

I am working with a BLE device that will return an application specific ATT error response (between 0x80 - 0x9F, as required by the Bluetooth specification) when a characteristic is written with invalid data. I am writing to this characteristic with client.write_gatt_char() and specifying response=True. However, when I run this code with intentionally invalid data, I am getting a BleakError without the ATT error response, because of this I cannot handle the error in my own code correctly.

What I Did

import asyncio
import bleak

DEVICE_MAC = '<my device mac address>' # Change this to your MAC address
CONFIG_UUID = '<my characteristic UUID>' # Change this to your characteristic UUID

async def run():
    # Connect to client and wait for connection to complete
    client = bleak.BleakClient(DEVICE_MAC, timeout=10)
    await client.connect()

    # Characteristic before it is set
    print(f'Before: {await client.read_gatt_char(CONFIG_UUID)}')

    # Set a good config
    good_data = b'\x00\x11\x40' # good config
    await client.write_gatt_char(CONFIG_UUID, good_data, True)

    # Characteristic after it is set
    print(f'After good: {await client.read_gatt_char(CONFIG_UUID)}')

    # Set to a known bad config
    bad_data = b'\x90\x11\x40' # intentionally bad config
    await client.write_gatt_char(CONFIG_UUID, bad_data, True)

    # This will never run due to error
    print(f'After bad: {await client.read_gatt_char(CONFIG_UUID)}')

if __name__ == "__main__":
    # Run the program
    loop = asyncio.get_event_loop()
    loop.run_until_complete(run())  

When I run this my output looks like:

Before: bytearray(b'\x00\x00\x00')
After good: bytearray(b'\x00\x11@')
<traceback snipped>
bleak.exc.BleakError: Could not write value b'\x90\x11@' to characteristic <my characteristic UUID>: 2

It is expected that an ATT error response would be returned or raised, but the python error raised does not indicate what the ATT error response was.

Further investigation

I looked through the .NET documentation that was mentioned in #59 ( https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.genericattributeprofile.gattwriteresult ), and it looks like the ATT error response is contained in the ProtocolError property of the gattwriteresult object. On my local copy of the library I changed the BleakError raised in write_gatt_char(), part of the dotNET backend from:

raise BleakError(
    "Could not write value {0} to characteristic {1}: {2}".format(
        data, characteristic.uuid, write_result.Status
    )
)

To:

raise BleakError(
    "Could not write value {0} to characteristic {1}    Status: {2}    ProtocolError: 0x{3:02X}".format(
        data, characteristic.uuid, write_result.Status, write_result.ProtocolError
    )
)

This now results in an error that shows the expected ATT error response 0x90 which in this application means "invalid configuration requested":

bleak.exc.BleakError: Could not write value b'\x90\x01@' to characteristic <my characteristic UUID>    Status: 2    ProtocolError: 0x90

Is it possible to expose this ATT Error Response to the user of the library? Either through a seperate error message that could be caught and handled, a return value, or some other mechanism?

[hbldh]

It will not be done in the foreseeable future I am afraid. I am swamped with other (paid) work and cannot guarantee doing anything with this project for quite some time. I will still address PRs to develop branch occasionally, so if you desire these changes you have to do the legwork yourselves.

[hbldh]

This is a very good suggestion. Implemented a version of this (2cf7b8b) on the develop branch. It will be included in version 0.7.0 of bleak. Thank you!

[Matt-Hicks-Bose]

Excellent! Will this be implemented in the two other backends as well?

[hbldh]

Right now, no. I am not sure where to fetch that information in BlueZ nor in Core Bluetooth. Bleak is very much a “each one to one’s own” in the sense that if you ask for it and do most of the actual detective work of the development, I will probably integrate it. If someone needs it, they are free to go look for it and I will eventually try to merge their OR or in this case request.

On that note, please try out the dev branch and see if you can reproduce the errors and verify the solution!

[hbldh]

@Matt-Hicks-Bose These error codes, where did you find specifications of them? Another user got a 0x0ferror code in #249 and I cannot find any reference to them...

[Matt-Hicks-Bose]

The error codes used by GATT are defined in the Bluetooth Core Specification (Version 5.2, Vol 3, Part H, Section 3.4.1.1, Table 3.4 (pp. 1491)), which is available to download here: https://www.bluetooth.com/specifications/bluetooth-core-specification/

I will add a comment to the other issue with more details about the error code.

[hbldh]

@Matt-Hicks-Bose Thank you! I will try to include those error codes in bleak for future use.

[hbldh]

Added text strings of these errors codes in 37597b3 and showing these when raising Protocol Errors. Thank you @Matt-Hicks-Bose; it will be included in version 0.8.0, after which I will close this issue and open two new ones for BlueZ and Core Bluetooth backends. It would be nice to provide the same details there, but I am not sure it is possible.

[hbldh]

Will close for now. I have had no success finding GATT error codes in BlueZ or Core Bluetooth.