Mergve Swerve.1.5.0 branch into master

Former-commit-id: 62e4cd4caded722512111f7157678ef3a697a539
Former-commit-id: c511fd2

FtcRobotController/src/main/AndroidManifest.xml

@@ -2,8 +2,8 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
           xmlns:tools="http://schemas.android.com/tools"
           package="com.qualcomm.ftcrobotcontroller"
-          android:versionCode="6"
-          android:versionName="1.5.2">
+          android:versionCode="7"
+          android:versionName="1.7.1">
 
 
   <uses-permission

README.md

@@ -5,11 +5,13 @@ The purpose of our library is to augment the robot controller runtime library fr
 in order to simplify programming for FTC teams. The central aim here is not to change what's there,
 just to make it better. The library is a drop-in replacement: if your code works with the FTC HQ
 release, it will work with the Swerve library, but you can also take advantage of new things.
-Please consult the [GitHub release notes](https://github.com/SwerveRobotics/ftc_app/releases) 
+**Please** consult the [GitHub release notes](https://github.com/SwerveRobotics/ftc_app/releases)
 for details regarding a given release. You might also want to check out our related project, the 
 Swerve Robotics Tools Suite, also [here](https://github.com/SwerveRobotics/tools) on GitHub. 
 
-Notable features of the Swerve Robotics FTC Library include the following.
+Notable features of the Swerve Robotics FTC Library include the following. Note: the 'Easy' controllers
+are now part of the core SDK. The functionality is as described here, but they are now *always*
+in use, irrespective of the flavor of opmode.
 
 ### Easy Legacy Motor Controller
 **EasyLegacyMotorController** is a replacement for the stock DCMotorController implementation
@@ -18,10 +20,6 @@ switch motors from read mode to write mode and back again and the attendant comp
 loop counting, or waiting for hardware cycles that that requires. Just call `setPower()`, `getPosition()`,
 or whatever other motor methods you need to use, and the right things happen under the covers.
 
-EasyLegacyMotorController can be used from any OpMode, or indeed any thread. In SynchronousOpModes, 
-EasyLegacyMotorController is used automatically; in other OpModes it can be used by calling 
-`ClassFactory.createEasyMotorController()`.
-
 ### Easy Modern Motor & Servo Controller and Easy Legacy Servo Controller
 In a conceptually similar way, alternate implementations for modern motor and servo controllers and
 for legacy servo controllers is also provided. The API simplifications for these controllers are less dramatic
@@ -33,11 +31,7 @@ of that change. You don't have to poll to see whether the mode change has taken
 and then immediately change to run with encoders? Perfectly fine. It just works. Additionally, a handful 
 of bug fixes is included. For example, `Servo.getPosition()` is now functionally useful.
 
-These easy controllers can be used from any OpMode or any thread. In SynchronousOpModes, they are used
-automatically; in other OpModes, they can be used by calling `ClassFactory.createEasyMotorController()`
-or `ClassFactory.createEasyServoController()` respectively.
-
-### Alternate OpMode Registration 
+### Alternate OpMode Registration
 The library has an **alternate OpMode registration mechanism** (the old `FtcOpModeRegister.register()` still works too)
 that allows you to register your own OpModes simply by decorating them with `@TeleOp` or `@Autonomous` annotations.
 This helps promote clean living and easier integration of library updates over time by avoiding
@@ -73,17 +67,15 @@ soon as possible. The enhanced telemetry class can be used both by synchronous a
 opmodes, but is used automatically in SynchronousOpModes.
 
 ### Easy I2C Programming
-The library contains an **I2cDeviceClient** class that wraps I2cDevice instances and makes them easy to use by handling
-read-vs-write mode switches and attendant waits automatically and transparently. Just call `read8()`
-or `write8()` (and friends) to read and write device registers and the rest is taken care of.
-With the I2C register map you get from the sensor manufacturer in hand, it's now just dead easy to
-write your own code to talk to new I2C devices. Note that I2cDeviceClient is also decoupled
-from SynchronousOpMode, in that one need not be using SynchronousOpMode to use I2cDeviceClient.
-However as some operations are lengthy, a worker thread is suggested in that case in order to avoid
-long-running operations on the `loop()` thread.
+The library (indeed, now the core SDK) contains an **I2cDeviceSynch** class that wraps I2cDevice instances
+and makes them easy to use by handling read-vs-write mode switches and attendant waits automatically and
+transparently. Just call `read8()` or `write8()` (and friends) to read and write device registers and the
+rest is taken care of. With the I2C register map you get from the sensor manufacturer in hand, it's now
+just dead easy to write your own code to talk to new I2C devices. I2cDeviceSynch can be used from any
+flavor of OpMode.
 
 ### AdaFruit IMU Support
-The library contains a class that is built on I2cDeviceClient that provides a semantic interface to the **Bosch BNO055 absolute
+The library contains a class that is built on I2cDeviceSynch that provides a semantic interface to the **Bosch BNO055 absolute
 position sensor**, allowing teams to make easy use of the [AdaFruit inertial motion unit (IMU)](http://www.adafruit.com/products/2472)
 which incorporates that sensor module. Features of this sensor include a gyro that does rate
 integration in hardware to provide robust and accurate angular position indications, and a
@@ -137,9 +129,14 @@ Migrating from LinearOpMode to SyncronousOpMode is easy, usually simply involvin
 * optionally removing `waitOneFullHardwareCycle()` calls, as they are no longer necessary
 
 The Swerve Library now appears to be quite stable and functional. Our own teams are actively
-developing their competition code using it. It currently is synchronized to the release from
-FTC HQ that was published January 4th, 2016 (version 1.5). Please be sure to **update your driver station**
-app to the latest-available version.
+developing their competition code using it. It currently is synchronized to the beta release from
+FTC HQ that was published in March, 2016 (version 1.7).
+
+Please be sure to **update your driver station** app to the latest-available version by side-loading
+the .APK from the doc\apk directory. Side loading can be accomplished by any of several means. See
+the ADB command 'install' command, for example (ADB is found in the Android SDK). Alternately, any
+of several PC applications (such as http://apkinstaller.com/) and Android APK Installer apps (found
+in the Play Store) can be used. The thread here (http://ftcforum.usfirst.org/showthread.php?6101-FTC-Beta-Branch&p=24750#post24750) might also be helpful.
 
 ## Installing the Library
 

SwerveRoboticsLibrary/src/main/java/org/swerverobotics/library/ClassFactory.java

@@ -2,6 +2,8 @@
 
 import com.qualcomm.robotcore.eventloop.opmode.OpMode;
 import com.qualcomm.robotcore.hardware.*;
+
+import org.swerverobotics.library.examples.SynchColorDemo;
 import org.swerverobotics.library.interfaces.*;
 import org.swerverobotics.library.internal.*;
 import java.util.*;
@@ -21,14 +23,17 @@ public final class ClassFactory
     //----------------------------------------------------------------------------------------------
 
     /**
+     * @deprecated This functionality is now included in the core SDK; the implementation of this
+     *             method is now effectively a nop.
+     *
      * If the provided motors are using a legacy motor controller, createEasyMotorController swaps
      * that controller out and installs an alternate 'EasyLegacyMotorController' DCMotorController
      * implementation for the duration of the OpMode. If the motors are using a modern motor controller,
      * an analogous swap to an 'EasyModernMotorController' is made. If a matrix motor controller is in
      * use, this function has no effect. The APIs to easy legacy and modern motor controllers
      * are <em>identical</em>, which helps simplify programming.
      *
-     * <p>EasyLegacyMotorController is implemented on top of an {@link II2cDeviceClient} instance
+     * <p>EasyLegacyMotorController is implemented on top of an {@link I2cDeviceSynch} instance
      * which completely handles all the complexities of read vs write mode switching and the
      * like, allowing the logic inside the controller itself to be extraordinarily simple.
      * In particular, the manual mode switching and loop() counting necessary with the stock
@@ -60,30 +65,31 @@ public final class ClassFactory
      *
      * @see org.swerverobotics.library.examples.SynchMotorLoopPerf
      */
+    @Deprecated
     public static DcMotorController createEasyMotorController(OpMode opmodeContext, DcMotor motor1, DcMotor motor2)
         {
         DcMotorController target = motor1==null ? null : motor1.getController();
 
         if (motor2 != null && target != null && motor2.getController()!=target)
             throw new IllegalArgumentException("motors do not share the same controller");
 
-        if (MemberUtil.isLegacyMotorController(target))
-            return EasyLegacyMotorController.create(opmodeContext, target, motor1, motor2);
-
-        else if (MemberUtil.isModernMotorController(target))
-            return EasyModernMotorController.create(opmodeContext, target, motor1, motor2);
-
-        else
-            return null;
+        return target;
         }
 
+    /**
+     * @deprecated Deprecated because of a poor choice of API name: insufficiently general.
+     * @see #createEasyMotorController(OpMode, DcMotor, DcMotor)
+     */
     @Deprecated
     public static void createEasyLegacyMotorController(OpMode opmodeContext, DcMotor motor1, DcMotor motor2)
         {
         createEasyMotorController(opmodeContext, motor1, motor2);
         }
 
     /**
+     * @deprecated This functionality is now included in the core SDK; the implementation of this
+     *             method is now effectively a nop.
+     *
      * Creates an alternate 'easy' implementation of the controller for the indicated collection
      * of servos, which must all share the same controller, and must be <em>all</em> the servos
      * which are found on that controller.
@@ -100,6 +106,7 @@ public static void createEasyLegacyMotorController(OpMode opmodeContext, DcMotor
      *
      * @see #createEasyMotorController(OpMode, DcMotor, DcMotor)
      */
+    @Deprecated
     public static ServoController createEasyServoController(OpMode opmodeContext, Collection<Servo> servos)
         {
         if (servos != null && !servos.isEmpty())
@@ -113,14 +120,7 @@ else if (controller != servo.getController())
                     throw new IllegalArgumentException("not all servos share the same controller");
                 }
 
-            if (MemberUtil.isModernServoController(controller))
-                return EasyModernServoController.create(opmodeContext, controller, servos);
-
-            else if (MemberUtil.isLegacyServoController(controller))
-                return EasyLegacyServoController.create(opmodeContext, controller, servos);
-
-            else
-                return null;
+            return controller;
             }
         else
             throw new IllegalArgumentException("no servos provided");
@@ -190,7 +190,7 @@ public static IBNO055IMU createAdaFruitBNO055IMU(I2cDevice i2cDevice, IBNO055IMU
      * @param i2cDevice     the robot controller runtime object representing the sensor
      * @param parameters    the parameters with which the sensor should be initialized
      * @return              the interface to the instantiated sensor object. This object also
-     *                      supports the II2cDeviceClientUser interface, which can be useful
+     *                      supports the I2cDeviceSynchUser interface, which can be useful
      *                      for debugging.
      * @see #createAdaFruitBNO055IMU(OpMode, I2cDevice)
      */
@@ -211,7 +211,7 @@ public static IBNO055IMU createAdaFruitBNO055IMU(OpMode opmodeContext, I2cDevice
      *
      * @see #createSwerveColorSensor(OpMode, I2cController, int, int, SENSOR_FLAVOR)
      * @see org.swerverobotics.library.examples.LinearColorDemo
-     * @see org.swerverobotics.library.examples.SyncColorDemo
+     * @see SynchColorDemo
      */
     public static ColorSensor createSwerveColorSensor(OpMode opmodeContext, ColorSensor target)
         {
@@ -230,7 +230,7 @@ public static ColorSensor createSwerveColorSensor(OpMode opmodeContext, ColorSen
      *
      * @see #createSwerveColorSensor(OpMode, ColorSensor)
      * @see org.swerverobotics.library.examples.LinearColorDemo
-     * @see org.swerverobotics.library.examples.SyncColorDemo
+     * @see SynchColorDemo
      */
     public static ColorSensor createSwerveColorSensor(OpMode opmodeContext, I2cController controller, int port, int i2cAddr8Bit, ClassFactory.SENSOR_FLAVOR flavor)
         {
@@ -243,62 +243,63 @@ public static ColorSensor createSwerveColorSensor(OpMode opmodeContext, I2cContr
     //----------------------------------------------------------------------------------------------
 
     /**
-     * Creates an II2cDevice interface around an I2cDevice.
+     * Creates an independent I2cDevice implementation using information from an existing
+     * I2cDevice as connectivity information. This is deprecated, as the underlying SDK now
+     * has I2cDevice as an interface separate from implementation, so there's no need to have
+     * our own here.
      *
      * @param i2cDevice the device to wrap
      * @return          the II2cDevice wrapping
+     *
+     * @deprecated I2cDevice, as defined in the SDK, is now an interface, not an implementation, so
+     *             this API is no longer necessary.
      */
-    public static II2cDevice createI2cDevice(I2cDevice i2cDevice)
+    @Deprecated
+    public static I2cDevice createI2cDevice(I2cDevice i2cDevice)
         {
-        I2cController i2cController = i2cDevice.getController();
+        I2cController i2cController = i2cDevice.getI2cController();
         int port                    = i2cDevice.getPort();
         return createI2cDevice(i2cController, port);
         }
 
     /**
-     * Creates an II2Device instance on a specific port on an I2cDeviceController
+     * Creates an I2Device instance on a specific port on an I2cDeviceController
      *
      * @param i2cController the controller on which to create the device
      * @param port          the port on the controller to use
      * @return              the created II2cDevice instance
      */
-    public static II2cDevice createI2cDevice(I2cController i2cController, int port)
+    public static I2cDevice createI2cDevice(I2cController i2cController, int port)
         {
-        return new I2cDeviceOnI2cDeviceController(i2cController, port);
+        return new I2cDeviceImpl(i2cController, port);
         }
 
     /**
-     * Create a new II2cDeviceClient on an I2cDevice instance. The client is initially disengaged,
-     * and must be engaged before use.
+     * Create a new I2cDeviceSynch on an I2cDevice instance. The new device is initially
+     * disengaged, and must be engaged before use. Closing the returned object does *not*
+     * automatically close the underlying I2cDevice.
      *
-     * @param opmodeContext         the OpMode within which the creation is taking place
      * @param i2cDevice             the II2cDevice to wrap
      * @param i2cAddr8Bit           the I2C address at which the client is to communicate
-     * @param closeOnOpModeStop     if true, then when the OpMode stops, the client will automatically close
-     * @return                      the newly instantiated I2c device client
-     * @see II2cDeviceClient#engage()
+     * @return                      the newly instantiated device
+     * @see Engagable#engage()
      */
-    public static II2cDeviceClient createI2cDeviceClient(OpMode opmodeContext, I2cDevice i2cDevice, int i2cAddr8Bit, boolean closeOnOpModeStop)
+    public static I2cDeviceSynch createI2cDeviceSynch(I2cDevice i2cDevice, int i2cAddr8Bit)
         {
-        II2cDevice ii2cDevice = createI2cDevice(i2cDevice);
-        return createI2cDeviceClient(opmodeContext, ii2cDevice, i2cAddr8Bit, closeOnOpModeStop);
+        return new I2cDeviceSynchImpl(i2cDevice, i2cAddr8Bit, false);
         }
 
-
     /**
-     * Create a new II2cDeviceClient on an II2cDevice instance. The client is initially
-     * disengaged, and must be engaged before use.
-     *
-     * @param opmodeContext         the OpMode within which the creation is taking place
-     * @param i2cDevice             the II2cDevice to wrap
-     * @param i2cAddr8Bit           the I2C address at which the client is to communicate
-     * @param closeOnOpModeStop     if true, then when the OpMode stops, the client will automatically close
-     * @return                      the newly instantiated I2c device client
-     * @see II2cDeviceClient#engage()
+     * @deprecated The creation API has been renamed to match changes in interface nomenclature.
+     *             Use {@link #createI2cDeviceSynch(I2cDevice, int) createI2cDeviceSynch()} instead.
+     * @see #createI2cDeviceSynch(I2cDevice, int)
      */
-    public static II2cDeviceClient createI2cDeviceClient(OpMode opmodeContext, II2cDevice i2cDevice, int i2cAddr8Bit, boolean closeOnOpModeStop)
+    @Deprecated
+    public static I2cDeviceSynch createI2cDeviceClient(OpMode opmodeContext, I2cDevice i2cDevice, int i2cAddr8Bit, boolean closeOnOpModeStop)
         {
-        return new I2cDeviceClient(opmodeContext, i2cDevice, i2cAddr8Bit, closeOnOpModeStop);
+        if (closeOnOpModeStop)
+            throw new UnsupportedOperationException("support for auto-closing on opmode stop has been removed");
+        return createI2cDeviceSynch(i2cDevice, i2cAddr8Bit);
         }
 
     //----------------------------------------------------------------------------------------------