Lack of usable BLE documentation

[idea--list]

Description of defect

All the pages & repos that are intended to explain how to program BLE functionalities are full of non-sense bloat and are cross-linking to eachother without actually onboarding Mbed users how to use BLE.

Target(s) affected by this defect ?

all

Toolchain(s) (name and version) displaying this defect ?

all

What version of Mbed-os are you using (tag or sha) ?

6.8.0

What version(s) of tools are you using. List all that apply (E.g. mbed-cli)

Not relevant

How is this defect reproduced ?

Read through all the BLE relevant pages of the official Mbed site, check out this repo, forget anything that BLE engineers already know and face the reality: there is no useful info through all those pages. And guess what: even the recent examples will not compile as those depend on pretty printer. Even if that is not mentioned anywhere. Got a feeling as the whole BLE stack was not an organic part of Mbed OS just someone would have hacked that into the project and even then was it meant to function with mbed CLI only.

[ciarmcom]

@idea--list thank you for raising this issue.Please take a look at the following comments:

What target(s) are you using?
What toolchain(s) are you using?
It would help if you could also specify the versions of any tools you are using?

NOTE: If there are fields which are not applicable then please just add 'n/a' or 'None'. This indicates to us that at least all the fields have been considered.
Please update the issue header with the missing information, the issue will not be mirrored to our internal defect tracking system or investigated until this has been fully resolved.

[paul-szczepanek-arm]

Thank you for your feedback. I'll try to get some work scheduled to improve the docs.

As for the example, they compile and run fine. The pretty printer you mention is part of the utils and is checked out automatically when you mbed deploy. The other github issue page in which you posted your comments was due to the fact that the user had previously checked out an older version of the examples which did not have the library, then updated the examples but forgot to run mbed deploy. Please clone the repo and see for yourself that the example compiles and runs fine.

The BLE feature is officially supported and developed by us, the Mbed team with contributions from our partners and the community.

[idea--list]

As for the example, they compile and run fine.

No, they do not. As i mentioned i am using Mbed Studio v1.3.1 until now i could not figure out how to use CLI commands like mbed deploy within that. What i did: copied the contents of main.cpp of BLE_Advertising example into a new file. Then i copy&pasted the content of pretty_printer.h found in mbed-os-ble-utils repo into another new file. Now the code compiles, but does not seem to run on my Artemis Thing Plus board, which has an on-chip BLE module and targets.json already sets BLE and Cordio for this board.

My other board is a MAX32630FTHR with a dual-mode BT chip on it, but mbed does not support BLE on this board anymore.

Meanwhile i checked out the BLE documentation of Arduino. Never thought i will ever have any interest in Arduino. Despite their BLE doc is much shorter, it does not contain any bloat and also one can understand and get started based on the doc, meaning the doc fulfills it's purpose. I also began this course also that explains everything about BLE so that one can understand and since that i can tell you Mbed's BT tutorial is even worse i thought 2 days ago. I think the documentation should be redone from scratch as adding some useful content to that amount of useless bloat does not make much sense.

[pan-]

Hi @idea--list ,

Your describing two different problems in this topic:

• BLE documentation being inadequate: We welcome feedback from our users . Please raise them in the documentation repository: https://github.com/ARMmbed/mbed-os-5-docs/issues . Explain what you think can be improved and more importantly how would help us deciding if it is something we should prioritize or not. Saying it is full of useless bloat without describing what such bloat is does not help.
• Examples from this repository not compiling with Mbed studio: Mbed studio does not support repositories that contains multiple projects out of the box.
  1. Clone this repository with git to your machine. The import program function from Mbed studio does not work with multiprojects root.
  2. Open the desired application (for example BLE_GAP) with File > Open workspace
  3. Deploy the missing libraries by going into the Libraries tab and click on the exclamation mark button at the top of the tab then click Fix all. This should deploy the libraries.
  4. Enjoy Mbed studio.

@paul-szczepanek-arm I think it would be worthwhile to add a note about this process in the documentation.

[idea--list]

Hi @pan-
Might be a long post even if i try to keep all this in a nutshell. This why the current documentation is full of bloat:
Take this page:

