[TW#15769] Better docs needed for esp_ble_gatts_create_service -> num_handle

[nkolban]

There is a new signature on the exposed API called esp_ble_gatts_create_service. It has a new parameter called num_handle which only has the documentation:

---

num_handle: number of handle requested for this service

---

I'd like to humbly request that the documentation for this be improved upon. My guess is that this parameter represents the number of handles to be allocated to the service. Reading the current statement, one might assume that this is the "number OF the handle" to be used as the start of handles. That might just be a simple grammar error.

However, when attempting to contemplate this function, the reader will now be puzzled by the notion. Among his questions will be:

• What is a handle?
• How many handles do I need to allocate?
• What metric/algorithm should I use to choose the value?
• What errors will be produced that would indicate that I have allocated too few?
• What is the impact if I make this number too large?
• How much "resource" is allocated when I allocate a handle?

[Yulong-espressif]

@nkolban What is a handle? --> An attribute handle is a 16-bit value that is assigned by each server to its own attributes to allow a client to reference those attributes. An attribute handle shall not be reused while an ATT Bearer exists between a client and its server.
Attribute handles on any given server shall have unique, non-zero values. Attributes are ordered by attribute handle.
An attribute handle of value 0x0000 is reserved, and shall not be used. An attribute handle of value 0xFFFF is know as the maximum attribute handle.
Note: Attributes can be added or removed while an ATT Bearer is active, however, an attribute that has been removed cannot be replaced by another attribute with the same handle while an ATT Bearer is active. You can find this explain in the Bluethooth Spec 4.2 Part F 3.2.2
How many handles do I need to allocate? --> We already know that each attribute corresponds to a handle, so how many attributes are required in a service? For example, there are three characteristic in a service, where the first characteristic has two descriptors, and the second characteristic has only one descriptor, and the third characteristic has no descriptor. Then the number of handles needed should be 1 (svc attr) + 4 (1 char declaration attr, 1 char value attr, 2 descriptors attr) + 3 (1 char declaration attr, 1 char value attr, 1 Descriptor attr) + 2 (1 char declaration attr, 1 char value attr) = 10, that is, to create such a service requires 10 handle.
What metric/algorithm should I use to choose the value? --> I don't understand it, can you explain please. What does the value here mean?
What errors will be produced that would indicate that I have allocated too few? --> If the handle too few, when you added the characteristic or descriptor which exceed the number of the handle, then the BT stack will print the error log "handle space full. handle_max = %d next_handle = %d\n", and return nothing.
What is the impact if I make this number too large? --> too large it is doesn't matter, but you have to make sure you have enough memory.
How much "resource" is allocated when I allocate a handle? --> This is very uncertain, this mainly depends on whether you set up ESP_GATT_RSP_BY_APP or ESP_GATT_AUTO_RSP. If ESP_GATT_RSP_BY_APP, then each attribute occupies the memory is almost the same for the 2 bytes uuid attribute occupies about 24 ~ 28bytes, for the 16-byte uuid attribute occupies about 40 ~ 44bytes.
If it is ESP_GATT_AUTO_RSP, mainly to see the characteristic of the value set the value.

[nkolban]

This is pure gold and MANY thanks for taking the time to write it up. I'm thinking that folks may not find this information easily. Would it be possible to write up this information in the documentation somewhere in here:

http://esp-idf.readthedocs.io/en/latest/

Again ... many thanks.