A Bluetooth kotlin multiplatform "Cross-Platform" library for iOS and Android

Overview

Blue Falcon Blue-Falcon CI Kotlin badge badge badge badge badge

A Bluetooth "Cross Platform" Kotlin Multiplatform library for iOS, Android, MacOS, Raspberry Pi and Javascript.

Bluetooth in general has the same functionality for all platforms, e.g. connect to device, fetch services, fetch characteristics.

This library is the glue that brings those together so that mobile developers can use one common api to perform the bluetooth actions.

The idea is to have a common api for using bluetooth as the principle of bluetooth is the same but each platform ios and android has different apis which means you have to duplicate the logic for each platform.

What this library isn't? It is not a cross platform library, this is a multiplatform library. The difference? each platform is compiled down to the native code, so when you use the library in iOS, you are consuming an obj-c library and same principle for Android and so on.

Basic Usage

iOS & MacOS

Create an instance of BlueFalcon and then call the scan method.

By passing in a string uuid of the service uuid, you can filter to scan for only devices that have that service.

let blueFalcon = BlueFalcon(serviceUUID: nil)
blueFalcon.scan()

Android

Install

implementation 'dev.bluefalcon:blue-falcon-android:0.9.6'

And if you are using the debug variant:

implementation 'dev.bluefalcon:blue-falcon-android-debug:0.9.6'

The Android sdk requires an Application context, we do this by passing in on the BlueFalcon constructor, in this example we are calling the code from an activity(this).

By passing in a string uuid of the service uuid, you can filter to scan for only devices that have that service.

try {
    val blueFalcon = BlueFalcon(this, null)
    blueFalcon.scan()
} catch (exception: PermissionException) {
    //request the ACCESS_COARSE_LOCATION permission
}

Raspberry Pi

Install

The Raspberry Pi library is using Java.

implementation 'dev.bluefalcon:blue-falcon-rpi:0.9.6'

Javascript

Install

Simply copy the compiled javascript file (blue-falcon.js) to your web directory.

See the JS-Example for details on how to use.

Kotlin Multiplatform

Install

implementation 'dev.bluefalcon:blue-falcon:0.9.6'

Please look at the Kotlin Multiplatform example in the Examples folder.

BlueFalcon API

The basic functionality of the api is listed below, this should be a simplistic as possible and is the same in any platform.

    fun connect(bluetoothPeripheral: BluetoothPeripheral, autoConnect: Boolean)
    fun disconnect(bluetoothPeripheral: BluetoothPeripheral)
    fun scan()
    fun stopScanning()
    fun readCharacteristic(
        bluetoothPeripheral: BluetoothPeripheral,
        bluetoothCharacteristic: BluetoothCharacteristic
    )
    fun notifyCharacteristic(
        bluetoothPeripheral: BluetoothPeripheral,
        bluetoothCharacteristic: BluetoothCharacteristic,
        notify: Boolean
    )
    fun writeCharacteristic(
        bluetoothPeripheral: BluetoothPeripheral,
        bluetoothCharacteristic: BluetoothCharacteristic,
        value: String
    )
    fun readDescriptor(
        bluetoothPeripheral: BluetoothPeripheral,
        bluetoothCharacteristic: BluetoothCharacteristic,
        bluetoothCharacteristicDescriptor: BluetoothCharacteristicDescriptor
    )
    fun changeMTU(bluetoothPeripheral: BluetoothPeripheral, mtuSize: Int)

Examples

This repo contains examples for kotlin MP, ios and android in the examples folder, install their dependencies, and run it locally:

Kotlin MP

Open the kotlin MP example directory in InteliJ and then run the install targets.

iOS & MacOS

To run the MacOS & iOS example, you need to reference the relevant framework by including it in your poroject. Ensure your project has the Framework search paths referencing the framework directory.

Android

Open the root directory of the project in Android Studio and run the Android app target from the ide.

Raspberry Pi

This example can only be ran on a Raspberry pi, it will crash otherwise.

Javascript

Open the index.html file in a web browser.

Support

For a bug, feature request, or cool idea, please file a Github issue.

Two big little things

Keep in mind that Blue-Falcon is maintained by volunteers. Please be patient if you don’t immediately get an answer to your question; we all have jobs, families, obligations, and lives beyond this project.

Many thanks to everyone so far who has contributed to the project, it really means alot.

