api v3.2.0 commit

README.md

@@ -18,7 +18,7 @@ Then, add the compile element to the dependencies closure in the module's *build
 
 ```gradle
 dependencies {
-    compile 'com.mbientlab:metawear:3.1.0'
+    compile 'com.mbientlab:metawear:3.2.0'
 }
 ```
 

library/build.gradle

@@ -25,14 +25,14 @@
 apply plugin: 'com.android.library'
 
 android {
-    compileSdkVersion 25
-    buildToolsVersion "25.0.2"
+    compileSdkVersion 26
+    buildToolsVersion "26.0.2"
 
     defaultConfig {
         minSdkVersion 18
-        targetSdkVersion 25
-        versionCode 51
-        versionName "3.1.0"
+        targetSdkVersion 26
+        versionCode 52
+        versionName "3.2.0"
     }
     buildTypes {
         release {

library/src/main/java/com/mbientlab/metawear/AnonymousRoute.java

@@ -0,0 +1,25 @@
+package com.mbientlab.metawear;
+
+/**
+ * Pared down variant of the {@link Route} interface that only has one {@link Subscriber}.  This
+ * interface can be used to retrieve logged data from a board that was not programmed by the current
+ * device.
+ * @author Eric Tsai
+ */
+public interface AnonymousRoute {
+    /**
+     * String identifying the data producer chain the subscriber is receiving data from
+     * @return String identifying the data chain
+     */
+    String identifier();
+    /**
+     * Subscribe to the data produced by this chain
+     * @param subscriber    Subscriber implementation to handle the received data
+     */
+    void subscribe(Subscriber subscriber);
+    /**
+     * Sets the environment values  passed into the {@link Subscriber#apply(Data, Object...) apply} function
+     * @param env   Environment values to use with the subscriber
+     */
+    void setEnvironment(Object ... env);
+}

library/src/main/java/com/mbientlab/metawear/MetaWearBoard.java

@@ -24,10 +24,13 @@
 
 package com.mbientlab.metawear;
 
+import org.json.JSONObject;
+
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.util.Map;
 import java.util.UUID;
 
 import bolts.Task;
@@ -60,7 +63,7 @@ public interface MetaWearBoard {
     Model getModel();
     /**
      * Same behavior as {@link #getModel()} except the returned value is a friendly name rather than an enum
-     * @return Board model as string
+     * @return Board model as string, null if unable to determine
      */
     String getModelString();
     /**
@@ -84,6 +87,14 @@ public interface MetaWearBoard {
      * @return Task holding the device information
      */
     Task<DeviceInformation> readDeviceInformationAsync();
+
+    /**
+     * Downloads the specific firmware release for the board to your local device.  You must be connected to the
+     * board before calling this function.
+     * @param version Firmware revision to download
+     * @return Task holding the file pointing to where the downloaded firmware resides on the local device
+     */
+    Task<File> downloadFirmwareAsync(String version);
     /**
      * Downloads the latest firmware release for the board to your local device.  You must be connected to the
      * board before calling this function.
@@ -166,6 +177,11 @@ interface Module { }
      */
     <T extends Module> T getModuleOrThrow(Class<T> moduleClass) throws UnsupportedModuleException;
 
+    /**
+     * Reads the current state of the board and creates anonymous routes based on what data is being logged
+     * @return Task that is completed when the anonymous routes are created
+     */
+    Task<AnonymousRoute[]> createAnonymousRoutesAsync();
     /**
      * Retrieves a route
      * @param id    Numerical ID to look up
@@ -178,6 +194,7 @@ interface Module { }
      * @return Observer corresponding to the specified ID, null if none can be found
      */
     Observer lookupObserver(int id);
+
     /**
      * Removes all routes and resources allocated on the board (observers, data processors, timers, and loggers)
      */
@@ -207,4 +224,12 @@ interface Module { }
      * @throws ClassNotFoundException Class of a serialized object cannot be found
      */
     void deserialize(InputStream ins) throws IOException, ClassNotFoundException;
+
+    /**
+     * Queries all info registers.  If the task times out, you can run the task again using the partially
+     * completed result from the previous execution so the function does not need to query all modules again.
+     * @param partial    Map of previously queries module info results, set to null to query all modules
+     * @return Task that is completed once the query is completed
+     */
+    Task<JSONObject> dumpModuleInfo(JSONObject partial);
 }

library/src/main/java/com/mbientlab/metawear/Route.java

@@ -29,16 +29,24 @@
  * @author Eric Tsai
  */
 public interface Route {
+    /**
+     * Generates a string identifying the data producer chain the subscriber is receiving data from.
+     * This value can be matched with the output from {@link AnonymousRoute#identifier()} if syncing data
+     * using the {@link AnonymousRoute} interface.
+     * @param pos    Numerical position of the subscriber to interact with, starting from 0
+     * @return String identifying the data chain, null if <code>param</code> value is out of bounds
+     */
+    String generateIdentifier(int pos);
     /**
      * Sets the environment values  passed into the {@link Subscriber#apply(Data, Object...) apply} function
-     * @param pos   Numerical position of the subscriber, starting from 0
+     * @param pos   Numerical position of the subscriber to interact with, starting from 0
      * @param env   Environment values to use with the subscriber
      * @return True if operation succeeded, false otherwise
      */
     boolean setEnvironment(int pos, Object ... env);
     /**
      * Quiets the stream the subscriber is listening to, does nothing if the subscriber is handling log data
-     * @param pos   Numerical position of the subscriber  to interact with, starting at 0
+     * @param pos   Numerical position of the subscriber to interact with, starting at 0
      * @return True if operation succeeded, false otherwise
      */
     boolean unsubscribe(int pos);

library/src/main/java/com/mbientlab/metawear/TaskTimeoutException.java

@@ -0,0 +1,25 @@
+package com.mbientlab.metawear;
+
+import java.util.concurrent.TimeoutException;
+
+/**
+ * Variant of the {@link TimeoutException} class that contains a partial result of the task
+ * @author Eric Tsai
+ */
+public class TaskTimeoutException extends TimeoutException {
+    private static final long serialVersionUID = -1265719967367246950L;
+
+    /** Partial result of the task */
+    public final Object partial;
+
+    /**
+     * Creates an exception with the given message and partial result
+     * @param message    Message to accompany the exception
+     * @param partial    Partial result of the task
+     */
+    public TaskTimeoutException(String message, Object partial) {
+        super(message);
+
+        this.partial = partial;
+    }
+}

library/src/main/java/com/mbientlab/metawear/UnsupportedModuleException.java

@@ -33,7 +33,7 @@ public class UnsupportedModuleException extends Exception {
 
     /**
      * Creates an exception with the given message
-     * @param msg    Data to accompany the exception
+     * @param msg    Message to accompany the exception
      */
     public UnsupportedModuleException(String msg) {
         super(msg);