update guided mode instructions for setting speed in positional mode

Author: hamishwillee

docs/examples/guided-set-speed-yaw-demo.rst

@@ -200,7 +200,6 @@ The functions sending immediate commands are:
 
 * :ref:`condition_yaw() <guided_mode_copter_set_yaw>` 
 * :ref:`set_roi(location) <guided_mode_copter_set_roi>`
-* :ref:`set_speed(speed) <guided_mode_copter_set_speed>`
 
 The example uses a number functions to convert global locations co-ordinates (decimal degrees) into local 
 coordinates relative to the vehicle (in metres). These are :ref:`described in the guide <guided_mode_copter_useful_conversion_functions>`.

docs/guide/copter/guided_mode.rst

@@ -58,7 +58,27 @@ to indicate when the vehicle has reached its destination. Developers can use eit
 :ref:`measure proximity to the target <example_guided_mode_goto_convenience>` to give the vehicle an 
 opportunity to reach its destination. The :ref:`example-guided-mode-setting-speed-yaw` shows both approaches.
 
-When moving the vehicle you can send a separate command to :ref:`control the speed <guided_mode_copter_set_speed>` (and other vehicle behaviour).
+You can optionally set the target movement speed using the function's ``airspeed`` or ``groundspeed`` parameters 
+(this is equivalent to setting :py:attr:`Vehicle.airspeed <dronekit.Vehicle.airspeed>`
+or :py:attr:`Vehicle.groundspeed <dronekit.Vehicle.groundspeed>`). The speed setting will then be used
+for all positional movement commands until it is set to another value. 
+
+.. code-block:: python
+
+    # Set airspeed using attribute
+    vehicle.airspeed = 5 #m/s
+
+    # Set groundspeed using attribute
+    vehicle.groundspeed = 7.5 #m/s
+    
+    # Set groundspeed using `simple_goto()` parameter
+    vehicle.simple_goto(a_location, groundspeed=10)
+
+.. note::
+
+    ``Vehicle.simple_goto()`` will use the last speed value set. If both speed values are set at the
+    same time the resulting behaviour will be vehicle dependent.
+
 
 .. tip::
 
@@ -256,13 +276,14 @@ Supported commands
 `Copter Commands in Guided Mode <http://dev.ardupilot.com/wiki/copter-commands-in-guided-mode/>`_ lists all the commands that *can* be sent to Copter in GUIDED mode (in fact most of the commands can be sent in any mode!)
 
 DroneKit-Python provides a friendly Python API that abstracts many of the commands. 
-Where possible you should use the API rather than send messages directly. 
-For example it is better to use :py:func:`Vehicle.simple_takeoff() <dronekit.Vehicle.simple_takeoff>` 
-than to explicitly send the ``MAV_CMD_NAV_TAKEOFF`` command.
+Where possible you should use the API rather than send messages directly> For example, use:
+
+* :py:func:`Vehicle.simple_takeoff() <dronekit.Vehicle.simple_takeoff>` instead of the ``MAV_CMD_NAV_TAKEOFF`` command. 
+* :py:func:`Vehicle.simple_goto() <dronekit.Vehicle.simple_goto>`, :py:attr:`Vehicle.airspeed <dronekit.Vehicle.airspeed>`, 
+   or :py:attr:`Vehicle.groundspeed <dronekit.Vehicle.groundspeed>` rather than ``MAV_CMD_DO_CHANGE_SPEED``.
 
 Some of the MAV_CMD commands that you might want to send include: 
 :ref:`MAV_CMD_CONDITION_YAW <guided_mode_copter_set_yaw>`, 
-:ref:`MAV_CMD_DO_CHANGE_SPEED <guided_mode_copter_set_speed>`, 
 :ref:`MAV_CMD_DO_SET_ROI <guided_mode_copter_set_roi>`, 
 ``MAV_CMD_DO_SET_SERVO``, 
 ``MAV_CMD_DO_REPEAT_SERVO``, 
@@ -317,36 +338,6 @@ The command allows you to specify that whether the heading is an absolute angle
 
 
 
-.. _guided_mode_copter_set_speed:
-
-Setting the speed
------------------
-
-Send `MAV_CMD_DO_CHANGE_SPEED <http://copter.ardupilot.com/common-mavlink-mission-command-messages-mav_cmd/#mav_cmd_do_change_speed>`_ to change the current speed (metres/second) when travelling to a point. 
-
-.. code-block:: python
-
-    def set_speed(speed):
-        msg = vehicle.message_factory.command_long_encode(
-            0, 0,    # target system, target component
-            mavutil.mavlink.MAV_CMD_DO_CHANGE_SPEED, #command
-            0, #confirmation
-            0, #param 1
-            speed, # speed in metres/second
-            0, 0, 0, 0, 0 #param 3 - 7
-            )
-
-        # send command to vehicle
-        vehicle.send_mavlink(msg)
-
-
-The command is useful when setting the vehicle position directly. It is not needed when controlling movement using velocity vectors.
-
-.. note:: 
-
-    In AC3.2.1 Copter will accelerate to the target speed across the journey and then decelerate as it reaches the target. In AC3.3 the speed changes immediately.
-
-
 
 .. _guided_mode_copter_set_roi:
 
