Merge branch 'release-2.8.4'

mbientlab · May 17, 2017 · 0ce1d98 · 0ce1d98
2 parents d24fa9f + 6184d17
commit 0ce1d98
Show file tree

Hide file tree

Showing 96 changed files with 1,964 additions and 1,574 deletions.
diff --git a/Docs/source/accelerometer.rst b/Docs/source/accelerometer.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 Accelerometer
 =============
@@ -14,10 +14,12 @@ One thing common to all accelerometers is the ability to access raw x, y, and z
 
 ::
 
-    device.accelerometer.sampleFrequency = 100; // Default: 100 Hz
-    [device.accelerometer.dataReadyEvent startNotificationsWithHandlerAsync:^(MBLAccelerometerData *obj, NSError *error) {
-        NSLog(@"X = %f, Y = %f, Z = %f", obj.x, obj.y, obj.z);
-    }];
+    device.accelerometer?.sampleFrequency = 100
+    device.accelerometer?.dataReadyEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("X = \(obj.x), Y = \(obj.y), Z = \(obj.z)")
+        }
+    })
 
 Raw RMS Data
 ------------
@@ -26,9 +28,11 @@ You can also access the root mean square (RMS) of the accelerometer data
 
 ::
 
-    [device.accelerometer.rmsDataReadyEvent startNotificationsWithHandlerAsync:^(MBLRMSAccelerometerData *obj, NSError *error) {
-        NSLog(@"RMS: %@", obj);
-    }];
+    device.accelerometer?.rmsDataReadyEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("RMS = \(obj.rms)")
+        }
+    })
 
 Single Axis Data
 ----------------
@@ -37,9 +41,11 @@ You can also access a single axis of accelerometer data.
 
 ::
 
-    [device.accelerometer.xAxisReadyEvent startNotificationsWithHandlerAsync:^(MBLNumericData *obj, NSError *error) {
-        NSLog(@"x-axis: %@", obj);
-    }];
+    device.accelerometer?.xAxisReadyEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("x-axis = \(obj.value)")
+        }
+    })
 
 Cast to Derived Class
 ---------------------
@@ -48,9 +54,8 @@ To use advanced accelerometer features it's necessary to figure out exactly what
 
 ::
 
-    if ([device.accelerometer isKindOfClass:[MBLAccelerometerMMA8452Q class]]) {
-        MBLAccelerometerMMA8452Q *accelerometerMMA8452Q = (MBLAccelerometerMMA8452Q *)device.accelerometer;
-    } else if ([device.accelerometer isKindOfClass:[MBLAccelerometerBMI160 class]]) {
-        MBLAccelerometerBMI160 *accelerometerBMI160 = (MBLAccelerometerBMI160 *)device.accelerometer;
-    }
+    if let accelerometerMMA8452Q = device.accelerometer as? MBLAccelerometerMMA8452Q {
+
+    } else if let accelerometerBMI160 = device.accelerometer as? MBLAccelerometerBMI160 {
 
+    }
diff --git a/Docs/source/accelerometerbmi160.rst b/Docs/source/accelerometerbmi160.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 AccelerometerBMI160
 ===================
@@ -12,10 +12,10 @@ Events can be generated for a single or double tap along any of the axis'.
 
 ::
 
-    accelerometerBMI160.tapType = MBLAccelerometerTapTypeSingle; // Default: Single tap
-    [accelerometerBMI160.tapEvent startNotificationsWithHandlerAsync:^(id obj, NSError *error) {
-        NSLog(@"Tapped Me!");
-    }];
+    accelerometerBMI160.tapEvent.type = .single
+    accelerometerBMI160.tapEvent.startNotificationsAsync(handler: { (obj, error) in
+        print("Tapped Me!")
+    })
 
 Notify on Orientation Change
 ----------------------------
@@ -24,9 +24,11 @@ Events can be generated when an orientation change of the MetaWear occurs.
 
 ::
 
-    [accelerometerBMI160.orientationEvent startNotificationsWithHandlerAsync:^(MBLOrientationData *obj, NSError *error) {
-        NSLog(@"Flipped Me: %@", obj);
-    }];
+    accelerometerBMI160.orientationEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("Flipped Me: \(obj)")
+        }
+    })
 
 Notify when Placed Flat
 -----------------------
