Merge pull request #42 from Beepiz/develop

Version 0.4.0

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Change log for BleGattCoroutines
 
+## Version 0.4.0 (2019-05-05)
+Compiled with Kotlin 1.3.31 (and kotlinx.coroutines 1.2.1).
+
+This is an important release for BleGattCoroutines that includes fixes, improvements & new features.
+
+### Fixes
+- Fix rare hard to track uncaught exceptions caused by `offer` called on closed channels. (744e862f)
+- Automatically request disconnect on close by default. Avoids issue where connection is not stopped by close on Android's side and prevents subsequent connections.
+
+### New features
+- Add a public `bluetoothDevice` property to the `GattConnection` interface, thanks to [Brian Parma](https://github.com/bj0) contribution.
+- Add `requestMtu` function on `GattConnection`, thanks to [Bill Cauchois](https://github.com/wcauchois) contribution.
+- Add first-class notifications enabling on remote device with `setCharacteristicNotificationsEnabledOnRemoteDevice`. This was the most requested feature.
+- Add `openNotificationSubscription` function to receive notifications only for a specific characteristic. This can replace usage of the `notifyChannel` property.
+
+### Changes
+- The `notifyChannel` property now returns a new subscription each time, so it is possible to have multiple consumers.
+- Exceptions to catch are now mentioned in `GattConnection` KDoc. (b85c9bea)
+- Add workaround for `Dispatchers.Main` initialization doing blocking I/O (8783db98).
+- Drop main thread usage requirement. You can now use the dispatcher you want.
+- Samples and `@RequiresApi` annotations migrated to AndroidX.
+- Samples now properly request runtime permissions, with a single suspending function call thanks to [Splitties permissions](https://github.com/LouisCAD/Splitties/tree/master/modules/permissions).
+- Minor doc improvements.
+
 ## Version 0.3.0 (2018-11-27)
 
 ### Kotlin 1.3
@@ -14,6 +38,7 @@ https://github.com/LouisCAD/Splitties/blob/e77c909585f1b6d457af0fe18655e4794434c
 - All the package names changed, dropping `experimental` from the hierarchy.
 - The API is still experimental, and is annotated accordingly.
 
+
 ## Version 0.2.0 (2018-11-27)
 This release is compiled with Kotlin 1.2.71 and relies on the version 0.30.2
 of kotlinx.coroutines.
@@ -33,7 +58,8 @@ properly, especially if you want to retry or recover._
 - You can pass `ConnectionSettings` when creating a `GattConnection` instance. With this, you can
 change transport, physical layer (aka. PHY) and enable auto connect.
 - `requireXxx` extension functions for `GattConnection`, `BluetoothGattService` and
-`BluetoothGattCharacteristic` thanks to @Miha-x64 contribution.
+`BluetoothGattCharacteristic` thanks to [Mike (@Miha-x64)](https://github.com/Miha-x64) contribution.
+
 
 ## Version 0.1.0 (2018-03-19)
 This is the first release of BleGattCoroutines.

README.md

@@ -47,7 +47,11 @@ feedback while you're using this library.**
 
 _Please, open an issue if something can be improved. If you just want to
 tell the author what you're doing with this library, feel free to reach out
-via [Twitter](https://twitter.com/Louis_CAD) DM, or public tweet._
+via [Twitter](https://twitter.com/Louis_CAD) DM, public tweet._
+
+You can also join the discussion on Kotlin's Slack in the
+[#beepiz-libraries](https://kotlinlang.slack.com/messages/beepiz-libraries) channel (you can get
+an invitation [here](http://slack.kotlinlang.org/)).
 
 ## Usage
 
@@ -101,20 +105,22 @@ https://github.com/Beepiz/BleGattCoroutines/blob/dd562dc49e5623bfc874dd9ff37d62d
 ```kotlin
 fun BluetoothDevice.logGattServices(tag: String = "BleGattCoroutines") = launch {
     val deviceConnection = GattConnection(bluetoothDevice = this@logGattServices)
-    deviceConnection.connect() // Suspends until connection is established
-    val gattServices = deviceConnection.discoverServices() // Suspends until completed
-    gattServices.forEach {
-        it.characteristics.forEach {
-            try { 
-                deviceConnection.readCharacteristic(it) // Suspends until characteristic is read
-            } catch (e: Exception) {
-                Log.e(tag, "Couldn't read characteristic with uuid: ${it.uuid}", e)
+    try {
+        deviceConnection.connect() // Suspends until connection is established
+        val gattServices = deviceConnection.discoverServices() // Suspends until completed
+        gattServices.forEach {
+            it.characteristics.forEach {
+                try { 
+                    deviceConnection.readCharacteristic(it) // Suspends until characteristic is read
+                } catch (e: Exception) {
+                    Log.e(tag, "Couldn't read characteristic with uuid: ${it.uuid}", e)
+                }
             }
+            Log.d(tag, it.print(printCharacteristics = true))
         }
-        Log.v(tag, it.print(printCharacteristics = true))
+    } finally {
+        deviceConnection.close() // Close when no longer used. Also triggers disconnect by default. 
     }
-    deviceConnection.disconnect() // Disconnection is optional. Useful if you don't close and reconnect later.
-    deviceConnection.close() // Close when no longer used it NOT optional 
 }
 ```
 
@@ -169,44 +175,40 @@ into your root project `build.gradle` file:
 ```groovy
 allProjects {
     ext {
-        blegattcoroutines_version = '0.3.0'
+        blegattcoroutines_version = '0.4.0'
     }
 }
 ```
 Here are all the artifacts of this library. Just use the ones you need:
-```groovy
-implementation "com.beepiz.blegattcoroutines:blegattcoroutines-core:$blegattcoroutines_version"
-implementation "com.beepiz.blegattcoroutines:blegattcoroutines-genericaccess:$blegattcoroutines_version"
+```kotlin
+implementation("com.beepiz.blegattcoroutines:blegattcoroutines-core:$blegattcoroutines_version")
+implementation("com.beepiz.blegattcoroutines:blegattcoroutines-genericaccess:$blegattcoroutines_version")
 ```
-#### Snapshots
-Let's say you need a new feature or a fix that did
-not make it to a release yet:
 
-You can grab it in the latest snapshot by adding the
-snapshots repository and changing the library version to the -SNAPSHOT
-version in your root project `build.gradle` file:
+#### Dev versions
+Let's say you need a new feature or a fix that did not make it to a release yet:
+
+You can grab it in the latest dev version by adding the corresponding repository and
+changing the library version to the dev version you need in your root project `build.gradle` file:
 
 ```groovy
 allProjects {
     repositories {
         google()
-        jcenter() // Add snapshots repo below
-        maven { url 'https://oss.jfrog.org/artifactory/oss-snapshot-local' }
+        jcenter() // Add dev versions repo below
+        maven { url 'https://dl.bintray.com/louiscad/splitties-dev' }
     }
     ext {
-        blegattcoroutines_version = '0.3.0-SNAPSHOT' // Change this line
+        splitties_version = '0.4.0-dev-001' // Change this line
     }
 }
 ```
 
-If you need to, you can browse the deployed snapshots [here on artifactory](
-https://oss.jfrog.org/webapp/#/artifacts/browse/tree/General/oss-snapshot-local/com/beepiz/blegattcoroutines
-).
-
 ### Other build systems
 For maven and alternative build-systems, check the [Bintray page](
 https://bintray.com/beepiz/maven/blegattcoroutines).
 
 ## New versions notifications
-To get notified for new versions, be sure to click on "Watch" on the
-[BleGattCoroutines Bintray page](https://bintray.com/beepiz/maven/blegattcoroutines).
+Releases are announced on GitHub, you can subscribe by[clicking on "Watch", then "Releases only"](
+https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository
+).

RELEASING.md

@@ -1,9 +1,17 @@
 # Releasing this library:
 
-## Releasing a stable, release candidate, beta, or alpha version
+## Releasing a stable, beta or alpha version
+
+### Option A: Run the interactive script
+
+Run [Releasing.kts](Releasing.kts) (preferably in system terminal as IDE could crash)
+with `kotlinc -script Releasing.kts` and follow the steps directly from the command line.
+
+### Option B: Manual steps
 
 1. Checkout the `develop` branch, if not already done.
-2. Change the `library_version` ext property in root project's `build.gradle` file to a non-SNAPSHOT version.
+2. Change the `thisLibrary` constant in the
+[ProjectVersions](buildSrc/src/main/kotlin/ProjectVersions.kt) file to a non-dev version.
 3. Update the `README.md` with the new version.
 4. Update the `CHANGELOG.md` for the impending release.
 5. Run `git commit -am "Prepare for release X.Y.Z"` (where X.Y.Z is the new version).
@@ -18,15 +26,13 @@
 14. Checkout the `master` branch.
 15. Pull from GitHub repository to update the local `master` branch.
 16. Checkout the `develop` branch.
-17. Change the `library_version` ext property in root project back to a -SNAPSHOT version.
+17. Change the `thisLibrary` constant in the
+    [ProjectVersions](buildSrc/src/main/kotlin/ProjectVersions.kt) file back to a `-dev-` version.
 18. Run `git commit -am "Prepare next development version."`.
 19. Run `git push origin`.
 
-## Publishing a SNAPSHOT
+## Publishing a dev version
 
-1. Make sure `library_version` ext property in root project's `build.gradle` file is set to
-a -SNAPSHOT version.
-2. Run `./gradlew artifactoryPublish`. **Do it from command line,
-not from Android Studio**, as the artifacts are not uploaded when the
-gradle task is run from the IDE (as of Android Studio `3.1.0-rc01`) because
-of a yet to be reported bug.
+1. Make sure the `thisLibrary` constant in the
+[ProjectVersions](buildSrc/src/main/kotlin/ProjectVersions.kt) file is set to a `-dev-` version.
+2. Run `./gradlew clean bintrayUpload`.