OpenRowingCommunity · MonsieurRz · May 10, 2022 · May 10, 2022 · May 10, 2022 · May 10, 2022
diff --git a/.github/workflows/dart.yml b/.github/workflows/dart.yml
@@ -23,12 +23,12 @@ jobs:
       # https://github.com/dart-lang/setup-dart/blob/main/README.md
       - uses: dart-lang/setup-dart@v1
         with:
-          sdk: 3.1.3
+          sdk: stable
 
-      - uses: subosito/flutter-action@v1
+      - uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: 3.13.0
+          flutter-version: 3.19.0
 
       - name: Install dependencies
         run: flutter pub get

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,9 @@
+# Do not remove or rename entries in this file, only add new ones
+# See https://github.com/flutter/flutter/issues/128635 for more context.
+
 # Miscellaneous
 *.class
+*.lock
 *.log
 *.pyc
 *.swp
@@ -15,26 +19,143 @@
 *.iws
 .idea/
 
-# The .vscode folder contains launch configuration and tasks you configure in
-# VS Code which you may wish to be included in version control, so this line
-# is commented out by default.
-#.vscode/
+# Visual Studio Code related
+.classpath
+.project
+.settings/
+.vscode/
+.ccls-cache
+
+# This file, on the master branch, should never exist or be checked-in.
+#
+# On a *final* release branch, that is, what will ship to stable or beta, the
+# file can be force added (git add --force) and checked-in in order to effectively
+# "pin" the engine artifact version so the flutter tool does not need to use git
+# to determine the engine artifacts.
+#
+# See https://github.com/flutter/flutter/blob/main/docs/tool/Engine-artifacts.md.
+/bin/internal/engine.version
+
+# Flutter repo-specific
+/bin/cache/
+/bin/internal/bootstrap.bat
+/bin/internal/bootstrap.sh
+/bin/internal/engine.realm
+/bin/mingit/
+/dev/benchmarks/mega_gallery/
+/dev/bots/.recipe_deps
+/dev/bots/android_tools/
+/dev/devicelab/ABresults*.json
+/dev/docs/doc/
+/dev/docs/api_docs.zip
+/dev/docs/flutter.docs.zip
+/dev/docs/lib/
+/dev/docs/pubspec.yaml
+/dev/integration_tests/**/xcuserdata
+/dev/integration_tests/**/Pods
+/packages/flutter/coverage/
+version
+analysis_benchmark.json
+
+# packages file containing multi-root paths
+.packages.generated
 
 # Flutter/Dart/Pub related
 **/doc/api/
 .dart_tool/
 .flutter-plugins
 .flutter-plugins-dependencies
+**/generated_plugin_registrant.dart
 .packages
+.pub-preload-cache/
 .pub-cache/
 .pub/
 build/
-# If you're building an application, you may want to check-in your pubspec.lock
-pubspec.lock
+flutter_*.png
+linked_*.ds
+unlinked.ds
+unlinked_spec.ds
+
+# Android related
+**/android/**/gradle-wrapper.jar
+.gradle/
+**/android/captures/
+**/android/gradlew
+**/android/gradlew.bat
+**/android/**/GeneratedPluginRegistrant.java
+**/android/key.properties
+*.jks
+local.properties
+**/.cxx/
+
+# iOS/XCode related
+**/ios/**/*.mode1v3
+**/ios/**/*.mode2v3
+**/ios/**/*.moved-aside
+**/ios/**/*.pbxuser
+**/ios/**/*.perspectivev3
+**/ios/**/*sync/
+**/ios/**/.sconsign.dblite
+**/ios/**/.tags*
+**/ios/**/.vagrant/
+**/ios/**/DerivedData/
+**/ios/**/Icon?
+**/ios/**/Pods/
+**/ios/**/.symlinks/
+**/ios/**/profile
+**/ios/**/xcuserdata
+**/ios/.generated/
+**/ios/Flutter/.last_build_id
+**/ios/Flutter/App.framework
+**/ios/Flutter/Flutter.framework
+**/ios/Flutter/Flutter.podspec
+**/ios/Flutter/Generated.xcconfig
+**/ios/Flutter/ephemeral
+**/ios/Flutter/app.flx
+**/ios/Flutter/app.zip
+**/ios/Flutter/flutter_assets/
+**/ios/Flutter/flutter_export_environment.sh
+**/ios/ServiceDefinitions.json
+**/ios/Runner/GeneratedPluginRegistrant.*
+
+# macOS
+**/Flutter/ephemeral/
+**/Pods/
+**/macos/Flutter/GeneratedPluginRegistrant.swift
+**/macos/Flutter/ephemeral
+**/xcuserdata/
+
+# Windows
+**/windows/flutter/ephemeral/
+**/windows/flutter/generated_plugin_registrant.cc
+**/windows/flutter/generated_plugin_registrant.h
+**/windows/flutter/generated_plugins.cmake
 