Comments
  • Notify not working on Android

    Notify not working on Android

    Describe the bug When calling the notifyCharacteristic, the onCharacteristicChanged never firing. I am getting a value for the read. And I have checked that the device indeed does support notifications using the LightBlue Application on IOS.

    To Reproduce Steps to reproduce the behavior:

    1. Connect to the device using blueFalcon.connect(bluetoothPeripheral, true)
    2. Wait until didDiscoverServices Returns
    3. Search through service to find the characteristic I want to nofify4.
    4. Call notifyCharacteristic on the returned characteristic

    char = service.characteristics.first { it.name == TESS5600_DATA_CHAR.lowercase() } bluetoothService.characteristicDelegate = this bluetoothService.notifyCharacteristic(bluetoothPeripheral, char!!, true)

    Expected behavior Expecting the onCharacteristicChanged to fire

    Smartphone

    • Device: Samsung Tablet
    • OS: Android API 31
    bug 
    opened by burnhamd 4
  • Windows 10 platform support

    Windows 10 platform support

    There is no a working solution to use Windows Bluetooth Api in Java/Kotlin desktop app. The only was is to switch to Linux or to C# Is it possible to port windows to use in kotlin somehow? Do you mind to schedule such feature?

    enhancement 
    opened by permiakover 7
  • changeMTU() method does not work as expected

    changeMTU() method does not work as expected

    When requesting a change of the MTU, the peripheral returned by the callback does not contain services and characteristics. Yet, if you keep a reference of previous characteristics, one cannot write or read on it anymore.

    The problem seems to lie in the fact that the MTU change request should appear between the connection and the discovery of services. Yet BlueFalcon abstracts this layer by calling directly the discovery of services as soon as the peripheral is connected.

    It could be interesting to add an MTU request within the connect method for instance.

    bug 
    opened by davidlepilote 2
  • BluetoothGatt: android.os.DeadObjectException

    BluetoothGatt: android.os.DeadObjectException

    Expected For creating a connection, I am using method connect() with autoConnect flag set to true. This is setup once and it is expected that after setting up this "autoConnect", there is no other action required and Android OS BLE stack will notify the app, once remote device becomes available, and this call will never time out.

    Actual Sometimes, I can reproduce following behavior: App is capable of connecting to device, but when app attempts to write bytes, it results in following exception: "BluetoothGatt: android.os.DeadObjectException"

    To Reproduce Steps to reproduce the behavior:

    1. call connect method with autoConnect flag set to true
    2. Wait a few hours
    3. After reconnection, writing to device will always result in "BluetoothGatt: android.os.DeadObjectException"

    Note: Even restarting the BT module will not solve the issue. What will solve the issue is reinitialising BlueFalcon library.

    Smartphone (please complete the following information):

    • Device: [Samsung Galaxy A5]
    • OS: [Android 7]
    • BlueFalcon version: [0.7.2]
    bug 
    opened by PeterKucera 0
  • GATT connection not closing (ANDROID)

    GATT connection not closing (ANDROID)

    Hi, during more stress test of my app, i've discovered that Android device after some time causes peripheral to stop accept connections and stops from being visible in ble scan. This is not a case for iOS. Steps to reproduce:

    1. Transport type LE
    2. Start LE scan if peripheral MAC found, connect
    3. If onConnected emited, stop LE scan
    4. acquire all characteristics (setup notifications etc)
    5. wait a little time
    6. disconnect
    7. wait a little time
    8. repeat from point 1

    After few loops, you will not be able to find peripheral MAC. Reseting peripheral or Android BT restores connectivity, removing Initializing BlueFalcon again also solves this issue. As far as i can tell, the GATT connection is held and this causes to reach maximum available connections. Good peripheral to test is Raspberry PI 3b+ with simple code using bluez.

    bug 
    opened by felislynx-silae 6
  • Writing characteristic not working after reconnect.

    Writing characteristic not working after reconnect.

    Issue created with #45 fix. After disconnect by calling disconnect method and reconnect again with device within same BlueFalcon instance, we won’t be able to write to gatt characteristic.

    It is because when we close the gatt connection in disconnect method, the method onConnectionStateChange from BluetoothGattCallback will never be called and as a result removeGatt method won’t be called. Thus the item in the Gatt list is not removed. In such cases when trying to write a characteristic we take an old object which is not currently connected to the device.

    In my opinion there are two solutions add additional call of removeGatt in disconnect method moving close() method from disconnect to onConnectionStateChange in BluetoothGattCallback so gatt will be closed after remove.

    First solution should work properly but it is not that clean and neat. Second is better but You need to check if moving close method won’t be an issue in disconnect scenarios and in that case You need to remove delegates.forEach { it.didDisconnect(bluetoothPeripheral) } from disconnect method to avoid calling it twice. This solution need to be tested very carefully.

    bug 
    opened by kazyh 3
Releases(0.10.10)
Owner
Andrew Reed
Mobile developer, keen interest in Kotlin Multiplatform
Andrew Reed
Kotlin Asynchronous Bluetooth Low Energy provides a simple Coroutines-powered API for interacting with Bluetooth Low Energy devices.

Kotlin Asynchronous Bluetooth Low Energy provides a simple Coroutines-powered API for interacting with Bluetooth Low Energy devices.

