开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

RxBluetoothKotlin

Android + BLE + Kotlin + RxJava3

Bluetooth Low Energy on Android made easy with RxJava.

Made with love at the Equisense HQ. This library is used in our Equisense app since years.

Looking for BLE with Coroutines instead of RxJava ? Take a look at the LouisCAD's implementation.

⚠️ Android 12 permissions changes ⚠️

Starting from Android API 31, the fine location permission is not required anymore, instead of this, you have to use the BLUETOOTH_CONNECT and BLUETOOTH_SCAN permissions when dealing the bluetooth low energy framework. Before upgrading targetSdkVersion to 31 in your app, check your requestPermission calls according to this new permission.

Because of this change, RxBluetoothKotlin was updated to fire the NeedBluetoothScanPermission and NeedBluetoothConnectPermission exceptions at the right moment if they're missing at the runtime. Theses exceptions are fired since the release 3.2.0.

Learn more

⚠️ Important notice about Maven Central release ⚠️

RxBluetoothKotlin is released on Maven Central since the version 3.1.0 you don't have to worry about this library when jCenter will shutdown ! Unfortunately, according to the Maven Central policies, I must update my package to match with the host domain I own. I only own masselis.com, so the package name RxBluetothKotlin were renamed from com.vincentmasselis.rxbluetoothkotlin to com.masselis.rxbluetoothkotlin, as consequence, you have to renamed EVERY import from rxbluetoothkotlin to the new package name.

TL/DR

// Check the github release section to find the latest available version
implementation 'com.masselis.rxbluetoothkotlin:rxbluetoothkotlin-core:<<latest_version>>'

Scan

val bluetoothManager = context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
bluetoothManager.rxScan()
  .subscribe { scanResult ->
  }

Connect

bluetoothDevice.connectRxGatt()
  .flatMapMaybe { gatt -> gatt.whenConnectionIsReady().map { gatt } }
  .subsribe { rxBluetoothGatt ->
  }

Read

rxBluetoothGatt.read(characteristic)
  .subscribe { byteArray ->
  }

Write

rxBluetoothGatt.write(characteristic, byteArray)
  .subscribe { _ ->
  }

Listen

rxBluetoothGatt.enableNotification(characteristic)
  .flatMapPublisher { listenChanges(characteristic) }
  .subscribe { byteArray ->
  }

Disconnect

rxBluetoothGatt.disconnect().subscribe()

Requirements

• Min target API 18
• When scanning with RxBluetoothKotlin, you have to grant theses runtime permissions:
  • From Android 6 to 9 inclusive: ACCESS_COARSE_LOCATION
  • From Android 10 to 11 inclusive: ACCESS_FINE_LOCATION
  • From Android 12: BLUETOOTH_SCAN
• When connecting with RxBluetoothKotlin, you have to grant this runtime permission:
  • From Android 12: BLUETOOTH_CONNECT
• A turned on bluetooth chip (context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager).adapter.isEnabled
• You can add to your manifest <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

RxBluetoothKotlin declare the BLUETOOTH_SCAN permission into the AndroidManifest with the property usesPermissionFlags="neverForLocation". If you want to remove the usesPermissionFlags property, you have to add tools:remove="usesPermissionFlags" to your uses-permission node into your own AndroidManifest, if you want to update usesPermissionFlags by setting an other value you have to use tools:replace="usesPermissionFlags" instead.

Logging

When scanning with rxScan() or connecting with connectRxGatt(), you can set the logger parameter. By setting it, RxBluetoothKotlin will produce a log for every bluetooth input, output, starting scan, error thrown, etc.. I recommend to set it for debugging purposes and/or if you're not familiar with the Android BLE API. It could helps you a lot to understand what's going on between your app and the Bluetooth Low Energy device.

Error management

Interact with Bluetooth Low Energy devices on Android is hard. The BLE specs uses unfamiliar concepts, the BLE API from Android could fails at any moment and some exceptions are silent. Because of this, a basic method like write(BluetoothGattCharacteristic) could fails for 5 different reasons. It becomes harder if you are chaining this call with other calls, this sum up to a thrown exception when it's impossible to known which call fails and why.

For this reason, every public method from this library is documented with every exceptions which could be fired and most of the exception are unique. For example: write(BluetoothGattCharacteristic) could fire:

• Unique CharacteristicWriteDeviceDisconnected if the device disconnects while writing
• Unique CannotInitializeCharacteristicWrite if the Android API returned false when calling writeCharacteristic
• Unique CharacteristicWriteFailed if the characteristic could not be written
• BluetoothIsTurnedOff if bluetooth...... is turned off