@@ -35,9 +37,11 @@ Events can be generated when the MetaWear is set down on a flat surface, or remo
 
 ::
 
-    [accelerometerBMI160.flatEvent startNotificationsWithHandlerAsync:^(MBLAccelerometerBoschFlatData *obj, NSError *error) {
-        NSLog(@"%@" obj.isFlat ? @"Flat" : "Not Flat");
-    }];
+    accelerometerBMI160.flatEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print(obj.isFlat ? "Flat" : "Not Flat")
+        }
+    })
 
 Notify on Step
 --------------
@@ -46,9 +50,11 @@ Events can be generated when a step pattern is detected.
 
 ::
 
-    [accelerometerBMI160.stepEvent startNotificationsWithHandlerAsync:^(MBLNumericData *obj, NSError *error) {
-        NSLog(@"Nice Step!");
-    }];
+    accelerometerBMI160.stepEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("Nice Step!")
+        }
+    })
 
 Notify on Freefall
 ------------------
@@ -57,11 +63,11 @@ Events can be generated when free-fall is detected.
 
 ::
 
-    accelerometerBMI160.lowOrHighGEvent.highGEnabledAxis = 0;
-    accelerometerBMI160.lowOrHighGEvent.lowGEnabled = YES;
-    [accelerometerBMI160.lowOrHighGEvent startNotificationsWithHandlerAsync:^(MBLDataSample *result, NSError *error) {
-        NSLog(@"Dropped Me!");
-    }];
+    accelerometerBMI160.lowOrHighGEvent.highGEnabledAxis = .X
+    accelerometerBMI160.lowOrHighGEvent.lowGEnabled = true;
+    accelerometerBMI160.lowOrHighGEvent.startNotificationsAsync(handler: { (obj, error) in
+        print("Dropped Me!")
+    })
 
 Notify on Shock
 ---------------
@@ -70,13 +76,11 @@ Events can be generated when high acceleration (shock) is detected.
 
 ::
 
-    accelerometerBMI160.fullScaleRange = MBLAccelerometerBMI160Range16G;
-        
-    accelerometerBMI160.lowOrHighGEvent.lowGEnabled = NO;
-    accelerometerBMI160.lowOrHighGEvent.highGThreshold = 8.0;
-    accelerometerBMI160.lowOrHighGEvent.highGEnabledAxis = MBLAccelerometerAxisX;
-        
-    [accelerometerBMI160.lowOrHighGEvent startNotificationsWithHandlerAsync:^(MBLDataSample *result, NSError *error) {
-        NSLog(@"8G Shock in X-Axis!");
-    }];
+    accelerometerBMI160.fullScaleRange = .range16G;
 
+    accelerometerBMI160.lowOrHighGEvent.lowGEnabled = false;
+    accelerometerBMI160.lowOrHighGEvent.highGThreshold = 8.0;
+    accelerometerBMI160.lowOrHighGEvent.highGEnabledAxis = .X;
+    accelerometerBMI160.lowOrHighGEvent.startNotificationsAsync(handler: { (obj, error) in
+        print("8G Shock in X-Axis!")
+    })
diff --git a/Docs/source/accelerometermma8452q.rst b/Docs/source/accelerometermma8452q.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 AccelerometerMMA8452Q
 =====================
@@ -12,11 +12,11 @@ Events can be generated for a single or double tap along any of the axis'.
 
 ::
 
-    accelerometerMMA8452Q.tapDetectionAxis = MBLAccelerometerAxisX; // Default: X-axis tap
-    accelerometerMMA8452Q.tapType = MBLAccelerometerTapTypeSingle; // Default: Single tap
-    [accelerometerMMA8452Q.tapEvent startNotificationsWithHandlerAsync:^(id obj, NSError *error) {
-        NSLog(@"Tapped Me!");
-    }];
+    accelerometerMMA8452Q.tapDetectionAxis = .X
+    accelerometerMMA8452Q.tapType = .single
+    accelerometerMMA8452Q.tapEvent.startNotificationsAsync(handler: { (obj, error) in
+        print("Tapped Me!")
+    })
 
 Notify on Orientation Change
 ----------------------------
@@ -25,9 +25,11 @@ Events can be generated when an orientation change of the MetaWear occurs.
 
 ::
 
