feat(dfu): add connection and MTU preflight checks

lib/controller/bluetooth.dart

@@ -299,11 +299,20 @@ class BluetoothController {
 
   Future<Result<void>> requestMtu(String deviceId,
       {int mtu = defaultMtu}) async {
+    final result = await requestMtuAndGetValue(deviceId, mtu: mtu);
+    if (result.isErr()) {
+      return bail(result.unwrapErr());
+    }
+    return Ok(null);
+  }
+
+  Future<Result<int>> requestMtuAndGetValue(String deviceId,
+      {int mtu = defaultMtu}) async {
     try {
       final negotiatedMtu = await _ble.requestMtu(deviceId: deviceId, mtu: mtu);
       log.info(
           'MTU negotiated for $deviceId: requested $mtu, got $negotiatedMtu');
-      return Ok(null);
+      return Ok(negotiatedMtu);
     } catch (e) {
       return bail('Error requesting MTU $mtu for $deviceId: $e');
     }

lib/model/shifter_types.dart

@@ -24,6 +24,10 @@ const int universalShifterDfuOpcodeAbort = 0x03;
 
 const int universalShifterDfuFrameSizeBytes = 64;
 const int universalShifterDfuFramePayloadSizeBytes = 63;
+const int universalShifterAttWriteOverheadBytes = 3;
+const int universalShifterDfuMinimumMtu =
+    universalShifterDfuFrameSizeBytes + universalShifterAttWriteOverheadBytes;
+const int universalShifterDfuPreferredMtu = 128;
 
 const int universalShifterDfuFlagEncrypted = 0x01;
 const int universalShifterDfuFlagSigned = 0x02;
@@ -107,6 +111,61 @@ class DfuUpdateProgress {
       state == DfuUpdateState.failed;
 }
 
+enum DfuPreflightFailureReason {
+  deviceNotConnected,
+  wrongConnectedDevice,
+  mtuRequestFailed,
+  mtuTooLow,
+}
+
+class DfuPreflightResult {
+  const DfuPreflightResult._({
+    required this.requestedMtu,
+    required this.requiredMtu,
+    required this.negotiatedMtu,
+    required this.failureReason,
+    required this.message,
+  });
+
+  final int requestedMtu;
+  final int requiredMtu;
+  final int? negotiatedMtu;
+  final DfuPreflightFailureReason? failureReason;
+  final String? message;
+
+  bool get canStart => failureReason == null;
+
+  static DfuPreflightResult ready({
+    required int requestedMtu,
+    required int negotiatedMtu,
+    int requiredMtu = universalShifterDfuMinimumMtu,
+  }) {
+    return DfuPreflightResult._(
+      requestedMtu: requestedMtu,
+      requiredMtu: requiredMtu,
+      negotiatedMtu: negotiatedMtu,
+      failureReason: null,
+      message: null,
+    );
+  }
+
+  static DfuPreflightResult failed({
+    required int requestedMtu,
+    required DfuPreflightFailureReason failureReason,
+    required String message,
+    int requiredMtu = universalShifterDfuMinimumMtu,
+    int? negotiatedMtu,
+  }) {
+    return DfuPreflightResult._(
+      requestedMtu: requestedMtu,
+      requiredMtu: requiredMtu,
+      negotiatedMtu: negotiatedMtu,
+      failureReason: failureReason,
+      message: message,
+    );
+  }
+}
+
 class ShifterErrorInfo {
   const ShifterErrorInfo({
     required this.code,

lib/service/shifter_service.dart

@@ -6,12 +6,30 @@ import 'package:anyhow/anyhow.dart';
 
 class ShifterService {
   ShifterService({
-    required BluetoothController bluetooth,
+    BluetoothController? bluetooth,
     required this.buttonDeviceId,
-  }) : _bluetooth = bluetooth;
+    DfuPreflightBluetoothAdapter? dfuPreflightBluetooth,
+  })  : _bluetooth = bluetooth,
+        _dfuPreflightBluetooth =
+            dfuPreflightBluetooth ?? _BluetoothDfuPreflightAdapter(bluetooth!) {
+    if (bluetooth == null && dfuPreflightBluetooth == null) {
+      throw ArgumentError(
+        'Either bluetooth or dfuPreflightBluetooth must be provided.',
+      );
+    }
+  }
 
-  final BluetoothController _bluetooth;
+  final BluetoothController? _bluetooth;
   final String buttonDeviceId;
+  final DfuPreflightBluetoothAdapter _dfuPreflightBluetooth;
+
+  BluetoothController get _requireBluetooth {
+    final bluetooth = _bluetooth;
+    if (bluetooth == null) {
+      throw StateError('Bluetooth controller is not available.');
+    }
+    return bluetooth;
+  }
 
   final StreamController<CentralStatus> _statusController =
       StreamController<CentralStatus>.broadcast();
@@ -28,7 +46,7 @@ class ShifterService {
   Future<Result<void>> writeConnectToAddress(String bikeDeviceId) async {
     try {
       final payload = parseMacToLittleEndianBytes(bikeDeviceId);
-      return _bluetooth.writeCharacteristic(
+      return _requireBluetooth.writeCharacteristic(
         buttonDeviceId,
         universalShifterControlServiceUuid,
         universalShifterConnectToAddrCharacteristicUuid,
@@ -42,7 +60,7 @@ class ShifterService {
   }
 
   Future<Result<void>> writeCommand(UniversalShifterCommand command) {
-    return _bluetooth.writeCharacteristic(
+    return _requireBluetooth.writeCharacteristic(
       buttonDeviceId,
       universalShifterControlServiceUuid,
       universalShifterCommandCharacteristicUuid,
@@ -59,7 +77,7 @@ class ShifterService {
   }
 
   Future<Result<GearRatiosData>> readGearRatios() async {
-    final readRes = await _bluetooth.readCharacteristic(
+    final readRes = await _requireBluetooth.readCharacteristic(
       buttonDeviceId,
       universalShifterControlServiceUuid,
       universalShifterGearRatiosCharacteristicUuid,
@@ -106,8 +124,10 @@ class ShifterService {
   }
 
   Future<Result<void>> writeGearRatios(GearRatiosData data) async {
-    final mtuResult =
-        await _bluetooth.requestMtu(buttonDeviceId, mtu: _gearRatioWriteMtu);
+    final mtuResult = await _requireBluetooth.requestMtu(
+      buttonDeviceId,
+      mtu: _gearRatioWriteMtu,
+    );
     if (mtuResult.isErr()) {
       return bail(
           'Could not request MTU before writing gear ratios: ${mtuResult.unwrapErr()}');
@@ -124,7 +144,7 @@ class ShifterService {
     payload[_defaultGearIndexOffset] =
         limit == 0 ? 0 : data.defaultGearIndex.clamp(0, limit - 1).toInt();
 
-    return _bluetooth.writeCharacteristic(
+    return _requireBluetooth.writeCharacteristic(
       buttonDeviceId,
       universalShifterControlServiceUuid,
       universalShifterGearRatiosCharacteristicUuid,
@@ -133,7 +153,7 @@ class ShifterService {
   }
 
   Future<Result<CentralStatus>> readStatus() async {
-    final readRes = await _bluetooth.readCharacteristic(
+    final readRes = await _requireBluetooth.readCharacteristic(
       buttonDeviceId,
       universalShifterControlServiceUuid,
       universalShifterStatusCharacteristicUuid,
@@ -149,12 +169,78 @@ class ShifterService {
     }
   }
 
+  Future<Result<DfuPreflightResult>> runDfuPreflight({
+    int requestedMtu = universalShifterDfuPreferredMtu,
+  }) async {
+    final currentConnection = _dfuPreflightBluetooth.currentConnectionState;
+    final connectionStatus = currentConnection.$1;
+    final connectedDeviceId = currentConnection.$2;
+
+    if (connectionStatus != ConnectionStatus.connected ||
+        connectedDeviceId == null) {
+      return Ok(
+        DfuPreflightResult.failed(
+          requestedMtu: requestedMtu,
+          failureReason: DfuPreflightFailureReason.deviceNotConnected,
+          message:
+              'No button connection is active. Connect the target button, then retry the firmware update.',
+        ),
+      );
+    }
+
+    if (connectedDeviceId != buttonDeviceId) {
+      return Ok(
+        DfuPreflightResult.failed(
+          requestedMtu: requestedMtu,
+          failureReason: DfuPreflightFailureReason.wrongConnectedDevice,
+          message:
+              'Connected to a different button ($connectedDeviceId). Reconnect to $buttonDeviceId before starting the firmware update.',
+        ),
+      );
+    }
+
+    final mtuResult = await _dfuPreflightBluetooth.requestMtuAndGetValue(
+      buttonDeviceId,
+      mtu: requestedMtu,
+    );
+    if (mtuResult.isErr()) {
+      return Ok(
+        DfuPreflightResult.failed(
+          requestedMtu: requestedMtu,
+          failureReason: DfuPreflightFailureReason.mtuRequestFailed,
+          message:
+              'Could not negotiate BLE MTU for DFU. Move closer to the button and retry. Details: ${mtuResult.unwrapErr()}',
+        ),
+      );
+    }
+
+    final negotiatedMtu = mtuResult.unwrap();
+    if (negotiatedMtu < universalShifterDfuMinimumMtu) {
+      return Ok(
+        DfuPreflightResult.failed(
+          requestedMtu: requestedMtu,
+          negotiatedMtu: negotiatedMtu,
+          failureReason: DfuPreflightFailureReason.mtuTooLow,
+          message:
+              'Negotiated MTU $negotiatedMtu is too small for 64-byte DFU frames. Need at least $universalShifterDfuMinimumMtu bytes MTU (64-byte frame + $universalShifterAttWriteOverheadBytes-byte ATT overhead). Reconnect and retry.',
+        ),
+      );
+    }
+
+    return Ok(
+      DfuPreflightResult.ready(
+        requestedMtu: requestedMtu,
+        negotiatedMtu: negotiatedMtu,
+      ),
+    );
+  }
+
   void startStatusNotifications() {
     if (_statusSubscription != null) {
       return;
     }
 
-    _statusSubscription = _bluetooth
+    _statusSubscription = _requireBluetooth
         .subscribeToCharacteristic(
       buttonDeviceId,
       universalShifterControlServiceUuid,
@@ -202,6 +288,32 @@ class ShifterService {
   }
 }
 
+abstract interface class DfuPreflightBluetoothAdapter {
+  (ConnectionStatus, String?) get currentConnectionState;
+  Future<Result<int>> requestMtuAndGetValue(
+    String deviceId, {
+    required int mtu,
+  });
+}
+
+class _BluetoothDfuPreflightAdapter implements DfuPreflightBluetoothAdapter {
+  const _BluetoothDfuPreflightAdapter(this._bluetooth);
+
+  final BluetoothController _bluetooth;
+
+  @override
+  (ConnectionStatus, String?) get currentConnectionState =>
+      _bluetooth.currentConnectionState;
+
+  @override
+  Future<Result<int>> requestMtuAndGetValue(
+    String deviceId, {
+    required int mtu,
+  }) {
+    return _bluetooth.requestMtuAndGetValue(deviceId, mtu: mtu);
+  }
+}
+
 class GearRatiosData {
   const GearRatiosData({
     required this.ratios,