Merge pull request #445 from dronekit/tcr-frame

Implements LocationGlobalRelative.

Author: tcr3dr

docs/examples/drone_delivery.rst

@@ -105,7 +105,8 @@ How it works
 Using attribute observers
 -------------------------
 
-All attributes in DroneKit can have observers - this is the primary mechanism you should use to be notified of changes in vehicle state.  For instance, `drone_delivery.py <https://github.com/dronekit/dronekit-python/blob/master/examples/drone_delivery/drone_delivery.py>`_ calls:
+All attributes in DroneKit can have observers - this is the primary mechanism you should use to be notified of changes in vehicle state.  
+For instance, `drone_delivery.py <https://github.com/dronekit/dronekit-python/blob/master/examples/drone_delivery/drone_delivery.py>`_ calls:
 
 .. code-block:: python
 
@@ -114,7 +115,7 @@ All attributes in DroneKit can have observers - this is the primary mechanism yo
     ...
 
     def location_callback(self, location):
-        location = self.vehicle.location.global_frame
+        location = location.global_frame
 
         if location.alt is not None:
             self.altitude = location.alt

docs/examples/vehicle_state.rst

@@ -58,7 +58,8 @@ On the command prompt you should see (something like):
     >>> GROUND START
 
     Get all vehicle attribute values:
-     Global Location: LocationGlobal:lat=-35.363261,lon=149.1652299,alt=0.0,is_relative=False
+     Global Location: LocationGlobal:lat=-35.363261,lon=149.1652299,alt=None
+     Global Location (relative altitude): LocationGlobalRelative:lat=-35.363261,lon=149.1652299,alt=0.0
      Local Location: LocationLocal:north=None,east=None,down=None
      Attitude: Attitude:pitch=0.00294387154281,yaw=-0.11805768311,roll=0.00139428151306
      Velocity: [-0.03, 0.02, 0.0]
@@ -81,11 +82,11 @@ On the command prompt you should see (something like):
      Waiting for home location ...
      Waiting for home location ...
 
-     Home location: LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=583.989990234,is_relative=False
+     Home location: LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=583.989990234
 
     Set new home location
-     New Home Location (from attribute - altitude should be 222): LocationGlobal:lat=-35.363261,lon=149.1652299,alt=222,is_relative=False
-     New Home Location (from vehicle - altitude should be 222): LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=222.0,is_relative=False
+     New Home Location (from attribute - altitude should be 222): LocationGlobal:lat=-35.363261,lon=149.1652299,alt=222
+     New Home Location (from vehicle - altitude should be 222): LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=222.0
 
     Set Vehicle.mode=GUIDED (currently: STABILIZE)
      Waiting for mode change ...
@@ -121,13 +122,13 @@ On the command prompt you should see (something like):
      Wait 1s so callback invoked before observer removed
      CALLBACK: (attitude): Attitude:pitch=0.00716688157991,yaw=-0.0950401723385,roll=0.00759896961972
      CALLBACK: (heading): 354
-     CALLBACK: (location): LocationGlobal:lat=-35.3632621,lon=149.1652291,alt=362.0,is_relative=False
+     CALLBACK: (location): <dronekit.lib.Locations object at 0x000000000767F2B0>
      CALLBACK: (airspeed): 0.0
      CALLBACK: (groundspeed): 0.0
      CALLBACK: (ekf_ok): True
      CALLBACK: (battery): Battery:voltage=12.538,current=3.48,level=99
      CALLBACK: (gps_0): GPSInfo:fix=3,num_sat=10
-     CALLBACK: (location): LocationGlobal:lat=-35.3632622,lon=149.1652295,alt=362.0,is_relative=False
+     CALLBACK: (location): <dronekit.lib.Locations object at 0x000000000767F2B0>
      CALLBACK: (velocity): [-0.14, 0.1, 0.0]
      CALLBACK: (local_position): LocationLocal:north=-0.136136248708,east=-0.0430941730738,down=-0.00938374921679
      CALLBACK: (channels): {'1': 1500, '3': 1000, '2': 1500, '5': 1800, '4': 1500, '7': 1000, '6': 1000, '8': 1800}
