Add requestConnectionPriority support (#221)

* feat: add requestConnectionPriority

- Add BleConnectionPriority enum (balanced, highPerformance, lowPower)
- Add BleCapabilities.supportsConnectionPriorityApi flag
- Implement on Android via BluetoothGatt.requestConnectionPriority()
- Throw notSupported on iOS, macOS, Windows, Linux, and Web
- Update pigeon definition and regenerate platform channel files
- Bump version 1.2.0 -> 1.3.0

* fix: improve requestConnectionPriority implementation

- Remove redundant BleCapabilities guard in Dart layer (native handles it)
- Add BleConnectionPriority Kotlin enum mirroring Dart enum
- Map to explicit Android SDK constants via when expression
- Add firstOrNull with ILLEGAL_ARGUMENT for unknown priority values
- Add catch (e: Exception) block for broader error handling
- Fix enum doc comment (throws belongs on method, not enum)
- Remove stale capability check guidance from docs and README

---------

Co-authored-by: aqeel-bmec-co <aqeel@bmec.co>
Co-authored-by: aqeel-bmec-co <85945830+aqeel-bmec-co@users.noreply.github.com>

lib/src/models/ble_capabilities.dart

@@ -40,6 +40,9 @@ class BleCapabilities {
   static bool supportsConnectedDevicesApi = !_Platform.isWeb;
 
   static bool supportsRequestMtuApi = !_Platform.isWeb;
+
+  static bool supportsConnectionPriorityApi =
+      !_Platform.isWeb && defaultTargetPlatform == TargetPlatform.android;
 }
 
 class _Platform {

lib/src/models/ble_connection_priority.dart

@@ -0,0 +1,13 @@
+/// Connection priority hint passed to [UniversalBle.requestConnectionPriority].
+///
+/// Maps to Android `BluetoothGatt.CONNECTION_PRIORITY_*` constants.
+enum BleConnectionPriority {
+  /// Default OS-managed interval (~30-50 ms). Android constant: 0.
+  balanced,
+
+  /// Low-latency interval (~7.5-15 ms), higher power draw. Android constant: 1.
+  highPerformance,
+
+  /// Power-optimised interval (~100-125 ms). Android constant: 2.
+  lowPower,
+}

lib/src/models/model_exports.dart

@@ -12,3 +12,4 @@ export 'package:universal_ble/src/models/ble_connection_state.dart';
 export 'package:universal_ble/src/models/ble_device.dart';
 export 'package:universal_ble/src/models/ble_command.dart';
 export 'package:universal_ble/src/models/ble_capabilities.dart';
+export 'package:universal_ble/src/models/ble_connection_priority.dart';

lib/src/universal_ble.dart

@@ -351,6 +351,30 @@ class UniversalBle {
     );
   }
 
+  /// Requests a connection parameter update for [deviceId].
+  ///
+  /// [priority] controls the BLE connection interval:
+  /// - [BleConnectionPriority.balanced] - default OS behaviour (~30-50 ms interval).
+  /// - [BleConnectionPriority.highPerformance] - low latency, higher power (~7.5-15 ms interval).
+  /// - [BleConnectionPriority.lowPower] - power-optimised (~100-125 ms interval).
+  ///
+  /// Only supported on Android. On all other platforms this throws
+  /// [UniversalBleException] with code [UniversalBleErrorCode.notSupported].
+  ///
+  /// Should be called after a successful connection and MTU negotiation, before
+  /// beginning high-throughput data transfer.
+  static Future<void> requestConnectionPriority(
+    String deviceId,
+    BleConnectionPriority priority, {
+    Duration? timeout,
+  }) async {
+    return await _bleCommandQueue.queueCommand(
+      () => _platform.requestConnectionPriority(deviceId, priority),
+      timeout: timeout,
+      deviceId: deviceId,
+    );
+  }
+
   /// Read the RSSI value of a connected device.
   ///
   /// Returns the current RSSI value in dBm. This value indicates the signal strength

lib/src/universal_ble_linux/universal_ble_linux.dart

@@ -397,6 +397,17 @@ class UniversalBleLinux extends UniversalBlePlatform {
     );
   }
 