-    [accelerometerMMA8452Q.orientationEvent startNotificationsWithHandlerAsync:^(MBLOrientationData *obj, NSError *error) {
-        NSLog(@"Flipped Me: %@", obj);
-    }];
+    accelerometerMMA8452Q.orientationEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("Flipped Me: \(obj)")
+        }
+    })
 
 Notify on Free Fall
 -------------------
@@ -36,9 +38,11 @@ Events can be generated when the MetaWear goes into free fall.
 
 ::
 
-    [accelerometerMMA8452Q.freeFallEvent startNotificationsWithHandlerAsync:^(id obj, NSError *error) {
-        NSLog(@"Dropped Me!");
-    }];
+    accelerometerMMA8452Q.freeFallEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("Dropped Me!")
+        }
+    })
 
 Notify on Shake
 ---------------
@@ -47,7 +51,9 @@ Events can be generated when you shake the MetaWear.
 
 ::
 
-    [accelerometerMMA8452Q.shakeEvent startNotificationsWithHandlerAsync:^(id obj, NSError *error) {
-        NSLog(@"Yeah YOU! Shook me all night long");
-    }];
+    accelerometerMMA8452Q.shakeEvent.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("Yeah YOU! Shook me all night long")
+        }
+    })
 
diff --git a/Docs/source/advanced_features.rst b/Docs/source/advanced_features.rst
@@ -0,0 +1,55 @@
+.. highlight:: swift
+
+Advanced Features 
+=================
+
+High Frequency Streaming
+------------------------
+
+Some developers may want to stream data from multiple motion sensors simultaneously or individually at frequencies higher than 100Hz. To accommodate this use case, accelerometer and gyro have a packed output mode that combines 3 data samples into 1 ble packet increasing the data throughput by 3x.  Simply enable notifications on the ``packedDataReadEvent`` to use this feature.
+
+Persistent Configuration
+------------------------
+
+``MBLRestorable`` object containing custom settings and events that are programmed to the MetaWear and preserved between disconnects and app termination.
+
+Use ``setConfigurationAsync`` to assign a new configuration object to this MetaWear.  This only needs to be called once, likely after you confirm the device from a scanning screen or such.  Upon calling it will erase all non-volatile memory the device (which requires disconnect), then perform reset, once its comes back online we will connect and invoke the runOnDeviceBoot method.   All calls in that method are persisted device side so after any future reset these settings will be applied automatically.
+
+The properties of the configuration objected are automatically persisted to disk after interactions with the board.  If, however, you make changes to various module setting without acutally interacting, then it may be useful to call ``synchronizeAsync`` to force a save to disk.
+
+::
+
+    device.setConfigurationAsync(DeviceConfiguration()).success { _ in
+        print("Settings successfully applied")
+    }.failure { error in
+        print("Something went wrong, we should try again: \(error)")
+    }
+
+Updating Firmware
+-----------------
+
+The firmware running on the MetaWear is periodically updated by MbientLab with additional features and bug-fixes.  To update, you first call a MetaWear API which puts the device in a special bootloader mode, then use the Nordic Semiconductor `IOS-DFU-Librarly <https://github.com/NordicSemiconductor/IOS-DFU-Library>`_ to upload the new firmware.  We recommend looking at our `Sample App <https://github.com/mbientlab/Metawear-SampleiOSApp>`_ for an example on how to integrate.
+
+This is one API you can call WITHOUT being connected, there are some cases where you can't connect because the firmware is too old, but you still need to be able to update it!
+
+::
+
+    device.prepareForFirmwareUpdateAsync().success { result in
+        var selectedFirmware: DFUFirmware?
+        if result.firmwareUrl.pathExtension.caseInsensitiveCompare("zip") == .orderedSame {
+            selectedFirmware = DFUFirmware(urlToZipFile: result.firmwareUrl)
+        } else {
+            selectedFirmware = DFUFirmware(urlToBinOrHexFile: result.firmwareUrl, urlToDatFile: nil, type: .application)
+        }
+        self.initiator = DFUServiceInitiator(centralManager: result.centralManager, target: result.target)
+        let _ = self.initiator?.with(firmware: selectedFirmware!)
+        self.initiator?.forceDfu = true // We also have the DIS which confuses the DFU library
+        self.initiator?.logger = self // - to get log info
+        self.initiator?.delegate = self // - to be informed about current state and errors
+        self.initiator?.peripheralSelector = self
+        self.initiator?.progressDelegate = self // - to show progress bar
+
+        self.dfuController = self.initiator?.start()
+    }.failure { error in
+        print("Something went wrong, we should try again in 60 seconds: \(error)")
+    }
diff --git a/Docs/source/ambient_light.rst b/Docs/source/ambient_light.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 Ambient Light
 =============
