Prepare public release (#231)

* update pubspec with higher dart constraint and links + remove default comments

* document constants, models and extension on int

* document mesh_network.dart

* document mesh_manager_api.dart

* document provisioning.dart

* document ble_manager_callbacks.dart and ble_mesh_manager_callbacks.dart

* document ble_manager.dart + ci script back to flutter stable

* document ble_mesh_manager.dart

* document ble_scanner.dart + move some constants to constants.dart

* add a unit test!

* remove useless meta dependency declaration

* update CHANGELOG.md

* remove unused dev dependency

* update README.md

* add license

* update CHANGELOG.md

.github/workflows/on_pr.yaml

@@ -18,7 +18,7 @@ jobs:
           java-version: "12.x"
       - uses: subosito/flutter-action@v1
         with:
-          flutter-version: '2.5.3'
+          channel: "stable"
       - name: Get dependencies
         run: flutter packages get
       - name: Check format

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.10.0
+
+First open source release ! :rocket:
+
+- add missing documentation
+- remove unused API and dependency
+- refresh `example/`, `ios/` and `android/` folders to be up to date with the latest Flutter version (2.10.3)
+
 ## 0.9.1
 
 - revert app's manifest changes

LICENSE

@@ -1 +1,29 @@
-TODO: Add your license here.
+BSD 3-Clause License
+
+Copyright (c) 2022, OZEO-DOOZ
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,14 +1,7 @@
 # nordic_nrf_mesh
+A Flutter plugin to enable mesh network management and communication using Nordic's SDKs. It also provides the ability to open BLE connection with mesh nodes using some other Flutter [plugin](https://pub.dev/packages/flutter_reactive_ble).
 
-A new flutter plugin project.
+## How to use
+_This section will be updated soon !_
 
-## Getting Started
-
-This project is a starting point for a Flutter
-[plug-in package](https://flutter.dev/developing-packages/),
-a specialized package that includes platform-specific implementation code for
-Android and/or iOS.
-
-For help getting started with Flutter, view our 
-[online documentation](https://flutter.dev/docs), which offers tutorials, 
-samples, guidance on mobile development, and a full API reference.
+Please refer to example app.

example/lib/src/views/home/home.dart

@@ -129,14 +129,14 @@ class _MeshManagerApiWidgetState extends State<MeshManagerApiWidget> {
         ),
         TextButton(
           onPressed: () async {
-            final provisionerList = await _meshNetwork!.provisionerList;
+            final provisionerList = await _meshNetwork!.provisioners;
             debugPrint('# of provs : ${provisionerList.length}');
           },
           child: const Text('get provisioner list'),
         ),
         TextButton(
           onPressed: () async {
-            var provUUIDs = await _meshNetwork!.provisionerList;
+            var provUUIDs = await _meshNetwork!.provisioners;
             for (var value in provUUIDs) {
               debugPrint('$value');
             }

example/lib/src/views/scan_and_provisionning/scan_and_provisioning.dart

@@ -62,8 +62,8 @@ class _ScanningAndProvisioningState extends State<ScanningAndProvisioning> {
         meshProvisioningUuid,
       ],
     ).listen((device) async {
-      _serviceData[device.id] = Uuid.parse(
-          _meshManagerApi.getDeviceUuid(device.serviceData[_meshManagerApi.meshProvisioningUuidServiceKey]!.toList()));
+      _serviceData[device.id] =
+          Uuid.parse(_meshManagerApi.getDeviceUuid(device.serviceData[meshProvisioningUuid]!.toList()));
       if (_devices.every((d) => d.id != device.id)) {
         setState(() {
           _devices.add(device);

example/pubspec.lock

@@ -298,7 +298,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.9.1"
+    version: "0.10.0"
   package_config:
     dependency: transitive
     description:

ios/nordic_nrf_mesh.podspec

@@ -4,10 +4,10 @@
 #
 Pod::Spec.new do |s|
   s.name             = 'nordic_nrf_mesh'
-  s.version          = '0.0.1'
-  s.summary          = 'A Flutter plugin to enable mesh network management and communication using Nordic SDKs. It also provides the ability to open BLE connection with mesh nodes using some other flutter package.'
+  s.version          = '0.10.0'
+  s.summary          = 'A Flutter plugin to enable mesh network management and communication using Nordic SDKs. It also provides the ability to open BLE connection with mesh nodes using some other Flutter plugin.'
   s.description      = <<-DESC
-A Flutter plugin to enable mesh network management and communication using Nordic SDKs. It also provides the ability to open BLE connection with mesh nodes using some other flutter package.
+A Flutter plugin to enable mesh network management and communication using Nordic SDKs. It also provides the ability to open BLE connection with mesh nodes using some other Flutter plugin.
                        DESC
   s.homepage         = 'http://dooz-domotique.com'
   s.license          = { :file => '../LICENSE' }

lib/nordic_nrf_mesh.dart

@@ -1,3 +1,6 @@
+/// A Flutter plugin to enable mesh network management and communication using Nordic's SDKs. It also provides the ability to open BLE connection with mesh nodes using some other Flutter plugin.
+library nordic_nrf_mesh;
+
 export 'src/nrf_mesh.dart';
 export 'src/mesh_network.dart' show IMeshNetwork;
 export 'src/mesh_manager_api.dart';
@@ -8,6 +11,6 @@ export 'src/ble/ble_manager_callbacks.dart';
 export 'src/ble/ble_mesh_manager.dart';
 export 'src/ble/ble_mesh_manager_callbacks.dart';
 export 'src/utils/provisioning.dart' show ProvisioningEvent;
-export 'src/contants.dart' show ProvisioningFailureCode, BleManagerFailureCode;
+export 'src/constants.dart' show ProvisioningFailureCode, BleManagerFailureCode;
 export 'src/exceptions/exceptions.dart';
 export 'src/extensions/extensions.dart';

lib/src/ble/ble_manager.dart

@@ -5,9 +5,9 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter_reactive_ble/flutter_reactive_ble.dart';
 import 'package:meta/meta.dart';
 import 'package:nordic_nrf_mesh/nordic_nrf_mesh.dart';
+import 'package:nordic_nrf_mesh/src/constants.dart';
 
-const mtuSizeMax = 517;
-const maxPacketSize = 20;
+// runtime constants
 final doozCustomServiceUuid =
     Platform.isAndroid ? Uuid.parse('00001400-0000-1000-8000-00805F9B34FB') : Uuid.parse('1400');
 final doozCustomCharacteristicUuid =
@@ -23,12 +23,16 @@ final meshProvisioningDataOut =
     Platform.isAndroid ? Uuid.parse('00002ADC-0000-1000-8000-00805F9B34FB') : Uuid.parse('2ADC');
 final clientCharacteristicConfigDescriptorUuid =
     Platform.isAndroid ? Uuid.parse('00002902-0000-1000-8000-00805f9b34fb') : Uuid.parse('2902');
-const Duration _kConnectionTimeout = Duration(seconds: 30);
 
+/// {@template ble_manager}
+/// An abstract class that should be extended to handle BLE device interactions.
+///
+/// It already implements most parts of the connection process and also triggers event on the given [BleManagerCallbacks].
+/// {@endtemplate}
 abstract class BleManager<E extends BleManagerCallbacks> {
   /// The current BLE device being managed if any
-  DiscoveredDevice? _device;
   DiscoveredDevice? get device => _device;
+  DiscoveredDevice? _device;
 
   /// A [bool] used to adapt the connection process
   bool isProvisioningCompleted = false;
@@ -46,34 +50,37 @@ abstract class BleManager<E extends BleManagerCallbacks> {
   late final StreamSubscription<ConnectionStateUpdate> _globalStatusListener;
 
   /// A [Completer] used to handle the async behavior of [connect] method
-  late Completer<void> _connectCompleter;
-
   @protected
   Completer<void> get connectCompleter => _connectCompleter;
+  late Completer<void> _connectCompleter;
 
   /// The entry point for BLE library
-  final FlutterReactiveBle _bleInstance;
   FlutterReactiveBle get bleInstance => _bleInstance;
+  final FlutterReactiveBle _bleInstance;
 
+  /// {@macro ble_manager}
   BleManager(this._bleInstance) {
     _globalStatusListener = _bleInstance.connectedDeviceStream.listen(_onGlobalStateUpdate);
   }
 
+  /// Will clear used resources
   Future<void> dispose() async {
     await callbacks?.dispose();
     await _connectedDeviceStatusListener?.cancel();
     await _globalStatusListener.cancel();
   }
 
+  /// A method that should be overriden to define a validation on the BLE device advertised services
   @visibleForOverriding
   Future<DiscoveredService?> isRequiredServiceSupported(bool shouldCheckDoozCustomService);
 
   /// A method that should implement the GATT initialization.
   ///
-  /// In our case, it means requesting the highest possible MTU size and subcribing to notifications
+  /// It should for instance request the highest possible MTU size and subscribe to notifications
   @visibleForOverriding
   Future<void> initGatt();
 
+  /// Will disconnect from the current device if any
   Future<void> disconnect() async {
     if (_device == null) {
       _log('calling disconnect without connected device..');
@@ -98,6 +105,9 @@ abstract class BleManager<E extends BleManagerCallbacks> {
   ///   - add event in [callbacks] sinks
   ///   - return any error on the stream or any given reason for [DeviceConnectionState.disconnected] events (usually a [GenericFailure])
   ///
+  /// _DooZ specific API :_
+  /// TODO remove before 1.0.0
+  ///
   /// The [whitelist] has been introduced along with [doozCustomCharacteristicUuid] and is intended to be used like so :
   ///   - the whitelist is populated with MAC addresses and [shouldCheckDoozCustomService] is true
   ///   - it will connect to the BLE device and check the MAC address that should be stored in the DooZ custom charac
@@ -106,7 +116,7 @@ abstract class BleManager<E extends BleManagerCallbacks> {
   /// (because this is a DooZ application specific flow, we made these parameters optional)
   Future<void> connect(
     final DiscoveredDevice discoveredDevice, {
-    Duration connectionTimeout = _kConnectionTimeout,
+    Duration connectionTimeout = kDefaultConnectionTimeout,
     List<String>? whitelist,
     bool shouldCheckDoozCustomService = false,
   }) async {

lib/src/ble/ble_manager_callbacks.dart

@@ -2,18 +2,26 @@ import 'dart:async';
 
 import 'package:flutter_reactive_ble/flutter_reactive_ble.dart';
 
+/// {@template discovered_device_and_service}
+/// A data class used to hold a [DiscoveredDevice] and the corresponding BLE Mesh service
+/// {@endtemplate}
 class BleManagerCallbacksDiscoveredServices {
   final DiscoveredDevice device;
   final DiscoveredService service;
 
+  /// {@macro discovered_device_and_service}
   const BleManagerCallbacksDiscoveredServices(this.device, this.service);
 }
 
+/// {@template ble_error}
+/// An error class use for propagating BLE errors
+/// {@endtemplate}
 class BleManagerCallbacksError {
   final DiscoveredDevice? device;
   final String message;
   final Object? error;
 
+  /// {@macro ble_error}
   const BleManagerCallbacksError(this.device, this.message, this.error);
 
   @override
@@ -23,37 +31,57 @@ class BleManagerCallbacksError {
       'device name: ${device?.name})';
 }
 
+/// An abstract class that should be extended to access callbacks during BLE device interactions
 abstract class BleManagerCallbacks {
+  /// The [StreamController] that is used to trigger an event when a device is connecting
   final onDeviceConnectingController = StreamController<ConnectionStateUpdate>();
+
+  /// The [Stream] that will contain the `connecting` event
   Stream<ConnectionStateUpdate> get onDeviceConnecting => onDeviceConnectingController.stream;
 
+  /// The [StreamController] that is used to trigger an event when a device is connected
   final onDeviceConnectedController = StreamController<ConnectionStateUpdate>();
+
+  /// The [Stream] that will contain the `connected` event
   Stream<ConnectionStateUpdate> get onDeviceConnected => onDeviceConnectedController.stream;
 
+  /// The [StreamController] that is used to trigger an event when a device is disconnecting
   final onDeviceDisconnectingController = StreamController<ConnectionStateUpdate>();
+
+  /// The [Stream] that will contain the `disconnecting` event
   Stream<ConnectionStateUpdate> get onDeviceDisconnecting => onDeviceDisconnectingController.stream;
 
+  /// The [StreamController] that is used to trigger an event when a device is disconnected
   final onDeviceDisconnectedController = StreamController<ConnectionStateUpdate>();
-  Stream<ConnectionStateUpdate> get onDeviceDisconnected => onDeviceDisconnectedController.stream;
 
-  // Stream<BluetoothDevice> onLinkLossOccurred;
+  /// The [Stream] that will contain the `disconnected` event
+  Stream<ConnectionStateUpdate> get onDeviceDisconnected => onDeviceDisconnectedController.stream;
 
+  /// The [StreamController] that is used to trigger an event when BLE services are validated upon connection
   final onServicesDiscoveredController = StreamController<BleManagerCallbacksDiscoveredServices>();
+
+  /// The [Stream] that will contain a [BleManagerCallbacksDiscoveredServices] object when BLE services are validated upon connection
   Stream<BleManagerCallbacksDiscoveredServices> get onServicesDiscovered => onServicesDiscoveredController.stream;
 
+  /// The [StreamController] that is used to trigger an event when the phone is ready to interact with target BLE device
   final onDeviceReadyController = StreamController<DiscoveredDevice>();
+
+  /// The [Stream] that will contain an event when the phone is ready to interact with target BLE device
   Stream<DiscoveredDevice> get onDeviceReady => onDeviceReadyController.stream;
 
+  /// The [StreamController] that is used to trigger an event when an error occur during connection lifetime
   final onErrorController = StreamController<BleManagerCallbacksError>();
-  Stream<BleManagerCallbacksError> get onError => onErrorController.stream;
 
-  // Stream<BluetoothDevice> onDeviceNotSupported;
+  /// The [Stream] that will contain any [BleManagerCallbacksError] that could occur during connection lifetime
+  Stream<BleManagerCallbacksError> get onError => onErrorController.stream;
 
   /// A method that should be used to update the stored MTU so the native code properly constructs the PDUs
   Future<void> sendMtuToMeshManagerApi(int mtu);
 
+  /// RFU
   bool shouldEnableBatteryLevelNotifications(DiscoveredDevice device) => false;
 
+  /// Will clear the used resources
   Future<void> dispose() => Future.wait([
         onDeviceConnectingController.close(),
         onDeviceConnectedController.close(),