API Documentation

[frax84]

Hello,
i'm following with interest the development of ESP32 IDF. I'm having hard time with the documentation (http://esp-idf.readthedocs.io/en/latest/?badge=latest). It's not impossible to use, just it's not really intuitive. I would like to know if there is any schedule for improved documentation.

Thanks,
Frax

[ESP_Sprite]

Hmm, 'non-intuitive' isn't entirely criticism we can immediately do something with... What would you like to see improved exactly?

[frax84]

Eheh! It's absolutely not criticism, it's more likely i'm just a newbie :\
I'm mostly interested in BT-BLE part. Actually it seems some description of the typedef/struct/commands are missing. Probably they go as granted and i'm just lacking something. I think it would be really useful adding more "operative" example, i.e. "How to create a service with 1 characteristic", "How to use advanced settings in service", "How to set permissions", etc.
I want to underline that it's not that i can't use what is available, it just would speed up the learning curve imho

Considering i'm already here i have another question. In this snippet of code of gatt example:

Code: Select all

static uint8_t test_service_uuid128[32] = {
    /* LSB <--------------------------------------------------------------------------------> MSB */
    //first uuid, 16bit, [12],[13] is the value
    0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00, 0xAB, 0xCD, 0x00, 0x00,
    //second uuid, 32bit, [12], [13], [14], [15] is the value
    0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00, 0xAB, 0xCD, 0xAB, 0xCD,
};

test_service_uuid128 is an array of 32 bytes --> 256bit but as for BT specs uuid for custom service is 128bit.
"first uuid, 16bit, [12],[13] is the value" --> what this mean? (same for bottom).

Thank you for your patience
Frax

[kolban]

Mr Frax,
It may be that this freely downloadable book of notes might be of some use to you ... please read the description of intent found there ...

http://esp32.com/viewtopic.php?f=2&t=390&p=2522

Neil

[ESP_Sprite]

Ah, I can imagine the BLE part is a bit lacking; it's a big thing to document and still a work in progress. I most certainly expect the usability to get better; as far as I understand it, at the moment you're basically down to manually shoving bytes into the HCI, which isn't the most user-friendly way imaginable.

[frax84]

@kolban:
Thank you Dr. Kolban for the interesting link. I'm following silently the (extremely useful) development of your book. Actually i still miss the updated version and i will gladly proceed to download

@ESP_Sprite:
Yes, i know it's a work in progress and i even know that it's not an high-priority update right now. That's why i was asking for any schedule for improved documentation
To be exact i'm actually at the point where i'm "breaking" your gatt_example in a set of sub-code easier to understand. The main problem is that i'm jumping from a documentation page to another, not always exhaustive, and often losing the general concept.

By the way, you answered to the original question and kolban gave me a good hint to proceed. That's enough for now

Thank you,
Frax