search

ARMmbed / mbed-os-example-ble

BLE demos using mbed OS and mbed cli
Apache License 2.0
134 stars 117 forks source link

Lack of usable BLE documentation #355

Open idea--list opened 3 years ago

idea--list commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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- commented 3 years ago

Hi @idea--list ,

Your describing two different problems in this topic:

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

idea--list commented 3 years ago

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: image

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: image 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: image 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 commented 3 years ago

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

idea--list commented 3 years ago

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 commented 3 years ago

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

ciarmcom commented 3 years ago

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

ciarmcom commented 3 years ago

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

0xc0170 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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- commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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.