Merge pull request #308 from dronekit/release-1.4.3

Release 1.4.3

Author: m4gr3d

ClientLib/build.gradle

@@ -3,11 +3,12 @@ apply plugin: 'com.android.library'
 ext {
     VERSION_MAJOR = 2
     VERSION_MINOR = 6
-    VERSION_PATCH = 6
+    VERSION_PATCH = 8
     VERSION_BUILD = 0
+    VERSION_SUFFIX = "release"
 
     PUBLISH_ARTIFACT_ID = 'dronekit-android'
-    PUBLISH_VERSION = generateVersionName("", VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH)
+    PUBLISH_VERSION = generateVersionName("", VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH, VERSION_SUFFIX)
     PUBLISH_VERSION_CODE = computeVersionCode(VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH, VERSION_BUILD)
     PROJECT_DESCRIPTION = "Android DroneKit client library."
     PROJECT_LABELS = ['3DR', '3DR Services', 'DroneAPI', 'Android', 'DroneKit']

ClientLib/src/main/AndroidManifest.xml

@@ -1,6 +1,8 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
           package="com.o3dr.android.client">
 
+    <uses-permission android:name="android.permission.INTERNET"/>
+
     <application>
         <activity
             android:name=".utils.InstallServiceDialog"

ClientLib/src/main/java/com/o3dr/android/client/Drone.java

@@ -233,17 +233,23 @@ public void post(Runnable action) {
         handler.post(action);
     }
 
+    /**
+     * Reset the vehicle flight timer.
+     */
     public void resetFlightTimer() {
         elapsedFlightTime = 0;
         startTime = SystemClock.elapsedRealtime();
     }
 
-    public void stopTimer() {
+    private void stopTimer() {
         // lets calc the final elapsed timer
         elapsedFlightTime += SystemClock.elapsedRealtime() - startTime;
         startTime = SystemClock.elapsedRealtime();
     }
 
+    /**
+     * @return Vehicle flight time in seconds.
+     */
     public long getFlightTime() {
         State droneState = getAttribute(AttributeType.STATE);
         if (droneState != null && droneState.isFlying()) {
@@ -682,6 +688,10 @@ public void loadWaypoints() {
         MissionApi.getApi(this).loadWaypoints();
     }
 
+    public Handler getHandler(){
+        return handler;
+    }
+
     void notifyDroneConnectionFailed(final ConnectionResult result) {
         if (droneListeners.isEmpty())
             return;

ClientLib/src/main/java/com/o3dr/android/client/apis/Api.java

@@ -1,6 +1,7 @@
 package com.o3dr.android.client.apis;
 
 import com.o3dr.android.client.Drone;
+import com.o3dr.services.android.lib.model.AbstractCommandListener;
 
 import java.util.concurrent.ConcurrentHashMap;
 
@@ -36,4 +37,22 @@ protected static <T extends Api> T getApi(Drone drone, ConcurrentHashMap<Drone,
 
         return apiInstance;
     }
+
+    protected static void postSuccessEvent(final AbstractCommandListener listener){
+        if(listener != null){
+            listener.onSuccess();
+        }
+    }
+
+    protected static void postErrorEvent(int error, AbstractCommandListener listener){
+        if(listener != null){
+            listener.onError(error);
+        }
+    }
+
+    protected static void postTimeoutEvent(AbstractCommandListener listener){
+        if(listener != null){
+            listener.onTimeout();
+        }
+    }
 }

ClientLib/src/main/java/com/o3dr/android/client/apis/CameraApi.java

@@ -0,0 +1,94 @@
+package com.o3dr.android.client.apis;
+
+import android.os.Bundle;
+import android.support.annotation.NonNull;
+import android.view.Surface;
+
+import com.o3dr.android.client.Drone;
+import com.o3dr.services.android.lib.drone.attribute.error.CommandExecutionError;
+import com.o3dr.services.android.lib.model.AbstractCommandListener;
+import com.o3dr.services.android.lib.model.action.Action;
+
+import java.util.concurrent.ConcurrentHashMap;
+
+import static com.o3dr.services.android.lib.drone.action.CameraActions.ACTION_START_VIDEO_STREAM;
+import static com.o3dr.services.android.lib.drone.action.CameraActions.ACTION_STOP_VIDEO_STREAM;
+import static com.o3dr.services.android.lib.drone.action.CameraActions.EXTRA_VIDEO_DISPLAY;
+import static com.o3dr.services.android.lib.drone.action.CameraActions.EXTRA_VIDEO_PROPS_UDP_PORT;
+import static com.o3dr.services.android.lib.drone.action.CameraActions.EXTRA_VIDEO_TAG;
+import static com.o3dr.services.android.lib.drone.action.CameraActions.EXTRA_VIDEO_PROPERTIES;
+
+/**
+ * Provides support to control generic camera functionality
+ * Created by Fredia Huya-Kouadio on 10/11/15.
+ *
+ * @since 2.6.8
+ */
+public class CameraApi extends Api {
+
+    private static final ConcurrentHashMap<Drone, CameraApi> apiCache = new ConcurrentHashMap<>();
+    private static final Builder<CameraApi> apiBuilder = new Builder<CameraApi>() {
+        @Override
+        public CameraApi build(Drone drone) {
+            return new CameraApi(drone);
+        }
+    };
+
+    /**
+     * Used to specify the udp port from which to access the streamed video.
+     */
+    public static final String VIDEO_PROPS_UDP_PORT = EXTRA_VIDEO_PROPS_UDP_PORT;
+
+    /**
+     * Retrieves a camera api instance
+     *
+     * @param drone
+     * @return
+     */
+    public static CameraApi getApi(final Drone drone) {
+        return getApi(drone, apiCache, apiBuilder);
+    }
+
+    private final Drone drone;
+
+    private CameraApi(Drone drone) {
+        this.drone = drone;
+    }
+
+    /**
+     * Attempt to grab ownership and start the video stream from the connected drone. Can fail if
+     * the video stream is already owned by another client.
+     *
+     * @param surface  Surface object onto which the video is decoded.
+     * @param tag      Video tag.
+     * @param videoProps Non-null video properties. @see VIDEO_PROPS_UDP_PORT
+     * @param listener Register a callback to receive update of the command execution status.
+     * @since 2.6.8
+     */
+    public void startVideoStream(@NonNull final Surface surface, final String tag, @NonNull Bundle videoProps, final AbstractCommandListener listener) {
+        if (surface == null || videoProps == null) {
+            postErrorEvent(CommandExecutionError.COMMAND_FAILED, listener);
+            return;
+        }
+
+        final Bundle params = new Bundle();
+        params.putParcelable(EXTRA_VIDEO_DISPLAY, surface);
+        params.putString(EXTRA_VIDEO_TAG, tag);
+        params.putBundle(EXTRA_VIDEO_PROPERTIES, videoProps);
+
+        drone.performAsyncActionOnDroneThread(new Action(ACTION_START_VIDEO_STREAM, params), listener);
+    }
+
+    /**
+     * Stop the video stream from the connected drone, and release ownership.
+     *
+     * @param tag      Video tag.
+     * @param listener Register a callback to receive update of the command execution status.
+     * @since 2.6.8
+     */
+    public void stopVideoStream(final String tag, final AbstractCommandListener listener) {
+        final Bundle params = new Bundle();
+        params.putString(EXTRA_VIDEO_TAG, tag);
+        drone.performAsyncActionOnDroneThread(new Action(ACTION_STOP_VIDEO_STREAM, params), listener);
+    }
+}

ClientLib/src/main/java/com/o3dr/android/client/apis/ControlApi.java

@@ -1,14 +1,19 @@
 package com.o3dr.android.client.apis;
 
 import android.os.Bundle;
+import android.support.annotation.IntDef;
 
 import com.o3dr.android.client.Drone;
 import com.o3dr.services.android.lib.coordinate.LatLong;
 import com.o3dr.services.android.lib.drone.attribute.AttributeType;
+import com.o3dr.services.android.lib.drone.attribute.error.CommandExecutionError;
+import com.o3dr.services.android.lib.drone.property.Attitude;
 import com.o3dr.services.android.lib.drone.property.Gps;
 import com.o3dr.services.android.lib.model.AbstractCommandListener;
 import com.o3dr.services.android.lib.model.action.Action;
 
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.util.concurrent.ConcurrentHashMap;
 
 import static com.o3dr.services.android.lib.drone.action.ControlActions.ACTION_DO_GUIDED_TAKEOFF;
@@ -23,16 +28,25 @@
 import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_VELOCITY_Y;
 import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_VELOCITY_Z;
 import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_YAW_CHANGE_RATE;
-import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_YAW_IS_CLOCKWISE;
 import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_YAW_IS_RELATIVE;
 import static com.o3dr.services.android.lib.drone.action.ControlActions.EXTRA_YAW_TARGET_ANGLE;
 
 /**
  * Provides access to the vehicle control functionality.
+ *
+ * Use of this api might required the vehicle to be in a specific flight mode (i.e: GUIDED)
+ *
  * Created by Fredia Huya-Kouadio on 9/7/15.
  */
 public class ControlApi extends Api {
 
+    public static final int EARTH_NED_COORDINATE_FRAME = 0;
+    public static final int VEHICLE_COORDINATE_FRAME = 1;
+
+    @IntDef({EARTH_NED_COORDINATE_FRAME, VEHICLE_COORDINATE_FRAME})
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface CoordinateFrame{}
+
     private static final ConcurrentHashMap<Drone, ControlApi> apiCache = new ConcurrentHashMap<>();
     private static final Builder<ControlApi> apiBuilder = new Builder<ControlApi>() {
         @Override
@@ -110,32 +124,67 @@ public void climbTo(double altitude) {
     /**
      * Instructs the vehicle to turn to the specified target angle
      * @param targetAngle Target angle in degrees [0-360], with 0 == north.
-     * @param turnSpeed Speed during turn in degrees per second
-     * @param isClockwise True for clockwise turn, false for counter clockwise turn
+     * @param turnRate Turning rate normalized to the range [-1.0f, 1.0f]. Positive values for clockwise turns, and negative values for counter-clockwise turns.
      * @param isRelative True is the target angle is relative to the current vehicle attitude, false otherwise if it's absolute.
      * @param listener Register a callback to receive update of the command execution state.
      */
-    public void turnTo(float targetAngle, float turnSpeed, boolean isClockwise, boolean isRelative, AbstractCommandListener listener){
+    public void turnTo(float targetAngle, float turnRate, boolean isRelative, AbstractCommandListener listener){
+        if(!isWithinBounds(targetAngle, 0, 360) || !isWithinBounds(turnRate, -1.0f, 1.0f)){
+            postErrorEvent(CommandExecutionError.COMMAND_FAILED, listener);
+            return;
+        }
+
         Bundle params = new Bundle();
         params.putFloat(EXTRA_YAW_TARGET_ANGLE, targetAngle);
-        params.putFloat(EXTRA_YAW_CHANGE_RATE, turnSpeed);
-        params.putBoolean(EXTRA_YAW_IS_CLOCKWISE, isClockwise);
+        params.putFloat(EXTRA_YAW_CHANGE_RATE, turnRate);
         params.putBoolean(EXTRA_YAW_IS_RELATIVE, isRelative);
         drone.performAsyncActionOnDroneThread(new Action(ACTION_SET_CONDITION_YAW, params), listener);
     }
 
-    /**
-     * Set the vehicle velocity vector.
-     * @param vx x velocity in meter / s
-     * @param vy y velocity in meter / s
-     * @param vz z velocity in meter / s
-     * @param listener Register a callback to receive update of the command execution state.
-     */
-    public void setVelocity(float vx, float vy, float vz, AbstractCommandListener listener){
+    private void moveAtVelocity(float vx, float vy, float vz, AbstractCommandListener listener){
         Bundle params = new Bundle();
         params.putFloat(EXTRA_VELOCITY_X, vx);
         params.putFloat(EXTRA_VELOCITY_Y, vy);
         params.putFloat(EXTRA_VELOCITY_Z, vz);
         drone.performAsyncActionOnDroneThread(new Action(ACTION_SET_VELOCITY, params), listener);
     }
+
+    /**
+     * Move the vehicle along the specified velocity vector.
+     *
+     * @param referenceFrame Reference frame to use. Can be one of
+     *                       {@link #EARTH_NED_COORDINATE_FRAME},
+     *                       {@link #VEHICLE_COORDINATE_FRAME}
+     *
+     * @param vx             x velocity normalized to the range [-1.0f, 1.0f].
+     * @param vy             y velocity normalized to the range [-1.0f, 1.0f].
+     * @param vz             z velocity normalized to the range [-1.0f, 1.0f].
+     * @param listener       Register a callback to receive update of the command execution state.
+     */
+    public void moveAtVelocity(@CoordinateFrame int referenceFrame, float vx, float vy, float vz, AbstractCommandListener listener){
+        if(!isWithinBounds(vx, -1f, 1f) || !isWithinBounds(vy, -1f, 1f) || !isWithinBounds(vz, -1f, 1f)){
+            postErrorEvent(CommandExecutionError.COMMAND_FAILED, listener);
+            return;
+        }
+
+        float projectedX = vx;
+        float projectedY = vy;
+
+        if(referenceFrame == VEHICLE_COORDINATE_FRAME) {
+            Attitude attitude = drone.getAttribute(AttributeType.ATTITUDE);
+            double attitudeInRad = Math.toRadians(attitude.getYaw());
+
+            final double cosAttitude = Math.cos(attitudeInRad);
+            final double sinAttitude = Math.sin(attitudeInRad);
+
+            projectedX = (float) (vx * cosAttitude) - (float) (vy * sinAttitude);
+            projectedY = (float) (vx * sinAttitude) + (float) (vy * cosAttitude);
+        }
+
+        moveAtVelocity(projectedX, projectedY, vz, listener);
+    }
+
+    private static boolean isWithinBounds(float value, float lowerBound, float upperBound){
+        return value <= upperBound && value >= lowerBound;
+    }
 }

ClientLib/src/main/java/com/o3dr/android/client/apis/GimbalApi.java

@@ -132,6 +132,7 @@ public void onError(int error){
     /**
      * Disables control of the gimbal. After calling this method, no call to {@link GimbalApi#updateGimbalOrientation(float, float, float, GimbalOrientationListener)}
      * will be allowed.
+     * @since 2.5.0
      * @param listener non-null GimbalStatusListener callback.
      */
     public void stopGimbalControl(final GimbalOrientationListener listener){
@@ -148,8 +149,12 @@ public void run() {
             return;
         }
 
+        gimbalListeners.remove(listener);
+
         //Reset the gimbal mount to the default.
-        drone.performAsyncActionOnDroneThread(new Action(ACTION_RESET_GIMBAL_MOUNT_MODE, null), new SimpleCommandListener(){
+        Bundle params = new Bundle(1);
+        params.putInt(GIMBAL_MOUNT_MODE, MAV_MOUNT_MODE.MAV_MOUNT_MODE_RC_TARGETING);
+        drone.performAsyncActionOnDroneThread(new Action(ACTION_SET_GIMBAL_MOUNT_MODE, params), new SimpleCommandListener(){
            @Override
             public void onTimeout(){
                listener.onGimbalOrientationCommandError(CommandExecutionError.COMMAND_FAILED);