The BLE APIs and the concept of "handles" ...

User avatar
kolban
Posts: 1683
Joined: Mon Nov 16, 2015 4:43 pm
Location: Texas, USA

The BLE APIs and the concept of "handles" ...

Postby kolban » Fri Dec 30, 2016 5:19 pm

I'm studying the BLE (Bluetooth Low Energy) APIs found in the latest ESP-IDF (as of the date of this post). I am making progress and feel comfortable on GAP and am now able to make GATT searches and query characteristics. This is all good and am trying to write up notes which I'll certainly share when they are in better shape. With this background in place, I have some core questions on the architecture.

I have been reading a number of BLE books including:

Getting Started with Bluetooth Low Energy
Bluetooth Low Energy: The Developer's Handbook

It is pointless (opinion) to start studying the ESP32 APIs on BLE without first knowing the principles of BLE in abstract. Don't start thinking you can correctly use API for programming BLE unless you can describe GAP, GATT, Services, Characteristics, Descriptions, Attributes, UUIDs and assigned numbers (opinion).

While mapping the theory of BLE in the books to practicals of BLE in the API, what I seem to be missing is the notion of "handles". In the BLE story, it seems that a "handle" is the 16bit identifier for an attribute as known to the GATT server. My model says ...

"We scan for a BLE peripheral using GAP. When found, we now know the BT address of the device. Now we form a GATT connection to it. From there we can search for the services it provides. Having found a service of interest, we can then ask that service for its characteristics ...". And right HERE is where I am losing focus ... If I am understanding correctly, a characteristic is identified by a UUID ... perfect ... no issue with that and using the APIs I can see the UUID. However, there is a second aspect ... called a "handle" ... and when we query a GATT server to ask about its characteristics, we not only "should" be getting the characteristics UUIDs but also their handles ... and ( if my study is close ), we then use those handles to read and write the attributes.

For example (and this is made up) ... If I were to run a BLE scan, I might find a response from a device called "FF:FF:45:19:14:80". I then form a GATT connection to this device and then ask about its services. It might then response:
  • UUID: 0x1800
  • UUID: 0x180F
  • UUID: 0x1802
If I then ask about the characteristics of one of the services (say 0x1802), I might get a response of:
  • UUID: 0x2A06
And now I know that the device does what I want and I can start working with this characteristics value ... but ... where are my handles? I had assumed that when querying a characteristic, I would have been also told ... "... and UUID 0x2A06 has a handle of 0x07 on this server".

When I look at the APIs used to manipulate values (esp_ble_gattc_write_char), I see that it takes the connection id to the device (check ... that makes sense), the service uuid and the characteristic uuid ... and no mention of handles. Now ... my *guess* is that internally in the ESP-IDF APIs, the knowledge of handles is being withheld from us and that when we pass in the triple just mentioned, the handles are mapped for us ... however ... that's the area I'd like to hear from others upon ... I feel that ESP-IDF might be helping us here ... but helping us in an opaque manner such that we need some guidance on how to understand the architecture in relationship to BLE study by itself.
Free book on ESP32 available here: https://leanpub.com/kolban-ESP32

WiFive
Posts: 2978
Joined: Tue Dec 01, 2015 7:35 am

Re: The BLE APIs and the concept of "handles" ...

Postby WiFive » Fri Dec 30, 2016 11:59 pm

Found this:
The Android BLE developers chose to use UUID as the characteristic identifier in GATT API's; handles are not directly exposed to applications. Internally, Android maps UUID's to handles and uses handles to access characteristics, but apps have no need to know the handle.

michaelwgnr
Posts: 26
Joined: Wed Dec 21, 2016 3:41 pm

Re: The BLE APIs and the concept of "handles" ...

Postby michaelwgnr » Tue Jan 03, 2017 10:18 am