@@ -191,7 +192,8 @@ This example has no known issues.
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/dronekit/dronekit-python/blob/master/examples/vehicle_state/vehicle_state.py>`_):
+The full source code at documentation build-time is listed below 
+(`current version on github <https://github.com/dronekit/dronekit-python/blob/master/examples/vehicle_state/vehicle_state.py>`_):
 
 .. literalinclude:: ../../examples/vehicle_state/vehicle_state.py
    :language: python

docs/guide/migrating.rst

@@ -170,6 +170,27 @@ Instead, use normal Python methods for getting file system information:
     full_directory_path_of_current_script = os.path.dirname(os.path.abspath(__file__))
 
     
+Vehicle.location
+----------------
+
+DroneKit-Python v1.x had a ``Vehicle.location`` attribute which provided latitude and longitude information in the
+global frame, and altitude either relative to sea-level or the home location (depending on the value of its ``is_relative`` member).
+
+DKPY2.0 uses and attribute with the same name to provide location in 
+global, global-relative and local (NED) frames:
+
+.. code-block:: python
+
+    print "Global Location: %s" % vehicle.location.global_frame
+    print "Global Location (relative altitude): %s" % vehicle.location.global_relative_frame
+    print "Local Location: %s" % vehicle.location.local_frame
+
+For more information see: :py:attr:`Vehicle.location <dronekit.lib.Vehicle.location>`, 
+:py:attr:`Vehicle.location.global_frame <dronekit.lib.Locations.global_frame>`, 
+:py:attr:`Vehicle.location.global_relative_frame <dronekit.lib.Locations.global_relative_frame>`, 
+:py:attr:`Vehicle.location.local_frame <dronekit.lib.Locations.local_frame>`,  and :ref:`vehicle-information`.
+   
+    
 .. _migrating_dkpy2_0_home_location:
 
 Home location
@@ -278,8 +299,8 @@ See :ref:`mavlink_messages` for more information.
 New attributes
 --------------
 
-In addition to the :ref:`home_location <migrating_dkpy2_0_heading>`, a few more attributes have been added, 
-including:
+In addition to the :ref:`home_location <migrating_dkpy2_0_home_location>`, 
+a few more attributes have been added, including:
 :py:func:`Vehicle.system_status <dronekit.lib.Vehicle.system_status>`, 
 :py:func:`Vehicle.heading <dronekit.lib.Vehicle.heading>`, 
 :py:func:`Vehicle.mount_status <dronekit.lib.Vehicle.mount_status>`, 

docs/guide/taking_off.rst

@@ -55,8 +55,8 @@ The code below shows a function to arm a Copter, take off, and fly to a specifie
         # Wait until the vehicle reaches a safe height before processing the goto (otherwise the command 
         #  after Vehicle.commands.takeoff will execute immediately).
         while True:
-            print " Altitude: ", vehicle.location.global_frame.alt
-            if vehicle.location.global_frame.alt>=aTargetAltitude*0.95: #Just below target, in case of undershoot.
+            print " Altitude: ", vehicle.location.global_relative_frame.alt
+            if vehicle.location.global_relative_frame.alt>=aTargetAltitude*0.95: #Just below target, in case of undershoot.
                 print "Reached target altitude"
                 break
             time.sleep(1)
@@ -127,8 +127,8 @@ concerned about reaching a particular height, a simpler implementation might jus
 .. code-block:: python
 
         while True:
-            print " Altitude: ", vehicle.location.global_frame.alt
-            if vehicle.location.global_frame.alt>=aTargetAltitude*0.95: #Just below target, in case of undershoot.
+            print " Altitude: ", vehicle.location.global_relative_frame.alt
+            if vehicle.location.global_relative_frame.alt>=aTargetAltitude*0.95: #Just below target, in case of undershoot.
                 print "Reached target altitude"
                 break
             time.sleep(1)

