Blue Falcon Documentation

Blue Falcon 3.0 provides a comprehensive testing suite designed to verify different layers of the library. The testing stack is built on:

• Framework: Kotlin Test (kotlin.test)
• Coroutines: kotlinx-coroutines-test for testing asynchronous operations
• Mocking: Custom fakes and mocks (e.g., FakeBlueFalconEngine, MockPeripheral)
• Assertions: Built-in Kotlin Test assertions

The infrastructure supports unit tests, integration tests, plugin verification, platform-specific engine tests, and mock implementations.

The Windows implementation utilizes the Windows Runtime (WinRT) API design, resulting in the following performance profile:

• Startup Time: < 1 second for Bluetooth initialization.
• Scan Latency: 100-500ms to first device discovery.
• Connection Time: 1-3 seconds typical.
• Memory Footprint: Minimal; native memory is managed by WinRT.
• CPU Usage: Low; uses asynchronous operations with event callbacks.

Security & Privacy

• Uses the standard Windows OS Bluetooth security model.
• Pairing is handled directly by the Windows operating system.
• No third-party dependencies are used, reducing the attack surface.

Plugins can depend on other plugins by accepting them as constructor parameters. This allows one plugin to utilize the functionality or state of another during its install phase.

class MetricsPlugin(
    private val loggingPlugin: LoggingPlugin
) : BlueFalconPlugin {
    override fun install(client: BlueFalconClient, config: PluginConfig) {
        // Use loggingPlugin functionality
        loggingPlugin.log("MetricsPlugin installed")
    }
}

Blue-Falcon 3.0 uses a plugin-based engine architecture (defined in ADR 0002). This design allows for a core module to orchestrate operations while delegating platform-specific logic (like BLE operations) to specialized engines and plugins.

Key patterns demonstrated in the architecture include:

1. DSL-based Instance Creation: Using a new DSL API to instantiate Blue-Falcon.
2. Plugin Interception: Creating custom plugins (e.g., a LoggingPlugin) to intercept and monitor BLE operations.
3. Vendor-Specific Functionality: Implementing specialized plugins for specific hardware needs, such as a Nordic OTA Plugin for firmware updates.
4. Multi-Platform Engine Selection: A pattern for selecting the appropriate engine based on the current platform (e.g., Android vs. iOS).

Blue Falcon provides two ways to observe notification readiness:

1. notificationReadiness: A bounded hint stream intended for lightweight application observation. It is optimized for speed; slow collectors do not backpressure platform callbacks.
2. notificationReadinessState: A durable state used by plugins that require a loss-free handoff. Its manager and active-session epochs remain stable even when the hint stream coalesces under heavy load.

Note that NotificationReadiness.Manager is manager-wide because the underlying platform (Core Bluetooth) does not identify which specific central released transmit capacity.

Blue Falcon uses two coordinated mechanisms to expose characteristic notifications to different types of consumers:

1. Reactive Consumers (Apps/Coroutines): Use the notifications: SharedFlow<ByteArray> available on the BluetoothCharacteristic object for direct, reactive stream consumption.
2. Plugin Consumers: Use the BlueFalconPlugin.onNotificationReceived(peripheral, characteristic, value) hook for engine-level interception.
3. Legacy Consumers: The engine-level notification events are bridged to the legacy BlueFalconDelegate.didCharacteristcValueChanged callback, ensuring that subscribed notifications trigger existing delegate logic.

Note that notification events are best-effort asynchronous signals; delivery and ordering are still subject to the underlying platform's BLE behavior.

Blue Falcon implements Windows BLE support using a three-layer architecture to bridge Kotlin Multiplatform with native Windows Runtime (WinRT) APIs:

1. Kotlin/JVM Layer: Provides the high-level Blue Falcon API using Kotlin coroutines for asynchronous operations. This layer targets the windows JVM platform.
2. JNI Bridge Layer: A native interface layer that marshals calls between the Kotlin/Java environment and C++.
3. Native Windows Layer: A C++ implementation that makes direct calls to the Windows.Devices.Bluetooth namespace in the Windows Runtime (WinRT).

This architecture ensures zero third-party dependencies and native performance by using only built-in Windows APIs.