+  @override
+  Future<void> requestConnectionPriority(
+    String deviceId,
+    BleConnectionPriority priority,
+  ) {
+    throw UniversalBleException(
+      code: UniversalBleErrorCode.notSupported,
+      message: "requestConnectionPriority is not supported on Linux platform",
+    );
+  }
+
   @override
   Future<int> readRssi(String deviceId) async {
     throw UniversalBleException(

lib/src/universal_ble_pigeon/universal_ble.g.dart

@@ -1256,6 +1256,30 @@ class UniversalBlePlatformChannel {
     }
   }
 
+  Future<void> requestConnectionPriority(String deviceId, int priority) async {
+    final pigeonVar_channelName =
+        'dev.flutter.pigeon.universal_ble.UniversalBlePlatformChannel.requestConnectionPriority$pigeonVar_messageChannelSuffix';
+    final pigeonVar_channel = BasicMessageChannel<Object?>(
+        pigeonVar_channelName,
+        pigeonChannelCodec,
+        binaryMessenger: pigeonVar_binaryMessenger);
+    final Future<Object?> pigeonVar_sendFuture =
+        pigeonVar_channel.send(<Object?>[deviceId, priority]);
+    final pigeonVar_replyList =
+        await pigeonVar_sendFuture as List<Object?>?;
+    if (pigeonVar_replyList == null) {
+      throw _createConnectionError(pigeonVar_channelName);
+    } else if (pigeonVar_replyList.length > 1) {
+      throw PlatformException(
+        code: pigeonVar_replyList[0]! as String,
+        message: pigeonVar_replyList[1] as String?,
+        details: pigeonVar_replyList[2],
+      );
+    } else {
+      return;
+    }
+  }
+
   Future<void> setLogLevel(UniversalBleLogLevel logLevel) async {
     final pigeonVar_channelName =
         'dev.flutter.pigeon.universal_ble.UniversalBlePlatformChannel.setLogLevel$pigeonVar_messageChannelSuffix';

lib/src/universal_ble_pigeon/universal_ble_pigeon_channel.dart

@@ -158,6 +158,14 @@ class UniversalBlePigeonChannel extends UniversalBlePlatform {
   Future<int> readRssi(String deviceId) =>
       _executeWithErrorHandling(() => _channel.readRssi(deviceId));
 
+  @override
+  Future<void> requestConnectionPriority(
+    String deviceId,
+    BleConnectionPriority priority,
+  ) => _executeWithErrorHandling(
+    () => _channel.requestConnectionPriority(deviceId, priority.index),
+  );
+
   @override
   Future<bool> isPaired(String deviceId) =>
       _executeWithErrorHandling(() => _channel.isPaired(deviceId));

lib/src/universal_ble_platform_interface.dart

@@ -97,6 +97,11 @@ abstract class UniversalBlePlatform {
 
   Future<int> readRssi(String deviceId);
 
+  Future<void> requestConnectionPriority(
+    String deviceId,
+    BleConnectionPriority priority,
+  );
+
   Future<bool> isPaired(String deviceId);
 
   Future<bool> pair(String deviceId);

lib/src/universal_ble_web/universal_ble_web.dart

@@ -292,6 +292,18 @@ class UniversalBleWeb extends UniversalBlePlatform {
     );
   }
 
+  /// `Unimplemented`
+  @override
+  Future<void> requestConnectionPriority(
+    String deviceId,
+    BleConnectionPriority priority,
+  ) {
+    throw UniversalBleException(
+      code: UniversalBleErrorCode.notSupported,
+      message: "requestConnectionPriority is not supported on Web platform",
+    );
+  }
+
   /// `Unimplemented`
   @override
   Future<int> readRssi(String deviceId) {