Both links i marked with red are linking to the very same index page but have different URL. If you scroll just a bit downwards, below the "Getting started" header you will find a hyperlink to this page. Also this page begins reexplaining that BLE is a wireless technology, etc.
Well everyone knows that, and i already could find this really useless information on the previous page...
And by the way we navigated from the page reached from Main menu->documentation->Mbed Cordio to a page referred as "Mbed OS Bluetooth documentation". By now maybe even most of search engines got confused from hopping from "documentation" to "documentation" of the same thing.

Right after that you will find this completely irrelevant sketch:

And the page continues with completely useless stuff:

Arm Mbed BLE, also called BLE_API, is the Bluetooth Low Energy software solution for Mbed. Many targets support Mbed BLE. Developers can use it to create new BLE applications.

Oh, really? This is the third time i get this same info in the last 20 seconds...but for sure it must then be really important to understand otherwise we just could not begin using the API.

Anyway by now i know it for sure that BLE has something to do with data. And reading further i get to know that i even could display the data (apparently even with devices/modules that do not have a display). Then i also understand "Displaying information" must be a really important buzzword in Mbed, at least it is repeated almost immediatly after the subheading with the same words. From the very next sentence i find out the data buzzword could mean "sensor input" (well...until now i thought sensors provide output and do not take input, but reading Mbed documentation is golden!)

The next section then tells me i could even process that data... Holy cow! Now i am blown away by this BLE thing... however i still can not do anything with or how to start as the doc is just plain bloat like the rest of this page is.

But let us at last get to the BLE API reference page, which begins with:

With other words: we know the doc is outdated as we changed a bunch of things but we do not care, take it as it is. Neat doc, right?
Then it makes me remember that this BLE thing is still a low power wireless technology! At least that has not changed since i began trying to figure out how to program BLE features with Mbed 3 links ago...

We go on by:

Arm Mbed BLE, also called BLE_API, is the Bluetooth Low Energy software solution for Mbed.

Oh my, i almost though it was meant for the Windows OS.

Please let me not to continue, but by now i hope you get the point what is wrong with the documentation.

[ciarmcom]

@idea--list it has been 5 days since the last reminder. Could you please update the issue header as previously requested?

[idea--list]

Take a look at this and this website as examples of good onboarding with BLE.
While they do not tell how to program with Cordio stack, they explain how BLE works, this is also something Mbed's doc utterly fails.

[ciarmcom]

@idea--list it has been 5 days since the last reminder. Could you please update the issue header as previously requested?

[ciarmcom]

@idea--list it has been 5 days since the last reminder. Could you please update the issue header as previously requested?

[ciarmcom]

@idea--list it has been 5 days since the last reminder. Could you please update the issue header as previously requested?

[0xc0170]

@idea--list it has been 5 days since the last reminder. Could you please update the issue header as previously requested?

I've fixed the template as it was quick.

[ciarmcom]

Thank you for raising this detailed GitHub issue. I am now notifying our internal issue triagers.
Internal Jira reference: https://jira.arm.com/browse/IOTOSM-3549

[Arjun765]

As for the example, they compile and run fine

They do not compile on GCC 9.3.1. I tried using the online compiler with the periodic advertisement example, while it compiles i can't get the Bluetooth to work properly (on a ST WB55).

[boraozgen]

Same story for the Cordio docs

How much of this information is up-to-date? AFAI understand the structure has changed quite a bit. Many of the folders depicted here do not exist anymore. I could not find a single piece of documentation on how the Cordio stack and the BLE API relate to each other.

[pan-]

@boraozgen Removing the cordio documentation from Mbed OS docs is something we track. Most of the information present remains valid but not everything is up to date like folder organization.

[idea--list]

Yesterday i stumbled across this one: BLEIntros.
If i get it right, it was meant to document BLE in Mbed OS 3, which has been abandonned...and thus the content is not always valid in terms of Mbed OS 6.x versions.
But hey this is how a proper documentation reads like. It briefly introduces to the technology, explains things in a way one can truly understand and also answers common questions. Has also a section about limitations on IOS/Android, etc.

I know BLE is being worked on which can explain the state of the current doc, but once implementation settles i wish the documentation should be updated like this one.

[0xc0170]

Yesterday i stumbled across this one: BLEIntros.

I'll look at this repository, to add details and archive it. It should not cause the confusion.

Thanks for the feedback, we will review BLEIntros.