From 3170b4b77bb9377b6dd35e29f007fb300891706c Mon Sep 17 00:00:00 2001
From: Foti Dim <foti@navideck.com>
Date: Mon, 17 Feb 2025 08:20:43 +0100
Subject: [PATCH] Improve requestMTU() docs (#140)

* Improve requestMTU() docs

* Update Linux info
---
 README.md                  | 28 ++++++++++++++++++++++++++++
 lib/src/universal_ble.dart |  3 ++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4c51a79..68d9be5 100644
--- a/README.md
+++ b/README.md
@@ -241,6 +241,34 @@ UniversalBle.enableBluetooth();
 UniversalBle.disableBluetooth();
 ```
 
+### Request MTU
+
+This method will **attempt** to set the MTU (Maximum Transmission Unit) but it is not guaranteed to succeed due to platform limitations. It will always return the current MTU.
+
+```dart
+int mtu = await UniversalBle.requestMtu(widget.deviceId, 247);
+```
+
+#### Platform Limitations
+
+On most platforms, the MTU can only be queried but not manually set:
+
+- **iOS/macOS**: System automatically sets MTU to 185 bytes maximum
+- **Android 14+**: System automatically sets MTU to 517 bytes for the first GATT client
+- **Windows**: MTU can only be queried
+- **Linux**: MTU can only be queried
+- **Web**: No mechanism to query or modify MTU size
+
+#### Best Practices
+
+When developing cross-platform BLE applications and devices:
+
+- Design for default MTU size (23 bytes) as default
+- Dynamically adapt to use larger packet sizes when the system provides them
+- Take advantage of the increased throughput when available without requiring it
+- Implement data fragmentation for larger transfers
+- Handle platform-specific MTU size based on current value
+
 ## Command Queue
 
 By default, all commands are executed in a global queue (`QueueType.global`), with each command waiting for the previous one to finish.
diff --git a/lib/src/universal_ble.dart b/lib/src/universal_ble.dart
index 9e30020..17e537c 100644
--- a/lib/src/universal_ble.dart
+++ b/lib/src/universal_ble.dart
@@ -208,7 +208,8 @@ class UniversalBle {
   }
 
   /// Request MTU value.
-  /// `requestMtu` is not supported on `Linux` and `Web.
+  /// It will **attempt** to set the MTU (Maximum Transmission Unit) but it is not guaranteed to succeed due to platform limitations.
+  /// It will always return the current MTU.
   static Future<int> requestMtu(String deviceId, int expectedMtu) async {
     return await _bleCommandQueue.queueCommand(
       () => _platform.requestMtu(deviceId, expectedMtu),