Blue-Falcon

June 3, 2026 · View on GitHub

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.

✨ Features

🔌 Plugin Architecture - Extensible engine system with official and community plugins
📱 Cross-Platform - Single API for iOS, Android, macOS, JavaScript, Windows, and Raspberry Pi
🔄 Legacy Support - 2.x API available via compatibility layer (see Migration Guide)
⚡ Native Performance - Compiles to platform-native code (Obj-C, JVM, JS, etc.)
🔧 Flexible APIs - Choose between Flow-based reactive API or delegate callbacks
🎯 Type-Safe - Full Kotlin type safety across all platforms

📦 Installation

Upgrading from 2.x? See the Migration Guide — most apps require zero code changes.

Core + Engine

commonMain.dependencies {
    implementation("dev.bluefalcon:blue-falcon-core:3.4.2")
}

// Add platform-specific engines
androidMain.dependencies {
    implementation("dev.bluefalcon:blue-falcon-engine-android:3.4.2")
}

iosMain.dependencies {
    implementation("dev.bluefalcon:blue-falcon-engine-ios:3.4.2")
}

Optional Plugins

commonMain.dependencies {
    // Logging support
    implementation("dev.bluefalcon:blue-falcon-plugin-logging:3.4.2")
    
    // Automatic retry with exponential backoff
    implementation("dev.bluefalcon:blue-falcon-plugin-retry:3.4.2")
    
    // Service/characteristic caching
    implementation("dev.bluefalcon:blue-falcon-plugin-caching:3.4.2")
}

🚀 Quick Start

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()

📚 Documentation

Migration Guide - Upgrading from 2.x (legacy API reference)
API Reference - Complete API documentation
Plugin Development - Creating custom plugins
Testing Guide - Testing your BLE code
Publishing Guide - Release and publishing process
Windows Setup - Windows support details, including native DLL build steps

Architecture

ADR 0001 - Windows Platform Support
ADR 0002 - Plugin-Based Engine Architecture

🎯 Platform Support

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
Windows	`blue-falcon-engine-windows`	✅ Stable	WinRT via JNI (Windows 10 1803+)
Raspberry Pi	`blue-falcon-engine-rpi`	✅ Stable	Blessed library (BlueZ)

Platform Requirements

Android

Minimum SDK: 24 (Android 7.0)
Target SDK: 33 (Android 13)

iOS

Minimum: iOS 13.0+
Xcode 14.0+

macOS

Minimum: macOS 10.15+

JavaScript

Modern browsers with Web Bluetooth support
HTTPS required (security policy)

Windows

Windows 10 version 1803 (April 2018 Update) or later
JDK 11+

Building `bluefalcon-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.md
library/src/windowsMain/cpp/README.md

Raspberry Pi

Linux with BlueZ 5.0+
JDK 11+

🏗️ Architecture

Blue 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)                         │
└─────────────────────────────────────────┘

Official Plugins

LoggingPlugin - Configurable logging with custom loggers
RetryPlugin - Automatic retry with exponential backoff
CachingPlugin - Service/characteristic discovery caching

See the Plugin Development Guide to create your own!

🤝 Contributing

We welcome contributions! Blue Falcon follows a structured decision-making process:

Proposing Major Changes

For significant architectural changes or new features:

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
- Use GitHub Copilot or your preferred AI assistant
- Reference existing ADRs for context
- See Contributing Guide for details
Submit a Pull Request
- Link to your ADR
- Discuss with maintainers
- Implement once approved

Quick Contributions

For bug fixes, docs, or small improvements:

Fork the repository
Create a feature branch
Make your changes
Submit a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📖 Examples

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 */ }
    }
}

Connection Management

// 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

// Request connection priority (Android-specific, no-op on other platforms)
blueFalcon.requestConnectionPriority(bluetoothPeripheral, ConnectionPriority.High)
// Options: ConnectionPriority.Balanced, ConnectionPriority.High, ConnectionPriority.Low

// Retrieve a previously known peripheral by identifier
val peripheral: BluetoothPeripheral? = blueFalcon.retrievePeripheral("device-identifier")
// Android: MAC address format (e.g., "00:11:22:33:44:55")
// iOS/Native: UUID format (e.g., "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")

Service & Characteristic Discovery

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()
)

Reading & Writing Characteristics

// 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.

📄 License

Blue Falcon is released under the MIT License.

🙏 Acknowledgments

Built with Kotlin Multiplatform
Inspired by the Ktor plugin architecture
Community contributors and plugin developers

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Made with ❤️ by the Blue Falcon community