JUUL Labs 275 Sep 14, 2021
[UNMAINTAINED][Android] Bluetooth Serial Port Profile which comfortable to developer application to communication with microcontroller via bluetooth

⚠ WARNING: This project is no longer being maintained Android-BluetoothSPPLibrary Bluetooth Serial Port Profile which comfortable to developer applica

Akexorcist 1.7k Dec 31, 2022
BLESSED Coroutines, a Bluetooth Low Energy (BLE) library for Android using Kotlin Coroutines

BLESSED for Android with Coroutines - BLE made easy BLESSED is a very compact Bluetooth Low Energy (BLE) library for Android 8 and higher, that makes

Martijn van Welie 82 Jan 1, 2023
This library allows for easy access to a Bluetooth LE device's AdRecord and RSSI value. It offers additional functionality for iBeacons.

Bluetooth LE Library for Android This library allows for easy access to a Bluetooth LE device's Advertisement Records. It also offers: A simple runnin

Alexandros Schillings 843 Dec 13, 2022
An Android Library for handling Bluetooth Low Energy on Android Easy

An Android Library for handling Bluetooth Low Energy on Android Easy

Leandro SQ 42 Jan 3, 2023
An Android library that solves a lot of Android's Bluetooth Low Energy problems

A library that makes working with Bluetooth LE on Android a pleasure. Seriously.

Nordic Semiconductor 1.4k Jan 7, 2023
A reactive, interface-driven central role Bluetooth LE library for Android

RxCentralBle RxCentralBle provides a simple reactive paradigm for connecting to and communicating with Bluetooth LE peripherals from the central role.

Uber Open Source 198 Nov 29, 2022
Kotlin Asynchronous Bluetooth Low-Energy

Kable Kotlin Asynchronous Bluetooth Low Energy provides a simple Coroutines-powered API for interacting with Bluetooth Low Energy devices. Usage is de

JUUL Labs 493 Dec 25, 2022
A non-trivial Bluetooth LE app using Kable and app architecture best practices

kable_mvvm_demo The intention of this project is to demonstrate a non-trivial Bluetooth LE app using Kable and app architecture best practices. ⚠️ The

Chris Laplante 14 Aug 18, 2022
BluePass extracts two factor authentication codes (2FA) from SMS and sends them to a paired device via Bluetooth RFCOMM.

BluePass extracts two factor authentication codes (2FA) from SMS and sends them to a paired device via Bluetooth RFCOMM.

Manuel Huber 15 Dec 4, 2022
Open-source weight and body metrics tracker, with support for Bluetooth scales

Open-source weight and body metrics tracker, with support for Bluetooth scales

OliE 1.3k Jan 4, 2023
Smooth communication via bluetooth with other android devices or microcontrollers such as Arduino.

Android Smooth Bluetooth Smooth communication via bluetooth with other android devices or microcontrollers such as Arduino. Getting Started Add Gradle

Mantas Palaima 191 Nov 28, 2022
RxBle: Use Android Bluetooth API in Rx way

RxBle: Use Android Bluetooth API in Rx way A lightweight encapsulation of Android Bluetooth API. Use Android Bluetooth API in Rx way. Support multiple

null 3 Dec 2, 2022
Simple bluetooth flutter project

bluetooth_simple Simple bluetooth implementation. Getting Started This project is a starting point for a Flutter application. A few resources to get y

Aleksey Vasiliev 0 Nov 25, 2021
The purpose is to share the Internet capability of one device to the entire Bluetooth LAN.

bluenet The purpose is to share the Internet capability of one device to the entire Bluetooth LAN. To make a prototype of a soft bus, or actually, I w

yunlong.wen 1 Jun 28, 2022
User-friendly Lightweight TPM Remote Attestation over Bluetooth

Ultrablue Ultrablue (User-friendly Lightweight TPM Remote Attestation over Bluetooth) is a solution to allow individual users to perform boot state at

ANSSI 32 Jan 2, 2023
A simple, lightweight library intended to take away some of the cruft and tediousness of using the Android BLE.

Blueteeth What Is Blueteeth? Blueteeth is a simple, lightweight library intended to take away some of the cruft and tediousness of using the Android B

Robot Pajamas 103 Nov 26, 2022
kotlin android - network connection

MarsPhotos - Starter Code Starter code for Android Basics in Kotlin. Introduction Using this stater code you will create MarsPhotos is a demo app that

RICKY_SENSEI 1 Oct 25, 2022
🍔 Meals is a small demo app based on modern Android technologies and MVVM architecture

Meals ?? Meals is a small demo app based on modern Android technologies and MVVM architecture. built-in Kotlin, Coroutine, Flow, Retrofit, and Jetpack

Amr Jyniat 4 Nov 6, 2022