ADR 0001: Add Windows 10 Platform Support Using Native WinRT APIs

Status: Accepted

Date: 2026-04-10

Deciders: Blue Falcon maintainers

Technical Story: Windows desktop users requested native BLE support to enable cross-platform Kotlin applications spanning mobile, web, and desktop environments.

Context

Blue Falcon is a Kotlin Multiplatform BLE library supporting Android, iOS, macOS, JavaScript, and Raspberry Pi. Windows desktop was notably absent as a supported platform, limiting the library’s usefulness for developers building truly cross-platform applications.

The primary challenge was determining how to implement Windows BLE support while:

• Maintaining API consistency with existing platforms
• Avoiding third-party dependencies (per project requirements)
• Ensuring native performance
• Working within Kotlin Multiplatform’s JVM target constraints

Windows 10 (version 1803+) provides built-in Bluetooth LE support through the Windows Runtime (WinRT) APIs in the Windows.Devices.Bluetooth namespace, but these are C++ APIs that require bridging to the JVM.

Decision

We will implement Windows platform support using a three-layer architecture:

1. Kotlin/JVM Layer: Platform-specific implementation of the Blue Falcon API using Kotlin coroutines for async operations
2. JNI Bridge Layer: Native interface layer for marshaling calls between Kotlin/Java and C++
3. Native Windows Layer: Direct C++ implementation using Windows Runtime (WinRT) Bluetooth LE APIs

This implementation will:

• Use only built-in Windows APIs (no third-party Bluetooth libraries)
• Target the windows JVM platform in Kotlin Multiplatform
• Require a native DLL (bluefalcon-windows.dll) built with CMake and Visual Studio
• Support Windows 10 version 1803 (April 2018 Update) or later
• Provide complete feature parity with other platforms

Consequences

Positive

• Zero third-party dependencies: Uses only Windows built-in APIs, reducing maintenance burden and security surface
• Native performance: Direct WinRT API calls without abstraction overhead
• Full platform coverage: Blue Falcon now supports all major desktop and mobile platforms
• API consistency: Same Blue Falcon API works identically across all platforms
• Modern C++ patterns: Uses C++17, WinRT async patterns, and thread-safe design
• Complete feature set: All BLE operations supported (scan, connect, GATT operations, notifications, MTU, descriptors)

Negative

• Complex build process: Requires Visual Studio, Windows 10 SDK, and CMake to build the native library
• JNI overhead: Method calls cross JNI boundary, adding minimal latency compared to pure native
• Platform-specific testing: Requires actual Windows hardware for integration testing
• Binary distribution: Must distribute pre-compiled DLL or provide build instructions
• Maintenance burden: Need to maintain C++ codebase alongside Kotlin implementations

Neutral

• Development requirements: Windows 10 SDK (10.0.17763.0+), Visual Studio 2019+, JDK 11+
• Runtime requirements: Windows 10 version 1803+, JRE 11+
• Architecture support: Initially x64, can be extended to x86 and ARM64
• File structure: Adds windowsMain/kotlin/ and windowsMain/cpp/ directories

Alternatives Considered

Alternative 1: Use blessed-bluez or TinyB Library

A third-party Bluetooth library wrapper that could potentially work on Windows.

Pros:

• Potentially simpler implementation
• Might provide cross-platform Linux/Windows support

Cons:

• Violates project requirement of “no third-party dependencies”
• blessed-bluez is primarily for Linux (used in RPI implementation)
• TinyB adds external dependency and maintenance risk
• May not support all Windows BLE features
• Additional library to maintain and update

Why not chosen: Explicitly rejected per project requirements to avoid third-party Bluetooth libraries.

Alternative 2: Pure JVM Implementation Using Java Bluetooth APIs

Attempt to use Java’s built-in Bluetooth APIs (JSR-82) or newer Java libraries.

Pros:

• No native code required
• Simpler build process
• Cross-platform JVM compatibility

Cons:

• JSR-82 is outdated and doesn’t support BLE properly
• No standard Java BLE API exists in modern JDK
• Third-party Java BLE libraries are limited and Windows support is poor
• Would still require native libraries under the hood

Why not chosen: No viable pure-JVM BLE solution exists for Windows with required feature completeness.

Alternative 3: Kotlin/Native Windows Target

Use Kotlin/Native instead of Kotlin/JVM for Windows platform.

Pros:

• Native compilation, no JVM required
• Direct C interop without JNI
• Potentially better performance

Cons:

• Kotlin/Native Windows support is less mature than JVM
• Most Kotlin multiplatform projects target JVM for desktop
• Would diverge from standard Kotlin desktop deployment patterns
• Limited ecosystem compared to JVM
• Harder to integrate with existing JVM-based Kotlin applications

Why not chosen: JVM target is more practical for desktop Kotlin applications and aligns better with typical deployment scenarios.

Alternative 4: Wrapper Around Windows CLI Tools

Use Windows PowerShell or command-line Bluetooth utilities.

Pros:

• No native code compilation needed
• Simple process execution from JVM

Cons:

• Extremely limited functionality
• No support for notifications/indications
• High latency for operations
• Poor error handling
• Not suitable for production applications
• No proper async support

Why not chosen: Insufficient functionality and performance for a production BLE library.

Implementation Notes

Build Process

The native library must be built separately before the Kotlin library can be used:

1. Navigate to library/src/windowsMain/cpp
2. Use CMake to generate Visual Studio project
3. Compile with Visual Studio C++ compiler
4. Resulting DLL must be in Java library path or application working directory

Migration Path

This is a new platform addition, not a migration. Existing platforms are unaffected.

Files Created

Kotlin Layer:

• windowsMain/kotlin/dev/bluefalcon/BlueFalcon.kt (507 lines)
• windowsMain/kotlin/dev/bluefalcon/BluetoothPeripheral*.kt
• windowsMain/kotlin/dev/bluefalcon/BluetoothService.kt
• windowsMain/kotlin/dev/bluefalcon/BluetoothCharacteristic.kt
• Supporting type definitions

Native Layer:

• windowsMain/cpp/BluetoothLEManager.cpp (618 lines)
• windowsMain/cpp/BluetoothLEManager.h (70 lines)
• windowsMain/cpp/jni_bridge.cpp (137 lines)
• windowsMain/cpp/CMakeLists.txt

Documentation:

• WINDOWS_IMPLEMENTATION_SUMMARY.md
• windowsMain/cpp/README.md
• Updated main README.md

CI/CD Changes

Added Windows verification job to CI workflows:

• pull-requests.yml: Build verification on windows-latest
• release.yml: Compilation verification before publishing

Related Decisions

• Future ADR may address distribution strategy for pre-compiled native libraries
• Future ADR may address support for additional desktop platforms (Linux desktop)

References

• Windows Bluetooth LE APIs: https://docs.microsoft.com/en-us/windows/uwp/devices-sensors/bluetooth
• WinRT C++ reference: https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth
• JNI specification: https://docs.oracle.com/en/java/javase/17/docs/specs/jni/index.html
• Original implementation summary: /WINDOWS_IMPLEMENTATION_SUMMARY.md
• Build instructions: /library/src/windowsMain/cpp/README.md