docs/guide/vehicle_state_and_parameters.rst

@@ -21,8 +21,9 @@ Attributes
 
 Vehicle state information is exposed through vehicle *attributes*. DroneKit-Python currently supports the following 
 "standard" attributes: 
-:py:attr:`Vehicle.location.global_frame <dronekit.lib.Vehicle.location.global_frame>`, 
-:py:attr:`Vehicle.location.local_frame <dronekit.lib.Vehicle.location.local_frame>`, 
+:py:attr:`Vehicle.location.global_frame <dronekit.lib.Locations.global_frame>`, 
+:py:attr:`Vehicle.location.global_relative_frame <dronekit.lib.Locations.global_relative_frame>`, 
+:py:attr:`Vehicle.location.local_frame <dronekit.lib.Locations.local_frame>`, 
 :py:attr:`Vehicle.attitude <dronekit.lib.Vehicle.attitude>`,
 :py:attr:`Vehicle.velocity <dronekit.lib.Vehicle.velocity>`,
 :py:attr:`Vehicle.airspeed <dronekit.lib.Vehicle.airspeed>`,
@@ -65,6 +66,7 @@ regularly updated from MAVLink messages sent by the vehicle).
     
     # vehicle is an instance of the Vehicle class
     print "Global Location: %s" % vehicle.location.global_frame
+    print "Global Location (relative altitude): %s" % vehicle.location.global_relative_frame
     print "Local Location: %s" % vehicle.location.local_frame    #NED
     print "Attitude: %s" % vehicle.attitude
     print "Velocity: %s" % vehicle.velocity
@@ -169,7 +171,7 @@ The ``observer`` callback function is invoked with the following arguments:
 * ``value`` - the attribute value (so you don't need to re-query the vehicle object).
 
 The code snippet below shows how to add (and remove) a callback function to observe changes
-in :py:attr:`Vehicle.location.global_frame <dronekit.lib.Vehicle.location.global_frame>` using 
+in :py:attr:`Vehicle.location.global_frame <dronekit.lib.Locations.global_frame>` using 
 :py:func:`Vehicle.add_attribute_listener() <dronekit.lib.Vehicle.add_attribute_listener>`. 
 The two second ``sleep()`` is required because otherwise the observer might be removed before the the 
 callback is first run.
@@ -184,13 +186,24 @@ callback is first run.
 
         
     # Add a callback `location_callback` for the `global_frame` attribute.
-    vehicle.add_attribute_listener('global_frame', location_callback)
+    vehicle.add_attribute_listener('location.global_frame', location_callback)
 
     # Wait 2s so callback can be notified before the observer is removed
     time.sleep(2)
 
     # Remove observer - specifying the attribute and previously registered callback function
-    vehicle.remove_message_listener('location', location_callback)
+    vehicle.remove_message_listener('location.global_frame', location_callback)
+    
+.. note::
+
+    The example above adds a listener on ``Vehicle`` to for attribute name ``'location.global_frame'``
+    You can alternatively add (and remove) a listener ``Vehicle.location`` for the attribute name ``'global_frame'``. 
+    Both alternatives are shown below:
+    
+    .. code-block:: python
+
+        vehicle.add_attribute_listener('location.global_frame', location_callback)
+        vehicle.location.add_attribute_listener('global_frame', location_callback)
 
     
 The example below shows how you can declare an attribute callback using the 

dronekit/__init__.py

@@ -20,6 +20,7 @@
 CommandSequence = dronekit.lib.CommandSequence
 VehicleMode = dronekit.lib.VehicleMode
 SystemStatus = dronekit.lib.SystemStatus
+LocationGlobalRelative = dronekit.lib.LocationGlobalRelative
 LocationGlobal = dronekit.lib.LocationGlobal
 LocationLocal = dronekit.lib.LocationLocal
 CloudClient = dronekit.lib.CloudClient