Template version: v0.0.1
fluttertpc_flutter_blue_plus
This project is based on flutter_blue_plus.
1. Installation and Usage
1.1 Installation
Go to the project directory and add the following dependencies in pubspec.yaml
pubspec.yaml
...
dependencies:
flutter_blue_plus_ohos:
git:
url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_blue_plus.git
path: ohos
...
Execute Command
flutter pub get
1.2 Usage
For use cases ohos/example
2. Constraints
2.1 Compatibility
This document is verified based on the following versions:
- 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 Permission Requirements
2.2.1 Add permissions to the module.json5 file in the entry directory.
Open entry/src/main/module.json5 and add the following information:
...
"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 Add the reason for applying for the preceding permission to the entry directory.
Open entry/src/main/resources/base/element/string.json and add the following information:
...
{
"string": [
{
"name": "bluetooth_reason",
"value": "bluetooth_reason"
}
]
}
3. API
If the value of **ohos Support** is **yes**, it means that the ohos platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android.
FlutterBluePlus API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| setLogLevel | Configure plugin log level | function | LogLevel level, {bool color = true} | Future | yes |
| setOptions | Set configurable Bluetooth options | function | {bool showPowerAlert = true, bool restoreState = false} | Future | yes |
| isSupported | Check if device supports Bluetooth | function | / | Future | yes |
| turnOn | Enable Bluetooth adapter | function | {int timeout = 60} | Future | yes |
| adapterStateNow | Current state of Bluetooth adapter | function | / | BluetoothAdapterState | no |
| adapterState | Stream for Bluetooth adapter power state | function | / | Stream | yes |
| startScan | Start scanning for BLE devices | 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 | Stop existing BLE device scan | function | / | Future | yes |
| onScanResults | Stream for real-time scan results | function | / | Stream<List> | yes |
| scanResults | Stream for real-time or previous scan results | function | / | Stream<List> | yes |
| lastScanResults | Most recent scan results | function | / | List | yes |
| isScanning | Stream for current scanning status | function | / | Stream | yes |
| isScanningNow | Check if scanning is currently active | function | / | bool | yes |
| connectedDevices | List of devices connected to your application | function | / | List | yes |
| systemDevices | List of system-connected devices (including those connected by other apps) | function | List withServices | Future<List> | yes |
| getPhySupport | Get supported Bluetooth PHY coding | function | / | Future | no |
| addPersistentDeviceId | Add a persistent storage virtual random address (API 16+) | function | String remote_id | Future | yes |
| deletePersistentDeviceId | Delete a persistently stored Bluetooth virtual device address (API 16+) | function | String remote_id | Future | yes |
| getPersistentDeviceIds | Get Bluetooth virtual device addresses persisted by this application (API 16+) | function | / | Future<List> | yes |
| isValidRandomDeviceId | Check if the remote Bluetooth device's virtual address is valid (API 16+) | function | String remote_id | Future | yes |
FlutterBluePlus Events API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| events.onConnectionStateChanged | Stream for connection state changes of all devices | function | / | Stream | yes |
| events.onMtuChanged | Stream for MTU changes of all devices | function | / | Stream | yes |
| events.onReadRssi | Stream for RSSI readings of all devices | function | / | Stream | yes |
| events.onServicesReset | Stream for service resets of all devices | function | / | Stream | no |
| events.onDiscoveredServices | Stream for service discoveries of all devices | function | / | Stream | yes |
| events.onCharacteristicReceived | Stream for characteristic readings of all devices | function | / | Stream | yes |
| events.onCharacteristicWritten | Stream for characteristic writings of all devices | function | / | Stream | yes |
| events.onDescriptorRead | Stream for descriptor readings of all devices | function | / | Stream | yes |
| events.onDescriptorWritten | Stream for descriptor writings of all devices | function | / | Stream | yes |
| events.onBondStateChanged | Stream for bond state changes of all devices (Android) | function | / | Stream | no |
| events.onNameChanged | Stream for name changes of all devices (iOS) | function | / | Stream | no |
BluetoothDevice API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| platformName | Get device's platform-preferred name | function | / | String | yes |
| advName | Get device's advertising name discovered during scanning | function | / | String | yes |
| connect | Establish connection with device | function | {Duration timeout = 35, int? mtu = 512, bool autoConnect = false} | Future | yes |
| disconnect | Disconnect from device | function | {int timeout = 35, bool queue = true, int androidDelay = 2000} | Future | yes |
| isConnected | Check if device is connected to your application | function | / | bool | yes |
| isDisconnected | Check if device is disconnected from your application | function | / | bool | yes |
| connectionState | Stream for Bluetooth device connection state changes | function | / | Stream | yes |
| discoverServices | Discover device's service list | function | {bool subscribeToServicesChanged = true, int timeout = 15} | Future<List> | yes |
| servicesList | Get current available service list | function | / | List | yes |
| onServicesReset | Service changes require rediscovery | function | / | Stream | yes |
| mtu | Get or monitor current MTU value and changes | function | / | Stream | yes |
| mtuNow | Get current MTU value | function | / | int | yes |
| readRssi | Read RSSI value from connected device | function | {int timeout = 15} | Future | yes |
| requestMtu | Request to change device's MTU value | function | {int desiredMtu, double predelay = 0.35, int timeout = 15} | Future | yes |
| requestConnectionPriority | Request high-priority, low-latency connection | function | required ConnectionPriority connectionPriorityRequest | Future | no |
| bondState | Monitor device bond state changes (Android only) | function | / | Stream | no |
| createBond | Force display system pairing dialog (if needed) | function | {int timeout = 90} | Future | no |
| removeBond | Remove device's Bluetooth bond | function | {int timeout = 30} | Future | no |
| setPreferredPhy | Set preferred RX and TX PHY and options for connection | function | required int txPhy, required int rxPhy, required PhyCoding option | Future | no |
| clearGattCache | Clear service discovery cache on Android | function | / | Future | no |
BluetoothCharacteristic API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| uuid | Get the UUID of the characteristic value | function | / | Guid | yes |
| device | Get associated Bluetooth device | function | / | BluetoothDevice | yes |
| properties | Get characteristic properties | function | / | CharacteristicProperties | yes |
| descriptors | Get descriptor list of the characteristic value | function | / | List | yes |
| lastValue | Last received characteristic value | function | / | List | yes |
| lastValueStream | Characteristic value receive stream + write stream | function | / | Stream<List> | yes |
| onValueReceived | Stream for receiving characteristic value updates from device | function | / | Stream<List> | yes |
| read | Read characteristic value content | function | {int timeout = 15} | Future<List> | yes |
| write | Write characteristic value content | function | List value, {bool withoutResponse = false, bool allowLongWrite = false, int timeout = 15} | Future | yes |
| setNotifyValue | Set characteristic notification/indication | function | bool notify, {int timeout = 15, bool forceIndications = false} | Future | yes |
| isNotifying | Check if notification/indication is enabled | function | / | bool | yes |
BluetoothDescriptor API
| Name | Description | Type | Input | Output | ohos Support |
|---|---|---|---|---|---|
| uuid | Get the UUID of the descriptor | function | / | Guid | yes |
| device | Get associated Bluetooth device | function | / | BluetoothDevice | yes |
| lastValue | Last received descriptor value | function | / | List | yes |
| lastValueStream | Descriptor value receive stream + write stream | function | / | Stream<List> | yes |
| onValueReceived | Stream for descriptor value reads/writes | function | / | Stream<List> | yes |
| read | Read descriptor content | function | {int timeout = 15} | Future<List> | yes |
| write | Write descriptor content | function | List value, {int timeout = 15} | Future | yes |
4. Known Issues
5. Others
6. License
This project is licensed under The BSD-3-Clause (license).