Android onboarding & basic usage documentation #339

tombertoli · 2024-09-11T14:28:21Z

This includes a simple setup guide and basic usage for both SimpleDroidBLE and the simpleble C++ interface on Android (using simpleble-bridge).

tombertoli · 2024-09-11T14:28:41Z

Lmk if you think anything is missing :)

kdewald · 2024-09-12T22:03:21Z

docs/simpledroidble/usage.rst

+Building from source
+--------------------
+
+1. Clone `the repo <https://github.com/OpenBluetoothToolbox/SimpleBLE>`_.


No need to clarify this. Also use proper language.

kdewald · 2024-09-12T22:04:20Z

docs/simpledroidble/usage.rst

+
+2. Build the libraries using gradle (``./simpledroidble/gradlew assembleRelease``) or Android Studio. The following libraries will be built:
+    - ``simpledroidble/simpledroidble/build/outputs/aar/simpledroidble-release.aar`` 
+    - ``simpleble/src/backends/android/simpleble-bridge/build/outputs/aar/simpleble-bridge-release.aar``


I would move the simpleble-bridge documentation to the simpleble/usage.rst page, as it would be specific for that kind of implementation.

Isn't simpleble-bridge.aar required to use simpledroidble? If so, from the POV of the Android programmer, this should just be another requirement imo (i.e.: "You need both these AARs to use simpledroidble").

kdewald · 2024-09-12T22:04:48Z

docs/simpledroidble/usage.rst

+      implementation(files('libs/simpledroidble.aar', 'libs/simpleble-bridge.aar'))
+    }
+
+3. You're ready to start using SimpleBLE on Android! Go to `Using SimpleDroidBLE`_ to continue with the onboarding.


Please use the same tone as the other documentation pages.

kdewald · 2024-09-12T22:05:24Z

docs/simpledroidble/usage.rst

+
+1. Place the package on your app's directory, and take note of its path. We'll use ``example-app/app/libs/{simpledroidble,simpleble-bridge}.aar``.
+
+2. Declare the dependency on your app's ``build.gradle{.kts}`` file (note: relative paths begin from your app's module folder)::


I would have a separate copy of this specific for simpleble-bridge inside simpleble/usage.rst

kdewald · 2024-09-12T22:06:28Z

docs/simpledroidble/usage.rst

+====================
+
+First you'll need to provide ``SimpleDroidBLE.contextReference`` with a WeakReference to the app's context. In this step, the native code will be loaded in memory and permissions will be requested to the user.


This needs to be a lot more elaborate. Why is this required? How do you do it? Show a few code examples.

docs/simpledroidble/usage.rst

kdewald · 2024-09-13T04:38:23Z

docs/simpledroidble/usage.rst

+-----------------
+
+The main entry point to SimpleDroidBLE is the Adapter object. You can get an Adapter instance via the static ``Adapter#getAdapters`` method, where the device's main bluetooth adapter will be returned.
+
+When using SimpleDroidBLE make sure to only reference a single instance of the Adapter object, as every instance creates a new internal referece in the native code.
+Having multiple instances (by unbounded calls to ``Adapter#getAdapters``, for example) may cause a memory leak.
+This can be accomplished by acquiring said instance either on your app's Application class, or, in a single activity app, on your Activity's viewmodel; and treating the Adapter as a global, singleton object.
+For an specific example you can check out `the sample app <https://github.com/OpenBluetoothToolbox/SimpleBLE/tree/main/examples/simpleble-android>`_.
+
+Connecting to devices
+---------------------
+
+SimpleDroidBLE is a `flow <https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/>`_-driven interface.
+
+That means that when looking to connect to a device, you should ``collect`` from ``Adapter#onScanFound`` and then start scanning for devices with ``Adapter#scanStart``. You'll get all found ``Peripheral`` s on said flow, where you can ``Peripheral#connect`` to whichever you need.
+


This is good as a very basic approach, but the text needs to go deeper into detail, including examples that should be easy to follow for non-experts.

kdewald · 2024-11-21T06:57:02Z

docs/simpledroidble/usage.rst

+    includeBuild("path/to/simpledroidble") {
+        dependencySubstitution {
+            substitute module("org.simpleble.android:simpledroidble") with project(":simpledroidble")
+        }
+    }


Maintain the use of code blocks with the corresponding language specifier.

kdewald · 2024-11-21T06:57:12Z

docs/simpledroidble/usage.rst

+    includeBuild("path/to/simpledroidble") {
+        dependencySubstitution {
+            substitute(module("org.simpleble.android:simpledroidble")).using(project(":simpledroidble"))
+        }
    }
-}

