蓝牙 BLE 与外设集成

Peripheral（外设，如手环）
└── Service（服务，UUID 标识一类功能）
    ├── Characteristic（特征，实际读写的数据点）
    │   ├── Value（值）
    │   ├── Properties（read/write/notify/indicate）
    │   └── Descriptor（描述符，如 CCCD 通知开关）
    └── Characteristic ...

import 'package:flutter_blue_plus/flutter_blue_plus.dart';

// 检查蓝牙状态
if (await FlutterBluePlus.isSupported == false) {
  throw Exception('设备不支持蓝牙');
}

// 开始扫描（可按 serviceUuid 过滤，避免扫出一堆无关设备）
await FlutterBluePlus.startScan(
  withServices: [Guid('0000180d-0000-1000-8000-00805f9b34fb')],
  timeout: const Duration(seconds: 15),
);

// 监听扫描结果
FlutterBluePlus.scanResults.listen((results) {
  for (final r in results) {
    print('${r.device.platformName}  RSSI=${r.rssi}  id=${r.device.remoteId}');
  }
});

// 记得停止扫描，否则会持续耗电
await FlutterBluePlus.stopScan();

final device = result.device;
await device.connect(timeout: const Duration(seconds: 15));

// 监听连接状态
device.connectionState.listen((state) {
  switch (state) {
    case BluetoothConnectionState.connected:
      print('已连接');
      break;
    case BluetoothConnectionState.disconnected:
      print('已断开');
      break;
    default:
      break;
  }
});

// 发现服务
final services = await device.discoverServices();
for (final s in services) {
  print('Service: ${s.uuid}');
  for (final c in s.characteristics) {
    print('  Char: ${c.uuid}  ${c.properties}');
  }
}

// 定位目标特征
final service = services.firstWhere(
  (s) => s.uuid == Guid('0000ffe0-0000-1000-8000-00805f9b34fb'),
);
final writeChar = service.characteristics.firstWhere(
  (c) => c.uuid == Guid('0000ffe1-0000-1000-8000-00805f9b34fb'),
);

// 读
final value = await writeChar.read();
print('读取到: ${value}');

// 写（有无响应两种）
await writeChar.write([0x01, 0x02], withoutResponse: false);

// 订阅通知
await writeChar.setNotifyValue(true);
writeChar.onValueReceived.listen((data) {
  print('收到通知: ${data.length} 字节');
});

// Android 支持主动请求 MTU（iOS 由系统自动协商，不可主动设置）
final mtu = await device.requestMtu(512);
print('协商后 MTU: $mtu');   // 实际值由外设能力决定，通常 247 或 512

// 有效载荷 = MTU - 3
final payloadSize = mtu - 3;

Future<void> sendLargeData(BluetoothCharacteristic char, Uint8List data) async {
  final chunkSize = device.mtuNow - 3;
  final total = (data.length / chunkSize).ceil();

  for (var i = 0; i < total; i++) {
    final start = i * chunkSize;
    final end = (start + chunkSize).clamp(0, data.length);

    // 包头：2 字节序号 + 1 字节总片数 + 数据
    final packet = Uint8List(3 + (end - start));
    packet[0] = (i >> 8) & 0xFF;
    packet[1] = i & 0xFF;
    packet[2] = total;
    packet.setRange(3, packet.length, data, start);

    await char.write(packet, withoutResponse: false);
  }
}

<!-- android/app/src/main/AndroidManifest.xml -->
<!-- Android 12+ 的新权限模型 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- Android 11 及以下 -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />

// 运行时申请权限（配合 permission_handler）
final status = await [
  Permission.bluetoothScan,
  Permission.bluetoothConnect,
].request();

<!-- ios/Runner/Info.plist -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙连接您的智能设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙连接您的智能设备</string>

// 申请忽略电池优化（Android）
final status = await Permission.ignoreBatteryOptimizations.request();

disconnected → scanning → connecting → connected → discovering
     ↑                                              ↓
     └──────────── reconnecting ←────────────── disconnected

Future<void> connectWithRetry(BluetoothDevice device) async {
  var attempt = 0;
  while (attempt < 5) {
    try {
      await device.connect(timeout: const Duration(seconds: 10));
      await device.discoverServices();
      _resubscribeNotifications();   // 重连后必须重新订阅通知
      return;
    } catch (e) {
      attempt++;
      // 指数退避：1s, 2s, 4s, 8s, 16s
      await Future.delayed(Duration(seconds: 1 << (attempt - 1)));
    }
  }
  throw Exception('重连失败，已达最大重试次数');
}

// OTA 传输：等 ACK 再发下一片
Future<void> sendFirmware(BluetoothCharacteristic char, Uint8List fw) async {
  final chunk = device.mtuNow - 3;
  for (var offset = 0; offset < fw.length; offset += chunk) {
    final end = (offset + chunk).clamp(0, fw.length);
    await char.write(fw.sublist(offset, end), withoutResponse: false);
    // 等待外设回 ACK（超时重发）
    await _waitForAck(timeout: const Duration(seconds: 2));
    _reportProgress(end / fw.length);
  }
}