+# Linux
+**/linux/flutter/ephemeral/
+**/linux/flutter/generated_plugin_registrant.cc
+**/linux/flutter/generated_plugin_registrant.h
+**/linux/flutter/generated_plugins.cmake
 
+# Coverage
+coverage/
 
+# Symbols
+app.*.symbols
 
-## Custom stuff
+# Exceptions to above rules.
+!**/ios/**/default.mode1v3
+!**/ios/**/default.mode2v3
+!**/ios/**/default.pbxuser
+!**/ios/**/default.perspectivev3
+!/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
+!/dev/ci/**/Gemfile.lock
+!.vscode/settings.json
 
-coverage/
+# Monorepo
+.cipd
+.gclient
+.gclient_entries
+.python-version
+.gclient_previous_custom_vars
+.gclient_previous_sync_commits
diff --git a/README.md b/README.md
@@ -79,13 +79,21 @@ Once you have the `Ergometer` instance for the erg you want to connect to, you c
 
 ```dart
 StreamSubscription<Ergometer> ergConnectionStream = myErg.connectAndDiscover().listen((event) {
-    if(event == ErgometerConnectionState.connected) {
-      //do stuff here once the erg is connected
-    } else if (event == ErgometerConnectionState.disconnected) {
-      //handle disconnection here
-    }
-  });
-}
+  if(event == ErgometerConnectionState.connected) {
+    //do stuff here once the erg is connected
+  } else if (event == ErgometerConnectionState.disconnected) {
+    //handle disconnection here
+  }
+}, onError: (Object error) {
+  // Handle a possible error
+  if (error is C2ConnectionException) {
+    //handle connection errors
+  } else if (error is C2BluetoothException) {
+    print("C2Bluetooth error: ${error.message}");
+  } else {
+    print("Unknown error: $error");
+  }
+});
 ```
 
 When you are done, disconnect from your erg by cancelling the stream:

diff --git a/docs/API.md b/docs/API.md
@@ -3,18 +3,29 @@
 This document is the starting point for learning more about the c2bluetooth API and inner workings at varying levels of detail:
 
 - The broadest overview comes from using the API as documented in the README