@@ -430,7 +421,14 @@ to the Earth's poles.
         #New position in decimal degrees
         newlat = original_location.lat + (dLat * 180/math.pi)
         newlon = original_location.lon + (dLon * 180/math.pi)
-        return LocationGlobal(newlat, newlon,original_location.alt)
+        if type(original_location) is LocationGlobal:
+            targetlocation=LocationGlobal(newlat, newlon,original_location.alt)
+        elif type(original_location) is LocationGlobalRelative:
+            targetlocation=LocationGlobalRelative(newlat, newlon,original_location.alt)
+        else:
+            raise Exception("Invalid Location object passed")
+            
+        return targetlocation;
 
 
 .. code-block:: python

examples/guided_set_speed_yaw/guided_set_speed_yaw.py

@@ -1,3 +1,4 @@
+
 """
 guided_set_speed_yaw.py: (Copter Only)
 
@@ -6,7 +7,7 @@
 Example documentation: http://python.dronekit.io/examples/guided-set-speed-yaw-demo.html
 """
 
-from dronekit import connect, VehicleMode, LocationGlobal
+from dronekit import connect, VehicleMode, LocationGlobal, LocationGlobalRelative
 from pymavlink import mavutil # Needed for command message definitions
 import time
 import math
@@ -132,34 +133,6 @@ def set_roi(location):
     vehicle.send_mavlink(msg)
 
 
-def set_speed(speed):
-    """
-    Send MAV_CMD_DO_CHANGE_SPEED to change the current speed when travelling to a point.
-
-    In AC3.2.1 Copter will accelerate to this speed near the centre of its journey and then 
-    decelerate as it reaches the target. In AC3.3 the speed changes immediately.
-
-    This method is only useful when controlling the vehicle using position/goto commands. 
-    It is not needed when controlling vehicle movement using velocity components.
-
-    For more information see: 
-    http://copter.ardupilot.com/common-mavlink-mission-command-messages-mav_cmd/#mav_cmd_do_change_speed
-    """
-    # create the MAV_CMD_DO_CHANGE_SPEED command
-    msg = vehicle.message_factory.command_long_encode(
-        0, 0,    # target system, target component
-        mavutil.mavlink.MAV_CMD_DO_CHANGE_SPEED, #command
-        0, #confirmation
-        0, #param 1
-        speed, # speed
-        0, 0, 0, 0, 0 #param 3 - 7
-        )
-
-    # send command to vehicle
-    vehicle.send_mavlink(msg)
-
-
-
 
 """
 Functions to make it easy to convert between the different frames-of-reference. In particular these
@@ -197,7 +170,14 @@ def get_location_metres(original_location, dNorth, dEast):
     #New position in decimal degrees
     newlat = original_location.lat + (dLat * 180/math.pi)
     newlon = original_location.lon + (dLon * 180/math.pi)
-    return LocationGlobal(newlat, newlon,original_location.alt)
+    if type(original_location) is LocationGlobal:
+        targetlocation=LocationGlobal(newlat, newlon,original_location.alt)
+    elif type(original_location) is LocationGlobalRelative:
+        targetlocation=LocationGlobalRelative(newlat, newlon,original_location.alt)
+    else:
+        raise Exception("Invalid Location object passed")
+        
+    return targetlocation;
 
 
 def get_distance_metres(aLocation1, aLocation2):
@@ -315,9 +295,6 @@ def goto(dNorth, dEast, gotoFunction=vehicle.simple_goto):
     targetLocation=get_location_metres(currentLocation, dNorth, dEast)
     targetDistance=get_distance_metres(currentLocation, targetLocation)
     gotoFunction(targetLocation)
-    
-    
-
 
     while vehicle.mode.name=="GUIDED": #Stop action if we are no longer in guided mode.
         remainingDistance=get_distance_metres(vehicle.location.global_relative_frame, targetLocation)
@@ -420,8 +397,10 @@ def send_global_velocity(velocity_x, velocity_y, velocity_z, duration):
 the distance-to-target.
 """	
 print("TRIANGLE path using standard Vehicle.simple_goto()")
-print("Set speed to 5m/s.")
-set_speed(5)
+
+print("Set groundspeed to 5m/s.")
+vehicle.groundspeed=5
+
 print("Position North 80 West 50")
 goto(80, -50)
 
@@ -450,17 +429,17 @@ def send_global_velocity(velocity_x, velocity_y, velocity_z, duration):
 print("TRIANGLE path using standard SET_POSITION_TARGET_GLOBAL_INT message and with varying speed.")
 print("Position South 100 West 130")
 
-print("Set speed to 5m/s.")
-set_speed(5)
+print("Set groundspeed to 5m/s.")
+vehicle.groundspeed=5
 goto(-100, -130, goto_position_target_global_int)
 
-print("Set speed to 15m/s (max).")
-set_speed(15)
+print("Set groundspeed to 15m/s (max).")
+vehicle.groundspeed=15
 print("Position South 0 East 200")
 goto(0, 260, goto_position_target_global_int)
 
-print("Set speed to 10m/s (max).")
-set_speed(10)
+print("Set airspeed to 10m/s (max).")
+vehicle.airspeed=10
 
 print("Position North 100 West 130")
 goto(100, -130, goto_position_target_global_int)