BLE documentation, especially Peripheral/Server use cases

[mphasize]

Please add more documentation on using Bluetooth / BLE

Is your feature request related to a problem? Please describe.

At the moment the Pycom documentation for the BLE implementation only describes how to use a Pycom board as a BLE client that connects to BLE peripherals. The documentation on how to use the board as a BLE peripheral (i.e. a BLE server) is almost completely missing at this point, however the Pycom forums have various user-contributed code sketches that show that it is at least partially possible.

Describe the solution you'd like

Add an example or tutorial and corresponding API documentation that shows how to use the Pycom boards as BLE peripherals (i.e. BLE server).

Topics to cover would be:

• How to create a service and characteristics and advertise it (see thread here: https://forum.pycom.io/topic/1500/support-for-bluetooth-le-notifications)
• How to handle READ, WRITE, NOTIFY and INDICATE operations on the published characteristic
• How to work with UUIDs (see thread here: https://forum.pycom.io/topic/530/working-with-uuid)

Teachability, Documentation, Adoption, Migration Strategy

Having canonical docs or tutorials would help developers to quickly understand the full capabilities of the ESP32 and BLE and would also help Pycom to get a better picture on the implementation status of the APIs and would make it easier to find and iron out bugs that might still be in the library.
A good set of usable code examples would be great, as an inspiration I would like to mention https://github.com/espressif/arduino-esp32/tree/master/libraries/BLE/examples

[catalinio]

hi @mphasize,

Thanks for your comments. Here are examples of BLE GATT both Server and Client: https://docs.pycom.io/firmwareapi/pycom/network/bluetooth/gattscharacteristic.html I think the READ/WRITE and Notify are being handled there. Also the forum posts are quite old, BLE is constantly improved, given our customers feedback. In principle the BLE features are described in ESP32-IDF documentation here: https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/bluetooth/bt_le.html and it can be quickly exposed in micropython if required. All our firmware/software and documentation is open-source and we are more than happy to accept pull-requests.

[mphasize]

Hi @catalinio,

thanks for the pointers! With the example from GATTSCharacteristic I finally managed to get something to work and I also finally understood that I will not find Python code for the Bluetooth library, but rather will have to look at the C code for the underlying functions.

I will put some notes here with the things I had trouble understanding – maybe they can help someone or inform the next iteration of docs/tutorials.

• Finding the example of how to set up a BLE server was difficult. When you browse the docs, a "Quick Usage Example" is often at the top, but the example for GATTSCharacteristic was "below the fold", so I missed it although I was looking for it.
• I knew that a service can have multiple characteristics from previous BLE projects, so I tried adding more characteristics for my service and that failed without an error message. Everything seemed to work, but I was not able to browse services and characteristics from the client. It took me a long while to figure out the meaning and importance of the nbr_chars=1 parameter of the Bluetooth.service() function, partially also because it's never used in the examples.
• UUIDv4 format is usually written out with dashes and naively using ubinascii.unhexlify() and simply leaving out the dashes does not work because for some obscure reason the byte order is reversed. This should be mentioned in the docs or the helper function linked to above could become part of the class.
• In my previous BLE project, setting a new value on a characteristic and notifying the client of the new value were two distinct operations, so I was searching for the "notify" function. The implicit notification is not mentioned in the docs and I'm not sure if it's always necessary to force the notification on every update. I believe it would be good if the developer can opt-out of notifications or trigger them separately.

Cheers Marcus