That's the really basic github page that presents a very high level briefing, mostly on how to build the library. I'm referring to User Guide, or How To Use documentation. For example:
1) The only way to find out about advertising devices is to ask the BluetoothManager for a list of the devices it knows about. These could be devices that are advertising now, or could be devices that the BM once knew about. I don't care about what the BM once knew about - I want to know what's advertising right now! Is there any way to control this? And why can't I just subscribe to the BM for asynchronous advertisement notification? That's how iOS CoreBluetooth works, and my expectations are based on that.
2) TinyB doesn't provide the means for a client app to register for advertisements, as the means to device discovery. Instead the app must obtain the list (see #1 above) and then subscribe on each object for asynchronous notification of new advertisements.
3) I'm getting weird exceptions reporting "Software caused connection abort" (reported in a separate issue), and it would be nice to have some idea of what the software is doing that causes this exception. JavaDoc style reference documentation doesn't even begin to help with that.
4) I've found that I need to put small delays in my code in a few places, to give TinyB time to complete whatever it is doing, and if I don't perform those waits then TinyB will crash.
Most if not all of these may be caused by my app, and it could be that I'm doing something I shouldn't, or not doing something I should. How would I know? Some best practices documentation would help.
I guess I don't know how else to ask this. What I'm asking for is a usage guide, not a minimalist sample. Something that's designed to guide a developer to make the best use of the API, and not make stupid usage errors. Sample code is great, but the HelloTinyB sample is minimal, with no explanation for things.
For example, line 71 in HelloTinyB.java (and other locations) - why wait 4 seconds? Is that a requirement? Is the app waiting for TinyB to catch up to something? Is it important to not make any other TinyB calls for 4 seconds?
Why does the call to manager.getDevices() return BluetoothDevices that aren't advertising right now? How do I filter out the ones that aren't really there? How do I tell the BluetoothManager to only return devices that are actually advertising?
Why does the call to BluetoothDevice.getServices() often hang? What am I doing wrong, to cause this behavior?
Why does the documentation page provide example code that is tied to version 0.3, when 0.5 is out and includes a much more coherent implementation (somewhat asynchronous versus limited to polling only).
Thanks. It's unexplained behaviors and extremely limited documentation that makes developers move on and look for a better alternative. I'm having trouble with TinyB hangs and crashes, and need to know ASAP if this is due to my usage, or if these issues are inherent in TinyB (or BlueZ). If the former, with some guidance, maybe I can get around the issues. If it's the latter I need to move on right now. That's why I'm asking for more than I've found so far.