diff --git a/README.md b/README.md index 3a2efb0b..5161a5d0 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ The library is organised around a few base entities, which are: - **Peripheral** - **Service** - **Characteristic** +* **Descriptor** You have to create an instance _BleManager_ and initialise underlying native resources. Using that instance you then obtain an instance of _Peripheral_, @@ -199,12 +200,18 @@ service.writeCharacteristic( characteristic.write(Uint8List.fromList([0]), false); //returns void ``` -Monitoring or reading a characteristic from _Peripheral_/_Service_ level +Monitoring or reading a characteristic from _Peripheral_/_Service_ level return _CharacteristicWithValue_ object, which is _Characteristic_ with additional `Uint8List value` property. - -## Facilitated by Frontside - -[Frontside](https://github.com/thefrontside) provided architectural advice and financial support for this library on behalf of [Resideo](https://github.com/resideo). + + ### Descriptor operations + +List of descriptors from a single characteristic can be obtained in a similar fashion to a list of characteristics from a single service, either from Peripheral, Service or Characteristic object. +Descriptors can be read/written from Peripheral, Service or Characteristic by supplying necessary UUIDs, or from Descriptor object. + +**Note:** to enable monitoring of characteristic you should use `characteristic.monitor()` or `(peripheral/service).monitorCharacteristic()` instead of changing the value of the underlying descriptor yourself. + +## Facilitated by Frontside +[Frontside](https://github.com/thefrontside) provided architectural advice and financial support for this library on behalf of [Resideo](https://github.com/resideo). ## Maintained by diff --git a/REFERENCE.md b/REFERENCE.md index cb73d6c1..e6e9429a 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,4 +1,5 @@ # Overview + The library is organised around a few base entities, which are: * **BleManager** * **Peripheral** @@ -7,25 +8,34 @@ The library is organised around a few base entities, which are: The basic idea is to create an instance of **BleManager**, use it to create/release native clients of the underlying libraries, scan for peripherals and then operate on **Peripheral**. + # BleManager + This entity serves as the library's entry point. It doesn't track any state, so it is safe to create as many of those as you wish. All of the following methods belong to BleManager instance. + ## Managing native resources + ```dart Future createClient({ String restoreStateIdentifier, RestoreStateAction restoreStateAction, }); ``` + Creates native adapters for handling BLE. *This method has to be called before you can begin using the library.* Both parameters are iOS-specific and handle restoration of already bonded devices, eg. after a crash. Method will return error if an instance of native BleAdapter has already been created. + ```dart Future destroyClient(); ``` + Releases native resources. Should be called once there's no further need for BLE capabilities. + ## Scanning for peripherals + ```dart Stream startPeripheralScan({ int scanMode, @@ -34,6 +44,7 @@ Releases native resources. Should be called once there's no further need for BLE bool allowDuplicates, }); ``` + `scanMode` and `callbackType` are Android-specific. [More information in Android documentation](https://developer.android.com/reference/android/bluetooth/le/ScanSettings) `allowDuplicates` is iOS-specific. [More information in iOS documentation](https://developer.apple.com/documentation/corebluetooth/cbcentralmanagerscanoptionallowduplicateskey) `uuids` is used to filter peripherals to only return those containing services with specified UUIDs. @@ -43,11 +54,15 @@ Returns a stream of objects containing advertisement data of the peripheral and ```dart Future stopDeviceScan(); ``` + Ends peripheral scan. + ## Managing log level + ```dart Future setLogLevel(LogLevel logLevel); ``` + Sets log level of underlying native libraries. Possible values are: * `none` * `verbose` @@ -59,39 +74,54 @@ Sets log level of underlying native libraries. Possible values are: ```dart Future logLevel(); ``` + Returns current log level of underlying native libraries. + ## Managing radio state + ```dart Future enableRadio({String transactionId}); ``` + Turns on system's Bluetooth Adapter. Android-only feature. This operation will fail immediately on iOS. ```dart Future disableRadio({String transactionId}); ``` + Turns off system's Bluetooth adapter. Android-only feature. This operation will fail immediately on iOS. ```dart Future bluetoothState(); ``` + Return the current state of system's Bluetooth adapter. ```dart Stream observeBluetoothState({bool emitCurrentValue = true}); ``` + Returns a stream of system's Bluetooth adapter state changes. By default emits current value first; behaviour can be overridden by passing `false` to the optional argument. + ## Listing known devices + ```dart Future> knownDevices(List peripheralIdentifiers); ``` + Return a list of Peripherals that have been scanned and match any of the supplied identifiers. Returns empty list if an empty list is passed. + ```dart Future> connectedDevices(List serviceUUIDs); + ``` + Returns a list of connected Peripherals that have at least one service with UUID matching any of the supplied UUIDs. Returns empty list if an empty list is passed. + ## Cancelling asynchronous operations + ```dart Future cancelTransaction(String transactionId); ``` @@ -103,9 +133,12 @@ The cancelled operation will still be completed (perhaps with error), but the us _(Read more about [transactions](https://github.com/Polidea/FlutterBleLib/#transactions))_ # Peripheral + Object representing a peripheral. Allows for managing connection, discovery and serves as a shortcut to characteristic operations, if the user knows the UUIDs of both service and characteristic. All of the following methods belong to Peripheral instance. + ## Connection + ```dart Future connect( {bool isAutoConnect = false, @@ -122,63 +155,89 @@ Attempts to connect to the peripheral. `refreshGatt` forces GATT to refresh its cache; Android-specific. If connection has not been established by `timeout`, the operation fails. `timeout` defaults to 30 seconds. + ```dart Stream observeConnectionState( {bool emitCurrentValue = false, bool completeOnDisconnect = false}); ``` + Returns a stream containing changes to the connection state. By default doesn't emit current state, nor terminates the stream after disconnecting. **Note:** due ambiguities concerning `disconnecting` state, current implementation never emits `disconnecting`, only `connecting`, `connected`, `disconnected`. ```dart Future isConnected(); ``` + Returns true if the peripheral is currently connected. ```dart Future disconnectOrCancelConnection(); ``` + Terminates connection or any attempt to connect. -## Obtaining services and characteristics + +## Obtaining services, characteristics and descriptors + ```dart Future discoverAllServicesAndCharacteristics({String transactionId}); ``` + Runs the discovery process, caching all discovered services and characteristics in the native parts. **Must be run before `services()`, `characteristics()` and any operations on characteristics** Operation is cancellable, meaning the operation's result in Dart can be discarded. + ```dart Future> services(); ``` -Returns list of all discovered services for the peripheral. + +Returns a list of all discovered services for the peripheral. Fails if discovery has not been done. ```dart Future> characteristics(String servicedUuid); ``` -Returns list of all discovered characteristics for the specified service of the peripheral. + +Returns a list of all discovered characteristics for the specified service of the peripheral. Fails if discovery has not been done. + +```dart + Future> descriptorsForCharacteristic( + String serviceUuid, + String characteristicUuid, + ); +``` + +Returns a list of all descriptors of the specified characteristic. Returns first match encountered, if there are UUID conflicts. + ## RSSI and MTU + ```dart Future rssi({String transactionId}) { return _manager.rssi(this, transactionId); } ``` + Reads current RSSI if the device is connected. + ```dart Future requestMtu(int mtu, {String transactionId}) { return _manager.requestMtu(this, mtu, transactionId); } ``` + Request peripheral to set a different MTU. On iOS only returns the current value. Returns the MTU set by peripheral after the request. MTU can be requested only once in the lifetime of the connection, meaning this call will fail if it was set prior by either passing a valid value to `connect(requestMtu: int)` or calling this function. ## Characteristic convenience methods + Finds first service with specified UUID and first characteristic in said service with specified UUID and then performs the requested operation. Following operations will be discussed in details in **Characteristic** section. `CharacteristicWithValue` object is a `Characteristic` with additional `Uint8List value` property. + ```dart Future readCharacteristic( String serviceUUID, @@ -186,6 +245,7 @@ Future readCharacteristic( String transactionId, }); ``` + ```dart Future writeCharacteristic( String serviceUUID, @@ -195,6 +255,7 @@ Future readCharacteristic( String transactionId, }); ``` + ```dart Stream monitorCharacteristic( String serviceUUID, @@ -202,16 +263,23 @@ Future readCharacteristic( String transactionId, }); ``` + # Service + Object representing a unique service associated with unique peripheral, ensured by the internal mechanisms of MultiPlatformBleAdapter. For ease of use exposes property `peripheral`. All of the following methods belong to Service instance. + ## Obtaining characteristics + ```dart Future> characteristics(); ``` + Returns a list of characteristics this service contains. + ## Characteristic convenience methods + Following operations will be discussed in details **Characteristic** section. Finds first characteristic with specified UUID and then performs the requested operation. `CharacteristicWithValue` object is a `Characteristic` with additional `Uint8List value` property. @@ -224,10 +292,12 @@ Finds first characteristic with specified UUID and then performs the requested o String transactionId, }); ``` + ```dart Future readCharacteristic(String characteristicUUID, {String transactionId}); ``` + ```dart Stream monitorCharacteristic( String characteristicUUID, { @@ -236,6 +306,7 @@ Finds first characteristic with specified UUID and then performs the requested o ``` # Characteristic + Object representing unique characteristic inside a unique service associated with unique peripheral, all ensured by the internal mechanisms of MultiPlatformBleAdapter. For ease of use exposes property `service`. Contains following boolean properties: @@ -251,7 +322,9 @@ All of the following methods belong to Characteristic instance. ```dart Future read({String transactionId}); ``` + Reads the value of the characteristic. Operation is cancellable, meaning the operation's result in Dart can be discarded. + ```dart Future write( Uint8List bytes, @@ -259,8 +332,25 @@ Reads the value of the characteristic. Operation is cancellable, meaning the ope String transactionId, }); ``` + Writes value to this characteristic. It is user's responsibility to choose whether write should be done with or without response. + ```dart Stream monitor({String transactionId}); ``` + Operation is cancellable, which allows the user to terminate the notifications from the peripheral for this characteristic. + +# Descriptor + +Object representing unique descriptor inside unique characteristic inside a unique service associated with unique peripheral, all ensured by the internal mechanisms of MultiPlatformBleAdapter. + +For ease of use exposes `characteristic` property. + +```dart + Future read({String transactionId}); +``` + +```dart + Future write(Uint8List value, {String transactionId}) +``` \ No newline at end of file