# flutter_bluetooth
**Repository Path**: heytun/flutter_bluetooth
## Basic Information
- **Project Name**: flutter_bluetooth
- **Description**: flutter实现ios、android的蓝牙连接
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-12
- **Last Updated**: 2025-10-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# flutter_bluetooth
#### 介绍
本项目使用 Flutter 实现 iOS 与 Android 的蓝牙功能，聚焦于播放器场景：手机作为发送端，将歌曲文件通过蓝牙发送到目标设备，支持扫描、发现、连接、传输（分片上传）与断开连接。
> 当前实现基于 BLE（GATT）。若需要 Classic Bluetooth（例如 A2DP/OBEX）以实现高质量实时音频流，应在原生层或使用不同插件中补充实现。
#### 特性
- 扫描附近蓝牙设备（支持按 UUID / RSSI 过滤）
- 发现设备服务与特征（GATT）
- 建立连接并管理连接状态
- 通过 GATT 特征分片发送歌曲文件（手机端为发送者，目标设备不保存原始歌曲）
- 连接断开与错误回调处理
- 示例代码与调试步骤
#### 兼容性与依赖
- Flutter：建议使用最新稳定版（推荐 Flutter 3.x / 4.x 可兼容最新 SDK）
- Android minSdkVersion：建议 >= 21
- iOS deployment target：建议 >= 11.0
- 主要插件：flutter_blue_plus（BLE）
#### 安装
1. 在 `pubspec.yaml` 中添加依赖（示例，使用指定版本）：
```yaml
dependencies:
flutter:
sdk: flutter
flutter_blue_plus: ^2.0.0
```
2. 获取依赖：
```bash
flutter pub get
```
#### 权限与平台配置
Android（在 `android/app/src/main/AndroidManifest.xml` 中）示例：
```xml
```
注意：运行时请按 Android 版本请求对应权限（Android 12+ 需要单独请求 BLUETOOTH_CONNECT/SCAN/ADVERTISE）。
iOS（在 `ios/Runner/Info.plist` 中）需要添加使用说明：
- NSBluetoothAlwaysUsageDescription
- NSBluetoothPeripheralUsageDescription
- NSMicrophoneUsageDescription（如需录音/音频相关权限）
#### 快速开始（示例代码）
下面示例使用 `flutter_blue_plus` 展示扫描、连接、发现服务与通过可写特征分片发送文件的基本流程（示例为简化版）：
```dart
import 'dart:io';
import 'package:flutter_blue_plus/flutter_blue_plus.dart';
class BluetoothSender {
final FlutterBluePlus _ble = FlutterBluePlus.instance;
BluetoothDevice? _device;
BluetoothCharacteristic? _writeChar;
Future startScan(Function(ScanResult) onFound) async {
_ble.startScan(timeout: const Duration(seconds: 5));
_ble.scanResults.listen((results) {
for (var r in results) onFound(r);
});
}
Future connect(String deviceId) async {
_device = await _ble.connectToDevice(id: DeviceIdentifier(deviceId));
await Future.delayed(const Duration(seconds: 1));
await discoverServices();
}
Future discoverServices() async {
if (_device == null) throw Exception('Device not connected');
final services = await _device!.discoverServices();
for (var s in services) {
for (var c in s.characteristics) {
if (c.properties.write || c.properties.writeWithoutResponse) {
_writeChar = c;
return;
}
}
}
if (_writeChar == null) throw Exception('No writable characteristic found');
}
Future sendFile(String path, {int mtu = 180}) async {
if (_writeChar == null) throw Exception('No write characteristic');
final file = File(path);
final bytes = await file.readAsBytes();
final chunkSize = mtu - 3; // 留出 ATT overhead
for (var offset = 0; offset < bytes.length; offset += chunkSize) {
final end = (offset + chunkSize < bytes.length) ? offset + chunkSize : bytes.length;
final chunk = bytes.sublist(offset, end);
await _writeChar!.write(chunk, withoutResponse: true);
await Future.delayed(const Duration(milliseconds: 20));
}
}
Future disconnect() async {
if (_device != null) {
await _device!.disconnect();
_device = null;
_writeChar = null;
}
}
}
```
#### 常见问题 — 高质量实时音频 FAQ
Q: 普通 3 分钟左右的歌曲是否算“高质量实时音频”？
A: 不是。3 分钟左右的歌曲通常是一个完整的音频文件，它属于“文件传输”场景（phone → device），可以通过 BLE 分片上传。"高质量实时音频" 指的是持续的、低延迟且高比特率的音频流（例如在手机与蓝牙耳机之间实时播放音乐，通常使用 A2DP/Classic Bluetooth，采样率 44.1kHz/16-bit 或更高、低延迟），需要更高带宽和原生支持，BLE 并不适合此类实时高质量音频流。
#### 运行与调试
1. 获取依赖：
```bash
flutter pub get
```
2. 列出设备并选择真机运行：
```bash
flutter devices
flutter run -d
```
3. Android: 如需在设备上直接授予权限（调试用）：
```bash
adb shell pm grant your.package.name android.permission.BLUETOOTH_CONNECT
adb shell pm grant your.package.name android.permission.BLUETOOTH_SCAN
adb shell pm grant your.package.name android.permission.ACCESS_FINE_LOCATION
```
注意：Android 模拟器通常不支持蓝牙，iOS 必须在真机上测试蓝牙功能。
#### 贡献
欢迎提交 issue 与 PR：Fork → 新建分支 → 提交 → 发起 PR。
#### 作者与联系方式
- 作者：阿威
- 联系方式：309243326
#### 许可证
本项目遵循 Apache License 2.0（见 LICENSE）。
如何运行 Demo（iOS 真机）
1. 在项目根运行依赖获取：
```bash
flutter pub get
```
2. 在 `ios/` 目录下安装 CocoaPods（如需要）：
```bash
cd ios; pod install; cd ..
```
3. 连接 iOS 真机并运行：
```bash
flutter devices
flutter run -d
```
调试提示：
- 如果遇到 CocoaPods 相关错误，请在 `ios/` 文件夹执行 `pod repo update` 后重试。
- 确保在 Xcode 中选中合适的签名（Signing）配置，或先使用 `flutter run` 让 Flutter 尝试处理签名。
重要提示 — `pod` 在 Windows 上不可用
如果你在 Windows 上执行 `pod install` 并看到类似：
```
pod : 无法将“pod”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
```
这是因为 CocoaPods 是 macOS 上的工具（基于 Ruby 的 gem），只能在 macOS（或 macOS CI）上安装和运行。Windows 环境不能直接运行 `pod`、也无法进行 iOS 的 Xcode 构建工作。
可行的解决办法：
1) 在 macOS 机器上执行（推荐）
1. 安装 Homebrew（如果还没安装）：
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. 安装 CocoaPods（或使用 gem）：
```bash
brew install cocoapods
# 或者
sudo gem install cocoapods
```
3. 进入项目 ios 目录并安装依赖：
```bash
cd ios
pod install
cd ..
```
2) 使用 macOS CI / 云 Mac 服务
如果你没有本地 macOS，可以使用 GitHub Actions (macOS runner)、Codemagic、Bitrise、MacStadium 等进行构建与 `pod install`。
3) 远程 macOS
把仓库推到远端（或使用远程 Mac），在那台 macOS 上运行 `pod install` 并部署或调试。
不可行的方法（注意）
- 在 Windows 上尝试用 WSL 运行 `pod` 并不可行用于 iOS 构建，因为 iOS 构建链依赖 Xcode/macOS。
如果你希望，我可以：
- 在 README 中加入一段更详细的 macOS/CocoaPods 安装说明（已添加到本文件）。
- 帮你生成一个 GitHub Actions 示例 workflow 来在 macOS runner 上自动执行 `flutter pub get` 和 `pod install`，并进行构建（如果你想要 CI 示例，请告诉我）。
下一步建议：
- 添加状态管理（Provider/Bloc）以更好地组织 UI 与数据流。
- 把 demo bytes 替换为文件选择（`file_picker`）并在 README 中列出相关权限。
- 如果要支持 Android，请告知，我会把 Android 实现补上并调整权限说明。