Library unifies Bluetooth functionality across various platforms, offering a common API for actions like device connection, service fetching, and characteristic handling, eliminating platform-specific code duplication.
Blue-Falcon
A Bluetooth Low Energy (BLE) Kotlin Multiplatform library for iOS, Android, MacOS, Raspberry Pi, Windows, and JavaScript.
Blue Falcon provides a unified API for Bluetooth LE operations across all platforms. Each platform implementation compiles to native code, ensuring optimal performance and seamless integration with platform-specific APIs.
🎉 Version 3.0+ introduces a plugin-based engine architecture inspired by Ktor, enabling extensibility. The 2.x API is still available via a compatibility layer — see the Migration Guide.
Upgrading from 2.x? See the Migration Guide — most apps require zero code changes.
commonMain.dependencies {
implementation("dev.bluefalcon:blue-falcon-core:3.4.5")
}
// Add platform-specific engines
androidMain.dependencies {
implementation("dev.bluefalcon:blue-falcon-engine-android:3.4.5")
}
iosMain.dependencies {
implementation("dev.bluefalcon:blue-falcon-engine-ios:3.4.5")
}
commonMain.dependencies {
// Logging support
implementation("dev.bluefalcon:blue-falcon-plugin-logging:3.4.5")
// Automatic retry with exponential backoff
implementation("dev.bluefalcon:blue-falcon-plugin-retry:3.4.5")
// Service/characteristic caching
implementation("dev.bluefalcon:blue-falcon-plugin-caching:3.4.5")
}
import dev.bluefalcon.core.*
import dev.bluefalcon.plugins.logging.*
// Configure with DSL
val blueFalcon = BlueFalcon {
engine = AndroidEngine(context) // or iOSEngine(), macOSEngine(), etc.
install(LoggingPlugin) {
level = LogLevel.DEBUG
}
install(RetryPlugin) {
maxAttempts = 3
initialDelay = 500
}
}
// Reactive Flow API
launch {
blueFalcon.peripherals.collect { devices ->
devices.forEach { device ->
println("Device: ${device.name}")
}
}
}
// Start scanning
blueFalcon.scan()
blue-falcon-engine-js artifact ships both js and wasmJs browser variants; Gradle resolves the right one for your target automaticallyscan() opens the browser's device chooser; dismissing it without picking a device is a no-op (no peripheral added), not an errorbluefalcon-windows.dll (from source)If you are building Blue Falcon's Windows implementation from source, build the native DLL with CMake:
cd library\src\windowsMain\cpp
mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release
The resulting bluefalcon-windows.dll is generated in the Release directory. Copy it to your Java library path or to library/src/windowsMain/resources/.
For full Windows setup and troubleshooting, see:
library/src/windowsMain/WINDOWS.mdlibrary/src/windowsMain/cpp/README.mdBlue Falcon 3.0 uses a three-layer architecture:
┌─────────────────────────────────────────┐
│ Your Application Code │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Core (Interfaces + Plugin System) │
│ • BlueFalcon API │
│ • Plugin Registry │
│ • Type Definitions │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Platform Engines (6 implementations) │
│ • AndroidEngine │
│ • iOSEngine, macOSEngine │
│ • JSEngine │
│ • WindowsEngine │
│ • RPiEngine │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Native Platform APIs │
│ • Android Bluetooth │
│ • CoreBluetooth (iOS/macOS) │
│ • Web Bluetooth │
│ • Windows WinRT │
│ • BlueZ (Linux) │
└─────────────────────────────────────────┘
See the Plugin Development Guide to create your own!
We welcome contributions! Blue Falcon follows a structured decision-making process:
For significant architectural changes or new features:
For bug fixes, docs, or small improvements:
See CONTRIBUTING.md for detailed guidelines.
blueFalcon.clearPeripherals()
// Check scanning state val scanning: Boolean = blueFalcon.isScanning
#### Observing Discovered Devices
```kotlin
// Observe discovered peripherals via StateFlow
blueFalcon.peripherals.collect { peripherals: Set<BluetoothPeripheral> ->
// update your UI with the discovered devices
}
// Observe Bluetooth manager state (Ready / NotReady)
blueFalcon.managerState.collect { state: BluetoothManagerState ->
when (state) {
BluetoothManagerState.Ready -> { /* Bluetooth is available */ }
BluetoothManagerState.NotReady -> { /* Bluetooth is unavailable */ }
}
}
// Connect to a peripheral (autoConnect = false for direct connection)
blueFalcon.connect(bluetoothPeripheral, autoConnect = false)
// Disconnect from a peripheral
blueFalcon.disconnect(bluetoothPeripheral)
// Check current connection state
val state: BluetoothPeripheralState = blueFalcon.connectionState(bluetoothPeripheral)
// Returns: Connecting, Connected, Disconnected, Disconnecting, or Unknown
blueFalcon.requestConnectionPriority(bluetoothPeripheral, ConnectionPriority.High)
peripheral: BluetoothPeripheral? = blueFalcon.retrievePeripheral()
When autoDiscoverAllServicesAndCharacteristics is true (default), services and characteristics are discovered automatically after connection. You can also trigger discovery manually:
// Discover services (optionally filter by service UUIDs)
blueFalcon.discoverServices(bluetoothPeripheral, serviceUUIDs = emptyList())
// Discover characteristics for a specific service (optionally filter by UUIDs)
blueFalcon.discoverCharacteristics(
bluetoothPeripheral,
bluetoothService,
characteristicUUIDs = emptyList()
)
// Read a characteristic value
blueFalcon.readCharacteristic(bluetoothPeripheral, bluetoothCharacteristic)
// Write a string value
blueFalcon.writeCharacteristic(
bluetoothPeripheral,
For the complete API including descriptors, MTU, L2CAP, and bonding, see the API Reference.
Blue Falcon is released under the MIT License.
Made with ❤️ by the Blue Falcon community
| Platform | Engine Module | Status | Notes |
|---|
| Android | blue-falcon-engine-android | ✅ Stable | Full BLE support including L2CAP, bonding |
| iOS | blue-falcon-engine-ios | ✅ Stable | CoreBluetooth wrapper |
| macOS | blue-falcon-engine-macos | ✅ Stable | CoreBluetooth wrapper |
| JavaScript | blue-falcon-engine-js | ✅ Stable | Web Bluetooth API (js browser target) |
| Wasm (browser) | blue-falcon-engine-js | ✅ Stable | Web Bluetooth API (wasmJs browser target) |
| Windows | blue-falcon-engine-windows | ✅ Stable | WinRT via JNI (Windows 10 1803+) |
| Raspberry Pi | blue-falcon-engine-rpi | ✅ Stable | Blessed library (BlueZ) |
Create an Architecture Decision Record (ADR)
# Use the ADR template
cp docs/adr/ADR-TEMPLATE.md docs/adr/XXXX-your-proposal.md
Let AI help you write it
Submit a Pull Request
Surfaced from shared tags and platforms — no rankings paid for.