kolban wrote:When I look at the APIs used to manipulate values (esp_ble_gattc_write_char), I see that it takes the connection id to the device (check ... that makes sense), the service uuid and the characteristic uuid ... and no mention of handles. Now ... my *guess* is that internally in the ESP-IDF APIs, the knowledge of handles is being withheld from us and that when we pass in the triple just mentioned, the handles are mapped for us ... however ... that's the area I'd like to hear from others upon ... I feel that ESP-IDF might be helping us here ... but helping us in an opaque manner such that we need some guidance on how to understand the architecture in relationship to BLE study by itself.
I did not look thoroughly at the GATT client API so far, but the omission of handles and the need to always use the full UUID to write to a characteristic seems odd, indeed, especially considering that a regular proprietary UUID will be 128 bits long. That said, unless you are debugging on the lower protocol layers (e.g. with a BLE protocol sniffer) you don't strictly need to know the actual handles used within the stack and most importantly, the stack should take care of assigning the handles. The only crucial information you need to identify characetistics is the UUID.

On the GATT server side, the ESP API actually provides the attribute handle. If, for example, a smart device acting as a GAP central is connected to your ESP32-based GAP peripheral and writes a certain characteristic, you will receive ESP_GATTS_WRITE_EVT with the parameters as defined in esp_gatts_api.h:

Code: Select all

    /**
     * @brief ESP_GATTS_WRITE_EVT
     */
    struct gatts_write_evt_param {
        uint16_t conn_id;				/*!< Connection id */
        uint32_t trans_id;				/*!< Transfer id */
        esp_bd_addr_t bda;				/*!< The bluetooth device address which been written */
        uint16_t handle;				/*!< The attribute handle */
        uint16_t offset;				/*!< Offset of the value, if the value is too long */
        bool need_rsp;					/*!< The write operation need to do response */
        bool is_prep;					/*!< This write operation is prepare write */
        uint16_t len;					/*!< The write attribute value length */
        uint8_t *value;					/*!< The write attribute value */
    } write;							/*!< Gatt server callback param of ESP_GATTS_WRITE_EVT */
As you can see in the above struct, you get the attribute handle, so you can identify the attribute that has been written.

ESP_Tianhao
Posts: 28
Joined: Thu Jan 05, 2017 10:46 am

Re: The BLE APIs and the concept of "handles" ...

Postby ESP_Tianhao » Fri Jan 06, 2017 6:37 am

Hi,
The "handle" means 'attribute handle", the bluetooth CORE spec define the name. So it's a professional name.
"attribute handle " is a uniq number, it is used for indicating different attribute(service, characteristic, descriptor),because that , for example, two service use the same UUID simultaneously can be allowed, so you cannot use UUID simply to indicate different service with the same UUID. :)

michaelwgnr
Posts: 26
Joined: Wed Dec 21, 2016 3:41 pm

Re: The BLE APIs and the concept of "handles" ...

Postby michaelwgnr » Fri Jan 06, 2017 8:21 am

ESP_Tianhao wrote:The "handle" means 'attribute handle", the bluetooth CORE spec define the name. So it's a professional name.
"attribute handle " is a uniq number, it is used for indicating different attribute(service, characteristic, descriptor),because that , for example, two service use the same UUID simultaneously can be allowed, so you cannot use UUID simply to indicate different service with the same UUID. :)
Yes, I understand that - and from my reading of his post - I think kolban does as well. Maybe I was a bit imprecise with my statement, that from a "user" perspective, the UUID is enough to identify a characteristic. Of course that is only true if you also have a corresponding connection handle. But in most use cases I assume knowing the attribute handle is not relevant.

The main question is, if I understand kolban correctly: why are there no attribute handles returned in the GATT client API?.

My assumption was: because it's not really needed for the BLE application developer.

ESP_Tianhao
Posts: 28
Joined: Thu Jan 05, 2017 10:46 am

Re: The BLE APIs and the concept of "handles" ...

Postby ESP_Tianhao » Mon Jan 09, 2017 5:58 am