-- sections like [Overall API Design](#overall-api-design) explain some of the core concepts or goals that we wanted to achieve with the API.
-- For people looking to get into the internals of c2bluetooth, the [Core API Concepts](#core-api-concepts) section below is a good mid-level overview of the various groups or categories of classes that are used in the API and what their purpose is.
-- For summaries of how c2bluetooth works internally and all the things it "takes care of" for end users, see the [internals](internals.md) document
+- sections like [Core Values](#core-values) help explain more of the "why" behind some of the design choices made in the API.
+- The [Basic api details](#basic-api-details) section is a detailed, mid-level overview of as man aspects of the public API as posible and what their purpose is.
+- For people looking to get into the internals of c2bluetooth or make contributions, see the [internals](internals.md) document.
 - Obviously the most detailed explaination of how the code works comes from reading the code and inline comments themselves. It is helpful to understand the general goals first 
 
 ## Terms used
 
 "implementor" generally refers to users of this library. This is intended to be an audience of primarily other flutter developers looking to use this library in their apps.
 
 
+## Core values
 
-## Overall API design
+These are some of the core values that were considered as part of the development of this library and forms the ethos/soul of the project. These should be used as general guidance when questions of scope or direction of the library are considered. 
+
+### The Silent Protector
+
+This principle shares its name with the [popular meme template](https://knowyourmeme.com/memes/the-silent-protector) depicting a soldier kneeling over and protecting a sleeping child.
+
+![A remix of the "silent protector" meme depicting c2bluetooth protecting the apps that use it from low-level details of bluetooth communications with a concept2 erg](../docs/images/silent-protector.jpg)
+
+This is essentially a graphical analogy to represent the idea that this library aims to "take on" as much responsibility for abstracting low-level details and hiding away various "gotchas" and complexities of the Concept2 Bluetooth interface specification as possible.
+
+To my knowledge this is not currently a software design principle found in the broader software industry. However I think it is an awesome way to explain the concept.
 
 ### Inspiration
 In order for this library to be a good fit within the community and provide a good user experience for developers, the goal is to design the interface for this library after other existing libraries interfacing with Concept2 rowing machines. The libraries looked at were [Py3Row](https://github.com/droogmic/Py3Row) (Python, BSD-2), [BoutFitness/Concept2-SDK](https://github.com/BoutFitness/Concept2-SDK) (Swift, MIT), [ErgometerJS](https://github.com/tijmenvangulik/ErgometerJS) (Javascript, Apache 2).
@@ -38,20 +49,13 @@ Since a lot of the architecture is already provided by FlutterBleLib and will li
 
 
 
-## Core API Concepts
+## Basic API details
 
 This library is built from a few core concepts, some of which are shared with the `csafe-fitness` library. These core concepts represent general groupings of classes that serve a particular purpose or abstract certain aspects of communicating with an erg.
 
 These concepts are roughly divided up into "external" (i.e. those that are part of the libraries public API) and "internal". If you are just using the library in your app, the external concepts should be all you need. Anyone looking to contribute to this library might find the "internal" concepts helpful 
 
 ### External Concepts
-#### Data Objects
-Data objects, such as the WorkoutSummary class, are  essentially wrappers around data exposed by the PM (Performance Monitor)'s bluetooth interface. This makes it easier for applications to access this data by providing a more object-oriented interface.
-
-Data objects are primarily a form of one-way communication from a PM to your application.
-
-Data objects are located in the `data` directory and represent the parts of c2bluetooth's public API that are most likely to be useful to an application. 
-
 
 #### Model Objects
 This is a gairly general group of classes that represent various indoor rowing concepts (in the form of objects). Some examples of classses in this category are the `Ergometer` and `Workout` classes. Unlike Data Objects, they are intended to be able to enable bidirectional data flow. For example, an `Ergometer` object may have properties for getting data (such as Data Objects) but also may contain methods like `sendWorkout()` that allow you to provide a `Workout` object to set up on the erg. `Workout` objects could also be returned by other methods as a way to represent a workout.  

diff --git a/docs/images/demo/connected.png b/docs/images/demo/connected.png
diff --git a/docs/images/demo/permission-denied.png b/docs/images/demo/permission-denied.png
diff --git a/docs/images/demo/pre-scan.png b/docs/images/demo/pre-scan.png
diff --git a/docs/images/demo/scanning.png b/docs/images/demo/scanning.png
diff --git a/docs/images/silent-protector.jpg b/docs/images/silent-protector.jpg
diff --git a/docs/internals.md b/docs/internals.md
@@ -1,7 +1,15 @@
 # Internal API and Design Concepts
 This document is meant to be similar to the [API](API.md) document, but specifically for providing an overview of the internal API organization. 
 
-Only people interested in contributing to c2bluetooth should need to understand things at this level.
+Only people interested in modifying c2bluetooth should need to understand things at this level.
+
+This also can be thought of as an outline of many of the (often low-level) things that c2bluetooth "takes care of" for impleenting applications in keeping with the [Silent Protector principle](API.md#the-silent-protector).
+
+
+## Terms used
+
+### Segment
+One key difference you may notice between this library and the source documentation that this is based on (such as the Concept2 Bluetooth API specifications) is the appearance of the term "segment". This is useful because splits and intervals are fundamentally similar enough that concept2 uses the same API to convey both split and interval data (the two are mutually exclusive anyway). Concept2's documentation, however, refers to it as "Split/interval", so the term segment was introduced to make this a little easier to think about and help differentiate data points that are unique to either splits or intervals. 
 
 ## Internal API Concepts
 #### Commands
@@ -29,3 +37,15 @@ If you need to create your own datatype, you should look at the existing datatyp
 
 This section intends to give a broad overview of various components of how c2bluetooth solves certain problems and why they were solved that way
 
+### Subscription Data Multiplex
+
+In order to provide c2bluetooth with the most flexibility and control over data coming from the PM5, it is useful to insert an additional layer between the incoming data from the bluetooth streams from the PM5 and the stream going out to the user so that c2bluetooth can take on and abstract as much of the complexity as possible.
+
+This is similar to how a library might add a custom class of its own that wraps an existing API from one of its dependencies so that, even if the API being depended on by the library changes, users of the library are more insulated as the library has a locaton where it can perform changes to keep the API as consistent for the end user as possible.
+
+Within the context of c2bluetooth, this additional layer is intended to also add functionality by managing both the data requested by implementors of the c2bluetooth library and the data available to it via the concept2's bluetooth interface so as to provide the implementors with the data that they requested for use in their own apps. 
+
+This layer has a few general objectives:
+- to keep track of what data the implementor wants ("requested data")
+- to keep track of what data we are currently receiving ("subscriptions" to bluetooth notifications from the PM)
+- to route data that comes in via bluetooth subscriptions to "outgoing streams" that the implementor is listening to while conserving bluetooth bandwidth as much as possible