-```kotlin
-includeBuild("path/to/simpledroidble") {
-    dependencySubstitution {
-        substitute(module("org.simpleble.android:simpledroidble")).using(project(":simpledroidble"))
+Then, inside your ``build.gradle`` or ``build.gradle.kts`` file, you can add the
+following dependency::
+
+    dependencies {
+        implementation "org.simpleble.android:simpledroidble"
    }
-}
-```
-
-Then, inside your `build.gradle` or `build.gradle.kts` file, you can add the
-following dependency:
-
-```groovy
-dependencies {
-    implementation "org.simpleble.android:simpledroidble"
-}
-```
-
-```kotlin
-dependencies {
-    implementation("org.simpleble.android:simpledroidble")
-}
-```
+
+Kotlin::
+
+    dependencies {
+        implementation("org.simpleble.android:simpledroidble")
+    }


Same for all of these

kdewald · 2024-11-21T06:58:07Z

docs/simpledroidble/tutorial.rst

+    import android.util.Log
+    import kotlinx.coroutines.CoroutineScope
+    import kotlinx.coroutines.launch
+    import org.simpleble.android.Adapter
+
+    suspend fun peripheralState() {
+        // Get an adapter
+        val adapter = Adapter.getAdapters().first()
+
+        CoroutineScope(Dispatchers.Main).run {
+            launch {
+                adapter.onScanUpdated.collect { peripheral ->
+                    adapter.scanStop()
+
+                    launch {
+                        peripheral.onConnected.collect {
+                            Log.i("Example", "Successfully connected to ${peripheral.identifier}")
+                        }
+                    }
+
+                    launch {
+                        peripheral.onDisconnected.collect {
+                            Log.i("Example", "Successfully disonnected from ${peripheral.identifier}")
+                        }
+                    }
+
+                    launch {
+                        peripheral.onConnectionActive.collect {
+                            Log.i("Example", "Connection changed to $it for ${peripheral.identifier}")
+                        }
+                    }
+
+                    peripheral.connect()
+                    delay(500)
+                    peripheral.disconnect()
+                }
+            }
+        }
+
+        adapter.scanStart()
+    }


Use code blocks with language descriptors

Followed SimpleBLE tutorial and converted references and examples to idiomatic Kotlin (i.e. using flows)

kdewald reviewed Sep 12, 2024

View reviewed changes

kdewald reviewed Sep 13, 2024

View reviewed changes

docs/simpledroidble/usage.rst Outdated Show resolved Hide resolved

kdewald reviewed Sep 13, 2024

View reviewed changes

kdewald reviewed Nov 21, 2024

View reviewed changes

tombertoli added 3 commits November 21, 2024 18:08

Onboarding documentation for Android use cases

5ebc155

Created Android tutorial

951e4ef

Followed SimpleBLE tutorial and converted references and examples to idiomatic Kotlin (i.e. using flows)

Add code blocks with language descriptors

9287907

tombertoli force-pushed the docs branch from 406537f to 9287907 Compare November 21, 2024 21:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Android onboarding & basic usage documentation #339

Android onboarding & basic usage documentation #339

tombertoli commented Sep 11, 2024

tombertoli commented Sep 11, 2024

kdewald Sep 12, 2024

kdewald Sep 12, 2024

tombertoli Sep 13, 2024

kdewald Sep 12, 2024

kdewald Sep 12, 2024

kdewald Sep 12, 2024

kdewald Sep 13, 2024

kdewald Nov 21, 2024

kdewald Nov 21, 2024

kdewald Nov 21, 2024


		1. Place the package on your app's directory, and take note of its path. We'll use ``example-app/app/libs/{simpledroidble,simpleble-bridge}.aar``.

		2. Declare the dependency on your app's ``build.gradle{.kts}`` file (note: relative paths begin from your app's module folder)::

		====================

		First you'll need to provide ``SimpleDroidBLE.contextReference`` with a WeakReference to the app's context. In this step, the native code will be loaded in memory and permissions will be requested to the user.

Android onboarding & basic usage documentation #339

Are you sure you want to change the base?

Android onboarding & basic usage documentation #339

Conversation

tombertoli commented Sep 11, 2024

tombertoli commented Sep 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment