Merge branch 'release-2.8.0'

Author: Stephen Schiffli

Docs/gen_api_reference.sh

@@ -1 +1,5 @@
-appledoc -p "MetaWear iOS/macOS/tvOS API 2.7.3" --project-version "2.7.3" -c "MBIENTLAB INC" --company-id com.mbientlab --no-create-docset --no-repeat-first-par --ignore .m -o . ../MetaWear/Classes
+appledoc -p "MetaWear iOS/macOS/tvOS API 2.8.0" --project-version "2.8.0" -c "MBIENTLAB INC" --company-id com.mbientlab --no-create-docset --no-repeat-first-par --ignore .m -o . ../MetaWear/Classes
+open html/index.html
+
+make html
+open build/html/index.html

Docs/source/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.7.3'
+version = '2.8.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.7.3'
+release = '2.8.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Docs/source/index.rst

@@ -52,3 +52,4 @@ If you are not developing for the Apple ecosystem, we also offer an `Android API
     timer
     serial
     filters
+    sensor_fusion

Docs/source/metawear_manager.rst

@@ -49,7 +49,7 @@ This feature is handy because the ``discoveryTimeRSSI`` property on the discover
             if (device.discoveryTimeRSSI.integerValue < MIN_ALLOWED_RSSI) {
                 continue;
             }
-            [[MBLMetaWearManager sharedManager] stopScanForMetaWears];
+            [[MBLMetaWearManager sharedManager] stopScan];
             // At this point we have a close MetaWear, do what you please with it!
         }
     }];

Docs/source/sensor_fusion.rst

@@ -0,0 +1,61 @@
+.. highlight:: Objective-C
+
+Sensor Fusion
+=============
+
+The MetaMotion family of boards comes with a builtin Sensor Fusion algorithm.  It's configured via properties on the `MBLSensorFusion <https://www.mbientlab.com/docs/metawear/ios/latest/Classes/MBLSensorFusion.html>`_ class.
+
+As explained `here <http://www.chrobotics.com/library/attitude-estimation>`_.  When estimating attitude and heading, the best results are obtained by combining data from multiple types of sensors to take advantage of their relative strengths. For example, rate gyros can be integrated to produce angle estimates that are reliable in the short-term, but that tend to drift in the long-term. Accelerometers, on the other hand, are sensitive to vibration and other non-gravity accelerations in the short-term, but can be trusted in the long-term to provide angle estimates that do no degrade as time progresses.  Combining rate gyros and accelerometers can produce the best of both worlds - angle estimates that are resistant to vibration and immune to long-term angular drift.
+
+Attitude and Heading
+--------------------
+
+We provide attitude and heading information using both Euler Angles and Quaternions.  Compared to quaternions, Euler Angles are simple and intuitive and they lend themselves well to simple analysis and control.  On the other hand, Euler Angles are limited by a phenomenon called Gimbal Lock.  In applications where the sensor will never operate near pitch angles of +/- 90 degrees, Euler Angles are a good choice.  A quaternion is a four-element vector that can be used to encode any rotation in a 3D coordinate system.  Technically, a quaternion is composed of one real element and three complex elements.  It's best to start with Euler Angles unless you are already familiar with quaternions.
+
+::
+
+    [self.device.sensorFusion.eulerAngle startNotificationsWithHandlerAsync:^(MBLEulerAngleData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+    [self.device.sensorFusion.quaternion startNotificationsWithHandlerAsync:^(MBLQuaternionData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+
+Gravity Reading
+---------------
+
+This looks at the acceleration due to gravity and removes the acceleration due to motion.  This vector always points to Earth.
+
+::
+
+    [self.device.sensorFusion.gravity startNotificationsWithHandlerAsync:^(MBLAccelerometerData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+
+Linear Acceleration
+-------------------
+
+This looks at the acceleration due to motion and removes the acceleration due to gravity.
+
+::
+
+    [self.device.sensorFusion.gravity startNotificationsWithHandlerAsync:^(MBLAccelerometerData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+
+Corrected Sensor Readings
+-------------------------
+
+Sensor fusion algorithms are able to use the strengths of various sensors to improve the weaknesses of others.  This allows us to extract more accurate readings of sensor values.
+
+::
+
+    [device.sensorFusion.acceleration startNotificationsWithHandlerAsync:^(MBLCorrectedAccelerometerData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+    [device.sensorFusion.rotation startNotificationsWithHandlerAsync:^(MBLCorrectedGyroData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];
+    [device.sensorFusion.magneticField startNotificationsWithHandlerAsync:^(MBLCorrectedMagnetometeData *obj, NSError *error) {
+        NSLog(@"%@", obj);
+    }];

MetaWear.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name               = 'MetaWear'
-  s.version            = '2.7.3'
+  s.version            = '2.8.0'
   s.license            = { :type => 'Commercial', :text => 'See https://www.mbientlab.com/terms/', :file => 'LICENSE' }
   s.homepage           = 'https://mbientlab.com'
   s.summary            = 'iOS/macOS/tvOS API and documentation for the MetaWear platform'

MetaWear/Classes/Categories/BFTask+MBLExtensions.h

@@ -58,31 +58,32 @@ NS_ASSUME_NONNULL_BEGIN
 
 typedef void (^MBLSuccessBlock)(ResultType result);
 typedef void (^MBLErrorBlock)(NSError *error);
+typedef __nullable id(^MBLExtensionsContinuationBlock)(BFTask<ResultType> *t);
 
 /**
- Add a block to be called if the task finishes successfully, complete with the 
+ Add a block to be called if the task finishes successfully, complete with the
  tasks result.  This callback will occur on the dispatchExecutor.
  */
-- (instancetype)success:(MBLSuccessBlock)block;
+- (BFTask *)success:(MBLSuccessBlock)block;
 
 /**
  Add a block to be called if the task finishes with an error.
  This callback will occur on the dispatchExecutor.
  */
-- (instancetype)failure:(MBLErrorBlock)block;
+- (BFTask *)failure:(MBLErrorBlock)block;
 
 
 /**
  Enqueues the given block to be run once this task completes successfully.
  This callback will occur on the dispatchExecutor.
  */
-- (instancetype)continueOnDispatchWithSuccessBlock:(BFContinuationBlock)block;
+- (BFTask *)continueOnDispatchWithSuccessBlock:(MBLExtensionsContinuationBlock)block NS_SWIFT_NAME(continueOnDispatchWithSuccess(block:));
 
 /**
  Enqueues the given block to be run once this task completes.
  This callback will occur on the dispatchExecutor.
  */
-- (instancetype)continueOnDispatchWithBlock:(BFContinuationBlock)block;
+- (BFTask *)continueOnDispatchWithBlock:(MBLExtensionsContinuationBlock)block NS_SWIFT_NAME(continueOnDispatch(block:));
 
 @end
 

MetaWear/Classes/Categories/BFTask+MBLExtensions.m

@@ -34,7 +34,7 @@
  */
 
 #import "BFTask+MBLExtensions.h"
-#import "BFTask+Private.h"
+#import "BFTask+MBLPrivate.h"
 #import "MBLMetaWearManager+Private.h"
 
 @implementation BFExecutor (MBLExtensions)
@@ -56,7 +56,7 @@ + (BFExecutor *)dispatchExecutor
 
 @implementation BFTask (MBLExtensions)
 
-- (instancetype)success:(MBLSuccessBlock)block
+- (BFTask *)success:(MBLSuccessBlock)block
 {
     return [self continueOnDispatchWithSuccessBlock:^id _Nullable(BFTask * _Nonnull task) {
         // We need to send a non-null response but some tasks don't
@@ -66,7 +66,7 @@ - (instancetype)success:(MBLSuccessBlock)block
     }];
 }
 
-- (instancetype)failure:(MBLErrorBlock)block
+- (BFTask *)failure:(MBLErrorBlock)block
 {
     return [self continueOnDispatchWithBlock:^id _Nullable(BFTask * _Nonnull task) {
         if (task.error) {
@@ -76,12 +76,12 @@ - (instancetype)failure:(MBLErrorBlock)block
     }];
 }
 
-- (instancetype)continueOnDispatchWithSuccessBlock:(BFContinuationBlock)block
+- (BFTask *)continueOnDispatchWithSuccessBlock:(MBLExtensionsContinuationBlock)block
 {
     return [self continueWithExecutor:[BFExecutor dispatchExecutor] withSuccessBlock:block];
 }
 
-- (instancetype)continueOnDispatchWithBlock:(BFContinuationBlock)block
+- (BFTask *)continueOnDispatchWithBlock:(MBLExtensionsContinuationBlock)block
 {
     return [self continueWithExecutor:[BFExecutor dispatchExecutor] withBlock:block];
 }
@@ -93,4 +93,3 @@ void MBLForceLoadCategory_BFTask_MBLExtensions()
     NSString *string = nil;
     [string description];
 }
-

MetaWear/Classes/Core/MBLConstants.h

@@ -69,7 +69,8 @@ typedef NS_ENUM(uint8_t, MBLFirmwareVersion) {
     MBLFirmwareVersion1_2_2,
     MBLFirmwareVersion1_2_3,
     MBLFirmwareVersion1_2_4,
-    MBLFirmwareVersion1_2_5
+    MBLFirmwareVersion1_2_5,
+    MBLFirmwareVersion1_3_0
 };
 NSString *MBLFirmwareVersionString(MBLFirmwareVersion version);
 
@@ -103,6 +104,17 @@ typedef NS_ENUM(uint8_t, MBLLogLevel) {
     MBLLogLevelDebug = 4
 };
 
+/**
+ Rating of Sensor Fusion calibration status for data samples
+ */
+typedef NS_ENUM(uint8_t, MBLCalibrationAccuracy) {
+    MBLCalibrationAccuracyUnreliable = 0,
+    MBLCalibrationAccuracyLow = 1,
+    MBLCalibrationAccuracyMedium = 2,
+    MBLCalibrationAccuracyHigh = 3
+};
+NSString *MBLCalibrationAccuracyString(MBLCalibrationAccuracy accuracy);
+
 #pragma mark - Block Typedefs
 
 typedef void (^MBLVoidHandler)();
@@ -161,7 +173,7 @@ extern NSInteger const kMBLErrorConnectionTimeout;
 extern NSInteger const kMBLErrorWrongFirmwareModelNumber;
 
 /*! @abstract 109: Couldn't perform DFU, no valid firmware releases found */
-extern NSInteger const kMBLErrorNoAvaliableFirmware;
+extern NSInteger const kMBLErrorNoAvailableFirmware;
 
 /*! @abstract 110: MetaWear not connected, can't perform operation */
 extern NSInteger const kMBLErrorNotConnected;

MetaWear/Classes/Core/MBLConstants.m

@@ -36,7 +36,7 @@
 #import "MBLConstants.h"
 #import "MBLConstants+Private.h"
 
-NSString *const kMBLAPIVersion = @"2.7.3";
+NSString *const kMBLAPIVersion = @"2.8.0";
 
 NSString *MBLFirmwareVersionString(MBLFirmwareVersion version)
 {
@@ -67,6 +67,22 @@
             return @"1.2.4";
         case MBLFirmwareVersion1_2_5:
             return @"1.2.5";
+        case MBLFirmwareVersion1_3_0:
+            return @"1.3.0";
+    }
+}
+
+NSString *MBLCalibrationAccuracyString(MBLCalibrationAccuracy accuracy)
+{
+    switch (accuracy) {
+        case MBLCalibrationAccuracyUnreliable:
+            return @"Unreliable";
+        case MBLCalibrationAccuracyLow:
+            return @"Low";
+        case MBLCalibrationAccuracyMedium:
+            return @"Medium";
+        case MBLCalibrationAccuracyHigh:
+            return @"High";
     }
 }
 
@@ -83,7 +99,7 @@
 NSInteger const kMBLErrorUnexpectedDisconnect = 106;
 NSInteger const kMBLErrorConnectionTimeout = 107;
 NSInteger const kMBLErrorWrongFirmwareModelNumber = 108;
-NSInteger const kMBLErrorNoAvaliableFirmware = 109;
+NSInteger const kMBLErrorNoAvailableFirmware = 109;
 NSInteger const kMBLErrorNotConnected = 110;
 NSInteger const kMBLErrorInsufficientMemory = 111;
 NSInteger const kMBLErrorOperationInvalid = 112;