模板版本: v0.0.1
fluttertpc_flutter_blue_plus
本项目基于 flutter_blue_plus 开发。
1. 安装与使用
1.1 安装方式
进入到工程目录并在 pubspec.yaml 中添加以下依赖：
pubspec.yaml
...
dependencies:
flutter_blue_plus_ohos:
git:
url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_blue_plus.git
path: ohos
...
执行命令
flutter pub get
1.2 使用案例
使用案例详见 ohos/example
2. 约束与限制
2.1 兼容性
在以下版本中已测试通过
- Flutter: 3.7.12-ohos-1.0.6; SDK: 5.0.0(12); IDE: DevEco Studio: 5.0.13.200; ROM: 5.1.0.120 SP3;
- Flutter: 3.22.1-ohos-1.0.1; SDK: 5.0.0(12); IDE: DevEco Studio: 5.0.13.200; ROM: 5.1.0.120 SP3;
2.2 权限要求
2.2.1 在 entry 目录下的module.json5中添加权限
打开 entry/src/main/module.json5，添加：
...
"requestPermissions": [
{
"name": "ohos.permission.ACCESS_BLUETOOTH",
"reason": "$string:bluetooth_reason",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when":"inuse"
}
},
{
"name": "ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC"
}
]
2.2.2 在 entry 目录下添加申请以上权限的原因
打开 entry/src/main/resources/base/element/string.json，添加：
...
{
"string": [
{
"name": "bluetooth_reason",
"value": "使用蓝牙"
}
]
}
3. API
"ohos Support"列为 yes 表示 ohos 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
FlutterBluePlus API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| setLogLevel | 配置插件日志级别 | function | LogLevel level, {bool color = true} | Future | yes |
| setOptions | 设置可配置的蓝牙选项 | function | {bool showPowerAlert = true, bool restoreState = false} | Future | yes |
| isSupported | 检查设备是否支持蓝牙 | function | / | Future | yes |
| turnOn | 打开蓝牙适配器 | function | {int timeout = 60} | Future | yes |
| adapterStateNow | 蓝牙适配器的当前状态 | function | / | BluetoothAdapterState | no |
| adapterState | 蓝牙适配器开关状态的流 | function | / | Stream | yes |
| startScan | 开始扫描 Ble 设备 | function | {List withServices = const [], List withRemoteIds = const [], List withNames = const [], List withKeywords = const [], List withMsd = const [], List withServiceData = const [], Duration? timeout, Duration? removeIfGone, bool continuousUpdates = false, int continuousDivisor = 1, bool oneByOne = false, bool androidLegacy = false, AndroidScanMode androidScanMode = AndroidScanMode.lowLatency, bool androidUsesFineLocation = false} | Future | yes |
| stopScan | 停止现有的 Ble 设备扫描 | function | / | Future | yes |
| onScanResults | 实时扫描结果的流 | function | / | Stream<List> | yes |
| scanResults | 实时扫描结果或之前结果的流 | function | / | Stream<List> | yes |
| lastScanResults | 最近的扫描结果 | function | / | List | yes |
| isScanning | 当前扫描状态的流 | function | / | Stream | yes |
| isScanningNow | 是否正在运行扫描 | function | / | bool | yes |
| connectedDevices | 连接到您应用的设备列表 | function | / | List | yes |
| systemDevices | 连接到系统的设备列表（即使由其他应用连接） | function | List withServices | Future<List> | yes |
| getPhySupport | 获取支持的蓝牙 phy 编码 | function | / | Future | no |
| addPersistentDeviceId | 添加持久化存储虚拟随机地址 api 16+ | function | String remote_id | Future | yes |
| deletePersistentDeviceId | 删除一个持久化的蓝牙虚拟设备地址。api 16+ | function | String remote_id | Future | yes |
| getPersistentDeviceIds | 获取该应用持久化过的蓝牙虚拟设备地址。api 16+ | function | / | Future<List> | yes |
| isValidRandomDeviceId | 判断对端蓝牙设备的虚拟地址是否是有效。 api 16+ | function | String remote_id | Future | yes |
FlutterBluePlus Events API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| events.onConnectionStateChanged | 所有设备连接状态变化的流 | function | / | Stream | yes |
| events.onMtuChanged | 所有设备 MTU 变化的流 | function | / | Stream | yes |
| events.onReadRssi | 所有设备 RSSI 读取的流 | function | / | Stream | yes |
| events.onServicesReset | 所有设备服务重置的流 | function | / | Stream | no |
| events.onDiscoveredServices | 所有设备服务发现的流 | function | / | Stream | yes |
| events.onCharacteristicReceived | 所有设备特征值读取的流 | function | / | Stream | yes |
| events.onCharacteristicWritten | 所有设备特征值写入的流 | function | / | Stream | yes |
| events.onDescriptorRead | 所有设备描述符读取的流 | function | / | Stream | yes |
| events.onDescriptorWritten | 所有设备描述符写入的流 | function | / | Stream | yes |
| events.onBondStateChanged | 所有设备（Android）绑定状态变化的流 | function | / | Stream | no |
| events.onNameChanged | 所有设备（iOS）名称变化的流 | function | / | Stream | no |
BluetoothDevice API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| platformName | 获取设备的平台首选名称 | function | / | String | yes |
| advName | 获取扫描期间发现的设备广播名称 | function | / | String | yes |
| connect | 建立与设备的连接 | function | {Duration timeout = 35, int? mtu = 512, bool autoConnect = false} | Future | yes |
| disconnect | 断开与设备的连接 | function | {int timeout = 35, bool queue = true, int androidDelay = 2000} | Future | yes |
| isConnected | 当前设备是否已连接到您的应用 | function | / | bool | yes |
| isDisconnected | 当前设备是否已断开与您的应用的连接 | function | / | bool | yes |
| connectionState | 蓝牙设备连接状态变化的流 | function | / | Stream | yes |
| discoverServices | 发现设备的服务列表 | function | {bool subscribeToServicesChanged = true, int timeout = 15} | Future<List> | yes |
| servicesList | 获取当前可用的服务列表 | function | / | List | yes |
| onServicesReset | 服务发生变化，需要重新发现服务 | function | / | Stream | yes |
| mtu | 获取或监听当前 MTU 值及其变化 | function | / | Stream | yes |
| mtuNow | 获取当前的 MTU 值 | function | / | int | yes |
| readRssi | 从已连接设备读取 RSSI 值 | function | {int timeout = 15} | Future | yes |
| requestMtu | 请求更改设备的 MTU 值 | function | {int desiredMtu, double predelay = 0.35, int timeout = 15} | Future | yes |
| requestConnectionPriority | 请求建立高优先级、低延迟的连接 | function | required ConnectionPriority connectionPriorityRequest | Future | no |
| bondState | 监听设备绑定状态的变化（对 Android 有用） | function | / | Stream | no |
| createBond | 强制显示系统配对对话框（如需要） | function | {int timeout = 90} | Future | no |
| removeBond | 移除设备的蓝牙绑定 | function | {int timeout = 30} | Future | no |
| setPreferredPhy | 设置连接的首选 RX 和 TX 的 PHY 及其选项 | function | required int txPhy, required int rxPhy, required PhyCoding option | Future | no |
| clearGattCache | 清除 Android 上服务发现结果的缓存 | function | / | Future | no |
BluetoothCharacteristic API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| uuid | 获取特征值的 UUID | function | / | Guid | yes |
| device | 获取关联的蓝牙设备 | function | / | BluetoothDevice | yes |
| properties | 获取特征值的属性 | function | / | CharacteristicProperties | yes |
| descriptors | 获取特征值的描述符列表 | function | / | List | yes |
| lastValue | 最近一次获取的特征值 | function | / | List | yes |
| lastValueStream | 特征值接收流 + 写入流 | function | / | Stream<List> | yes |
| onValueReceived | 从设备接收特征值更新的流 | function | / | Stream<List> | yes |
| read | 读取特征值的内容 | function | {int timeout = 15} | Future<List> | yes |
| write | 写入特征值的内容 | function | List value, {bool withoutResponse = false, bool allowLongWrite = false, int timeout = 15} | Future | yes |
| setNotifyValue | 设置特征值的通知或指示 | function | bool notify, {int timeout = 15, bool forceIndications = false} | Future | yes |
| isNotifying | 当前是否已启用通知或指示 | function | / | bool | yes |
BluetoothDescriptor API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| uuid | 获取描述符的 UUID | function | / | Guid | yes |
| device | 获取关联的蓝牙设备 | function | / | BluetoothDevice | yes |
| lastValue | 最近一次获取的描述符值 | function | / | List | yes |
| lastValueStream | 描述符值接收流 + 写入流 | function | / | Stream<List> | yes |
| onValueReceived | 描述符值读取和写入的流 | function | / | Stream<List> | yes |
| read | 读取描述符的内容 | function | {int timeout = 15} | Future<List> | yes |
| write | 写入描述符的内容 | function | List value, {int timeout = 15} | Future | yes |
4. 遗留问题
5. 其他
6. 开源协议
本项目基于 The BSD-3-Clause (license) ，请自由地享受和参与开源。