EricKwok
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# Low Level API
|
|
|
|
### Connecting
|
|
|
|
```dart
|
|
// Connect to a device using the `deviceId` of the BleDevice received from `UniversalBle.onScanResult`
|
|
String deviceId = bleDevice.deviceId;
|
|
UniversalBle.connect(deviceId);
|
|
|
|
// Disconnect from a device
|
|
UniversalBle.disconnect(deviceId);
|
|
|
|
// Get connection/disconnection updates using stream
|
|
UniversalBle.connectionStream(deviceId).listen((bool isConnected) {
|
|
debugPrint('Is device $deviceId connected?: $isConnected');
|
|
});
|
|
|
|
// Or set a handler to get updates of all devices
|
|
UniversalBle.onConnectionChange = (String deviceId, bool isConnected, String? error) {
|
|
debugPrint('Is device $deviceId connected?: $isConnected. Error: $error');
|
|
}
|
|
```
|
|
|
|
### Discovering Services
|
|
|
|
After establishing a connection, you need to discover services. This method will discover all services and their characteristics.
|
|
|
|
```dart
|
|
// Discover services of a specific device
|
|
UniversalBle.discoverServices(deviceId);
|
|
```
|
|
|
|
### Reading & Writing data
|
|
|
|
You need to first [discover services](#discovering-services) before you are able to read and write to characteristics.
|
|
|
|
```dart
|
|
// Read data from a characteristic
|
|
UniversalBle.read(deviceId, serviceId, characteristicId);
|
|
|
|
// Write data to a characteristic
|
|
UniversalBle.write(deviceId, serviceId, characteristicId, value);
|
|
|
|
// Subscribe to a characteristic notifications
|
|
UniversalBle.subscribeNotifications(deviceId, serviceId, characteristicId);
|
|
|
|
// Subscribe to a characteristic indications
|
|
UniversalBle.subscribeIndications(deviceId, serviceId, characteristicId);
|
|
|
|
// Get characteristic notifications/indications updates using stream
|
|
UniversalBle.characteristicValueStream(deviceId, characteristicId).listen((Uint8List value) {
|
|
debugPrint('OnValueChange $deviceId, $characteristicId, ${hex.encode(value)}');
|
|
});
|
|
|
|
// Or set a handler to get updates of all characteristics
|
|
UniversalBle.onValueChange = (String deviceId, String characteristicId, Uint8List value) {
|
|
debugPrint('onValueChange $deviceId, $characteristicId, ${hex.encode(value)}');
|
|
}
|
|
|
|
// Unsubscribe from notifications/indications
|
|
UniversalBle.unsubscribe(deviceId, serviceId, characteristicId);
|
|
```
|
|
|
|
### Pairing
|
|
|
|
#### Trigger pairing
|
|
|
|
##### Pair on Android, Windows, Linux
|
|
|
|
```dart
|
|
await UniversalBle.pair(deviceId);
|
|
```
|
|
|
|
##### Pair on Apple and web
|
|
|
|
For Apple and Web, pairing support depends on the device. Pairing is triggered automatically by the OS when you try to read/write from/to an encrypted characteristic.
|
|
|
|
Calling `UniversalBle.pair(deviceId)` will only trigger pairing if the device has an _encrypted read characteristic_.
|
|
|
|
If your device only has encrypted write characteristics or you happen to know which encrypted read characteristic you want to use, you can pass it with a `pairingCommand`.
|
|
|
|
```dart
|
|
UniversalBle.pair(deviceId, pairingCommand: BleCommand(service:"SERVICE", characteristic:"ENCRYPTED_CHARACTERISTIC"));
|
|
```
|
|
|
|
After pairing you can check the pairing status.
|
|
|
|
#### Pairing status
|
|
|
|
##### Pair on Android, Windows, Linux
|
|
|
|
```dart
|
|
// Check current pairing state
|
|
bool? isPaired = UniversalBle.isPaired(deviceId);
|
|
```
|
|
|
|
##### Pair on Apple and web
|
|
|
|
For `Apple` and `Web`, you have to pass a "pairingCommand" with an encrypted read or write characteristic. If you don't pass it then it will return `null`.
|
|
|
|
```dart
|
|
bool? isPaired = await UniversalBle.isPaired(deviceId, pairingCommand: BleCommand(service:"SERVICE", characteristic:"ENCRYPTED_CHARACTERISTIC"));
|
|
```
|
|
|
|
##### Discovering encrypted characteristic
|
|
|
|
To discover encrypted characteristics, make sure your device is not paired and use the example app to read/write to all discovered characteristics one by one. If one of them triggers pairing, that means it is encrypted and you can use it to construct `BleCommand(service:"SERVICE", characteristic:"ENCRYPTED_CHARACTERISTIC")`.
|
|
|
|
#### Pairing state changes
|
|
|
|
```dart
|
|
// Get pairing state updates using stream
|
|
UniversalBle.pairingStateStream(deviceId).listen((bool paired) {
|
|
// Handle pairing state change
|
|
});
|
|
|
|
// Or set a handler to get pairing state updates of all devices
|
|
UniversalBle.onPairingStateChange = (String deviceId, bool paired) {}
|
|
```
|
|
|
|
#### Unpair
|
|
|
|
```dart
|
|
UniversalBle.unpair(deviceId);
|
|
```
|
|
|
|
### Request MTU
|
|
|
|
This method will **attempt** to set the MTU (Maximum Transmission Unit) but it is not guaranteed to succeed due to platform limitations. It will always return the current MTU.
|
|
|
|
```dart
|
|
int mtu = await UniversalBle.requestMtu(widget.deviceId, 247);
|
|
```
|
|
|
|
### Read RSSI
|
|
|
|
Read the signal strength (RSSI) of a connected device.
|
|
|
|
```dart
|
|
int rssi = await UniversalBle.readRssi(deviceId);
|
|
```
|
|
|
|
> ⚠️ Note: The device must be connected before reading RSSI.
|
|
|
|
#### Platform Limitations
|
|
|
|
* **Android / iOS / macOS**: Fully supported.
|
|
|
|
* **Windows / Linux / Web**: Not supported.
|