michaelwgnr wrote:
ESP_Tianhao wrote:The "handle" means 'attribute handle", the bluetooth CORE spec define the name. So it's a professional name.
"attribute handle " is a uniq number, it is used for indicating different attribute(service, characteristic, descriptor),because that , for example, two service use the same UUID simultaneously can be allowed, so you cannot use UUID simply to indicate different service with the same UUID. :)
Yes, I understand that - and from my reading of his post - I think kolban does as well. Maybe I was a bit imprecise with my statement, that from a "user" perspective, the UUID is enough to identify a characteristic. Of course that is only true if you also have a corresponding connection handle. But in most use cases I assume knowing the attribute handle is not relevant.

The main question is, if I understand kolban correctly: why are there no attribute handles returned in the GATT client API?.

My assumption was: because it's not really needed for the BLE application developer.
Gatt client use "UUID + inst_id" to realize different attribute(corresponding to handle). Bluedroid do that. Maybe, in future, we will modify or add API to use "handle".

Ernesto
Posts: 4
Joined: Sat Dec 23, 2017 3:48 am

Re: The BLE APIs and the concept of "handles" ...

Postby Ernesto » Sat Dec 23, 2017 3:56 am

ESP_Tianhao wrote: Gatt client use "UUID + inst_id" to realize different attribute(corresponding to handle). Bluedroid do that. Maybe, in future, we will modify or add API to use "handle".
Even though it feels a bit like thread necromancy, but I stumbled across this discussion because I am wondering the very same as the OP.

I have a BLE device that requires authentication. With bluez gatttool, I do a

Code: Select all

char-write-req <handle> <pin>
and are authenticated.

How could the same be done here? What is ment with <inst_id> in the above example?

User avatar
kolban
Posts: 1683
Joined: Mon Nov 16, 2015 4:43 pm
Location: Texas, USA

Re: The BLE APIs and the concept of "handles" ...

Postby kolban » Sun Dec 24, 2017 6:08 am

Since this original post, it appears that handles are now indeed exposed by the APIs. If one is a client, one can find the handle of a service, characteristic or descriptor and if one is a server, one can be told of ones own handle.
Free book on ESP32 available here: https://leanpub.com/kolban-ESP32

Ernesto
Posts: 4
Joined: Sat Dec 23, 2017 3:48 am

Re: The BLE APIs and the concept of "handles" ...

Postby Ernesto » Fri Dec 29, 2017 7:54 am

kolban wrote:Since this original post, it appears that handles are now indeed exposed by the APIs. If one is a client, one can find the handle of a service, characteristic or descriptor and if one is a server, one can be told of ones own handle.
Hi Neil,

thanks for your reply!

Does anyone have an example how that would work now, just using handles?
By looking at the Espressif examples and the API I couldn't figure out how. :(

User avatar
kolban
Posts: 1683
Joined: Mon Nov 16, 2015 4:43 pm
Location: Texas, USA

Re: The BLE APIs and the concept of "handles" ...

Postby kolban » Sat Dec 30, 2017 5:44 am

In my travels, I wanted to create a C++ framework for working with BLE and created the library that can be found here:

https://github.com/nkolban/esp32-snippe ... /cpp_utils

My goal is not to have you use that library but instead maybe skim it for API usage. I made extensive use of handles within. For specific questions, I'll be more than willing to dig in with you but I haven't committed all the nuances to memory. What I'd suggest you do is start small and get the bare minimum working and then build from there. First decide if you are building a BLE client or a BLE server and start incrementally building up from that. As puzzles start appearing, document them well and post them to this forum. I for one will try and jump in if I can offer any knowledge. Realize that BLE is a big beastie with a lot of parts. You may up benefiting from a BLE framework of some sort to make the job easier so you can focus on just your logic steps.
Free book on ESP32 available here: https://leanpub.com/kolban-ESP32

Who is online

Users browsing this forum: No registered users and 43 guests