@@ -14,7 +14,5 @@ There is currently nothing in the generic ``MBLAmbientLight`` class, so you need
 
 ::
 
-    if ([device.ambientLight isKindOfClass:[MBLAmbientLightLTR329 class]]) {
-        MBLAmbientLightLTR329 *ambientLightLTR329 = (MBLAmbientLightLTR329 *)device.ambientLight;
+    if let ambientLightLTR329 = device.ambientLight as? MBLAmbientLightLTR329 {
     }
-
diff --git a/Docs/source/ambientlightltr329.rst b/Docs/source/ambientlightltr329.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 AmbientLightLTR329
 ==================
@@ -12,12 +12,13 @@ This ambient light sensor has a built in timer, so you can program it directly t
 
 ::
 
-    ambientLightLTR329.gain = MBLAmbientLightLTR329Gain1X;
+    ambientLightLTR329.gain = .gain1X;
     // Have the sensor measure over 100ms
-    ambientLightLTR329.integrationTime = MBLAmbientLightLTR329Integration100ms;
+    ambientLightLTR329.integrationTime = .integration100ms;
     // Perform a new measurement each second
-    ambientLightLTR329.measurementRate = MBLAmbientLightLTR329Rate1000ms;
-    [ambientLightLTR329.periodicIlluminance startNotificationsWithHandlerAsync:^(MBLNumericData *obj, NSError *error) {
-        NSLog(@"ambient light: %f lux", obj.value.floatValue);
-    }];
-
+    ambientLightLTR329.measurementRate = .rate1000ms;
+    ambientLightLTR329.periodicIlluminance.startNotificationsAsync(handler: { (obj, error) in
+        if let obj = obj {
+            print("ambient light: \(obj.value.doubleValue) lux")
+        }
+    })
diff --git a/Docs/source/ancs.rst b/Docs/source/ancs.rst
@@ -1,4 +1,4 @@
-.. highlight:: Objective-C
+.. highlight:: swift
 
 ANCS
 ====
@@ -14,10 +14,10 @@ It's simple to have the MetaWear flash when a notification comes in.
 
 ::
 
-    MBLEvent *ancs = [device.ancs eventWithCategoryIds:MBLANCSCategoryIDAny];
-    [ancs programCommandsToRunOnEventAsync:^{
-        [device.led flashLEDColorAsync:[UIColor redColor] withIntensity:1.0];
-    }];
+    let ancs = device.ancs?.event(withCategoryIds: .any)
+    ancs?.programCommandsToRunOnEventAsync {
+        device.led?.flashColorAsync(.red, withIntensity: 1.0)
+    }
 
 Filter Notification Events
 --------------------------
@@ -26,13 +26,12 @@ You may want to be notified when you get a message from a special someone:
 
 ::
 
-    MBLEvent *ancs = [device.ancs eventWithCategoryIds:MBLANCSCategoryIDAny
-                                              eventIds:MBLANCSEventIDNotificationAdded
-                                            eventFlags:MBLANCSEventFlagAny
-                                           attributeId:MBLANCSNotificationAttributeIDTitle
-                                         attributeData:@"John Doe"];
-    [ancs programCommandsToRunOnEventAsync:^{
-        [device.led flashLEDColorAsync:[UIColor greenColor] withIntensity:1.0 numberOfFlashes:5];
-        [device.hapticBuzzer startHapticWithDutyCycleAsync:255 pulseWidth:500 completion:nil];
-    }];
-
+    let ancs = device.ancs?.event(withCategoryIds: .any,
+                                  eventIds: .notificationAdded,
+                                  eventFlags: .init(rawValue: 0),
+                                  attributeId: .title,
+                                  attributeData: "John Doe")
+    ancs?.programCommandsToRunOnEventAsync {
+        device.led?.flashColorAsync(.green, withIntensity: 1.0, numberOfFlashes: 5)
+        device.hapticBuzzer?.startHapticAsync(dutyCycle: 255, pulseWidth: 500, completion: nil)
+    }