Add high level API (#160)

* Add high-level api extensions for BleDevice and Characteristic * Add doc comments and move few files to utils * Add advance documentation * Make the high level APIs the new default in the readme * More readme cleanups * Add pair api, improve notifications apis and deprecate writeValue * Use highLevel apis in Example * Rename HighLevel isPaired api to hasPairing api * Update Readme * Rename low level readValue api to read and update Readme * Update UniversalBle to use new apis instead of deprecated internally * Split queueCommand and queueCommandWithoutTimeout * Split setNotifiable into subscribeNotifications, subscribeIndications and unsubscribe * Fix web imports * Update changelog * Switch back to isPaired Co-authored-by: Rohit Sangwan <rohitsangwan647@gmail.com> * Fix BleDevice toString method * Switch back to isPaired * Change peripheral to device * Rename cached to preferCached * Remove preferCached from discoverServices() * Update changelog * Use cached services * Add /// * Reverse withoutResponse to withResponse to avoid negation * Link to low level API * Move connectionState to public readme * Rename disableSubscriptions to unsubscribe * Improve documentation * Fix getService cache * Add NotFoundException --------- Co-authored-by: Foti Dim <foti@navideck.com>
2025-06-19 16:32:14 +05:30
parent 72090571a3
commit 0758f5e91d
32 changed files with 940 additions and 278 deletions
@@ -0,0 +1,133 @@
+# 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);
+```