Merge remote-tracking branch 'upstream/master'

Author: maruina

docs/examples/drone_delivery.rst

@@ -52,7 +52,7 @@ Looking at the code
 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/diydrones/droneapi-python/blob/master/example/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/diydrones/droneapi-python/blob/master/examples/drone_delivery/drone_delivery.py>`_ calls:
 
 :: 
 
@@ -84,7 +84,7 @@ Next we'll look at the basics of using the webservice and the local vehicle API
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/example/drone_delivery/drone_delivery.py>`_):
+The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/drone_delivery/drone_delivery.py>`_):
 
-.. include:: ../../example/drone_delivery/drone_delivery.py
+.. include:: ../../examples/drone_delivery/drone_delivery.py
     :literal:

docs/examples/flight_replay.rst

@@ -14,7 +14,7 @@ In this case, we pick some public flight from `Droneshare <http://www.droneshare
 
 You'll notice that the mission number for this flight is 101.
 
-Now we'll launch **flight_replay.py** (/example/flight_replay/flight_replay.py) and ask it to try and 'replay' mission 101.  It will ask the web server for representative points from the flight, parse the JSON response and use that data to generate 100 waypoints we would like our vehicle to hit.  For safety rather than using the altitude from the original flight we instead ask our vehicle to fly at a height of 30 meters.
+Now we'll launch **flight_replay.py** (/examples/flight_replay/flight_replay.py) and ask it to try and 'replay' mission 101.  It will ask the web server for representative points from the flight, parse the JSON response and use that data to generate 100 waypoints we would like our vehicle to hit.  For safety rather than using the altitude from the original flight we instead ask our vehicle to fly at a height of 30 meters.
 
 One possible use of some variant of this tool to replay your old flights at your regular test field.
 
@@ -57,7 +57,7 @@ The following simple function asks for the droneshare flight data:
 Some comments:
 
 * ``max_freq`` is used to throttle the messages found in the raw flight data to a lower message rate
-* ``_decode_dict`` is a utility function found on stack overflow which extracts usable strings from unicode encoded JSON (see `flight_replay.py <https://github.com/hamishwillee/dronekit-python/blob/master/example/flight_replay/flight_replay.py>`_ for its implementation).
+* ``_decode_dict`` is a utility function found on stack overflow which extracts usable strings from unicode encoded JSON (see `flight_replay.py <https://github.com/hamishwillee/dronekit-python/blob/master/examples/flight_replay/flight_replay.py>`_ for its implementation).
 
 
 Setting the new waypoints
@@ -94,7 +94,7 @@ Next we'll work with existing Linux services (gpsd) to add a new drone based fea
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/example/flight_replay/flight_replay.py>`_):
+The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/flight_replay/flight_replay.py>`_):
 
-.. include:: ../../example/flight_replay/flight_replay.py
+.. include:: ../../examples/flight_replay/flight_replay.py
     :literal:

docs/examples/follow_me.rst

@@ -18,7 +18,7 @@ Before running this demo you'll need to make sure your computer has the gpsd ser
 
     apt-get install gpsd gpsd-clients
 
-You can then plug in a USB GPS and run the "xgps" client to confirm that it is working. If you do not have a USB GPS you can use simulated data by running *droneapi-python/example/run-fake-gps.sh*.
+You can then plug in a USB GPS and run the "xgps" client to confirm that it is working. If you do not have a USB GPS you can use simulated data by running *droneapi-python/examples/run-fake-gps.sh*.
 
 Once your GPS is plugged in you can start follow-me by running the following command inside of MAVProxy:
 
@@ -42,7 +42,7 @@ Next, take a look at the full :ref:`api_reference` for more information.
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/example/follow_me/follow_me.py>`_):
+The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/follow_me/follow_me.py>`_):
 
-.. include:: ../../example/follow_me/follow_me.py
+.. include:: ../../examples/follow_me/follow_me.py
     :literal:

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

@@ -25,7 +25,7 @@ Once MAVProxy is running and the API is loaded, you can run the example by typin
 If you started the DroneKit MAVProxy prompt in a directory containing the example script you can start it using:
 ``api start guided_set_speed_yaw.py``. 
 Otherwise you may have to specify the full path (something like):
-``api start /home/user/git/dronekit-python/example/guided_set_speed_yaw/guided_set_speed_yaw.py``.
+``api start /home/user/git/dronekit-python/examples/guided_set_speed_yaw/guided_set_speed_yaw.py``.
 
 The program will automatically arm the vehicle and start the demo. First it waits for a GPS lock 
 (``Waiting for GPS...``), then to receive a location update (``Waiting for location...``) and finally 
@@ -49,7 +49,7 @@ After starting the simulator, the console output should look something like:
     -> module load droneapi.module.api
     DroneAPI loaded
     Loaded module droneapi.module.api
-    -> api start /home/user/git/dronekit-python/example/guided_set_speed_yaw/guided_set_speed_yaw.py
+    -> api start /home/user/git/dronekit-python/examples/guided_set_speed_yaw/guided_set_speed_yaw.py
     Waiting for GPS...
     Loaded module console
     Loaded module map
@@ -198,7 +198,7 @@ At the time of writing, the acceleration and yaw parameters of
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/example/guided_set_speed_yaw/guided_set_speed_yaw.py>`_):
+The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/guided_set_speed_yaw/guided_set_speed_yaw.py>`_):
 
-.. include:: ../../example/guided_set_speed_yaw/guided_set_speed_yaw.py
+.. include:: ../../examples/guided_set_speed_yaw/guided_set_speed_yaw.py
     :literal:

docs/examples/index.rst

@@ -13,6 +13,7 @@ during missions and outside missions using custom commands.
    :maxdepth: 1
 
    running_examples
+   Vehicle State <vehicle_state>
    Simple Goto <simple_goto>
    Follow Me (Linux only)<follow_me>
    Drone Delivery <drone_delivery>

docs/examples/running_examples.rst

@@ -17,7 +17,7 @@ The easiest way to get the DroneKit example source code is to clone the **dronek
 
     git clone http://github.com/diydrones/droneapi-python.git
 
-The examples are stored in the subdirectories of **/dronekit-python/example/**.
+The examples are stored in the subdirectories of **/dronekit-python/examples/**.
 
 
 

docs/examples/simple_goto.rst

@@ -1,48 +1,139 @@
-========================
-Example: Simple Go To
-========================
+.. _example_simple_goto:
 
-This little demonstration just tells the vehicle to fly to a couple of different locations in the world.  You can edit the code to pick a latitude and longitude close to your position.
+==============================
+Example: Simple Go To (Copter)
+==============================
 
-Running the example
-===================
+This example demonstrates how to arm and launch a Copter in GUIDED mode, travel to a number of waypoints, and then return 
+to the home location. It uses :py:func:`Vehicle.commands.takeoff() <droneapi.lib.CommandSequence.takeoff>`, 
+:py:func:`Vehicle.commands.goto() <droneapi.lib.CommandSequence.goto>` and :py:attr:`Vehicle.mode <droneapi.lib.Vehicle.mode>`.
+
+The locations used are centred around the home location when the :ref:`Simulated Vehicle <vagrant-sitl-from-full-image>` is booted; you can edit the latitude and longitude 
+to use more appropriate positions for your own vehicle. 
+
+.. note:: 
 
-Once Mavproxy is running and the API is loaded, you can run this small example by typing: ``api start simple_goto.py``
+    This example will only run on *Copter*:
 
-It will tell your vehicle to start flying to a particular latitude and longitude stored in the file (though for safety the take-off command is not included - you must manually tell vehicle to fly).  On the mavproxy console you should see:
+    * *Plane* does not support ``takeoff`` in GUIDED mode. 
+    * *Rover* will ignore the ``takeoff`` command and will then stick at the altitude check.
+   
 
-::
 
-	STABILIZE> api start simple_goto.py
-	STABILIZE> Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
-	GUIDED> Mode GUIDED
-	APIThread-0 exiting...
-	Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
+Running the example
+===================
+
+The vehicle and DroneKit should be set up as described in the :ref:`quick-start` or :ref:`get-started`.
+
+If you're using a simulated vehicle, remember to :ref:`disable arming checks <disable-arming-checks>` so 
+that the example can run.
+
+Once MAVProxy is running and the API is loaded, you can start the example by typing: ``api start simple_goto.py``.
+
+.. note:: 
+
+    The command above assumes you started the *MAVProxy* prompt in a directory containing the example script. If not, 
+    you will have to specify the full path to the script (something like):
+    ``api start /home/user/git/dronekit-python/examples/simple_goto/simple_goto.py``.
+
+.. tip::	
+
+    It is more interesting to watch the example above on a map than the console. The topic :ref:`viewing_uav_on_map` 
+    explains how to set up *Mission Planner* to view a vehicle running on the simulator (SITL).
+
+On the *MAVProxy* console you should see (something like):
+
+.. code-block:: python
+
+    MAV> api start simple_goto.py
+    STABILIZE> Basic pre-arm checks
+    Arming motors
+     Waiting for arming...
+     Waiting for arming...
+    APM: ARMING MOTORS
+    APM: GROUND START
+     Waiting for arming...
+     Waiting for arming...
+    GUIDED> Mode GUIDED
+    APM: Initialising APM...
+    Got MAVLink msg: COMMAND_ACK {command : 400, result : 0}
+    Waiting for arming...
+    ARMED
+    Taking off!
+     Altitude:  0.0
+    Got MAVLink msg: COMMAND_ACK {command : 22, result : 0}
+     Altitude:  0.10000000149
+     Altitude:  0.620000004768
+     ...
+     Altitude:  19.25
+    Reached target altitude
+    Going to first point...
+    Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
+    Going to second point...
+    Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
+    Returning to Launch
+    APIThread-0 exiting...	
+	
+.. tip::	
+
+    If you get stuck in ``Waiting for arming...`` it is very likely that the vehicle did not pass all pre-arm checks. 
+    On a real device you can view the controller LEDs to determine likely issues. On the Simulator console you 
+    can disable the checks if needed:
+
+    .. code-block:: bash
+
+        STABILIZE>param load ../Tools/autotest/copter_params.parm
+        STABILIZE>param set ARMING_CHECK 0
 
 
 How does it work?
 =================
 
-The key code in this demo is the following:
+The code has three distinct sections: arming and takeoff, flight to a specified location, and return-to-home.
+
+Takeoff
+-------
+
+To launch *Copter* you need to set the mode to ``GUIDED``, arm the vehicle, and then call 
+:py:func:`Vehicle.commands.takeoff() <droneapi.lib.CommandSequence.takeoff>`. The takeoff code in this example
+is explained in the guide topic :ref:`taking-off`.
+
+	
+Flying to a point - Goto
+------------------------
+
+The vehicle is already in ``GUIDED`` mode, so to send it to a certain point we just need to 
+call :py:func:`Vehicle.commands.goto() <droneapi.lib.CommandSequence.goto>` with the target location, 
+and then :py:func:`flush() <droneapi.lib.Vehicle.flush>` the command:
+
+.. code-block:: python	
+
+    point1 = Location(-35.361354, 149.165218, 20, is_relative=True)
+    vehicle.commands.goto(point1)
+    vehicle.flush()
+
+    # sleep so we can see the change in map
+    time.sleep(30)
 
-::
+Without some sort of "wait" the next command would be executed immediately. In this example we just 
+sleep for 30 seconds - a good opportunity to observe the vehicle's movement on a map. 
 
-	vehicle.mode    = VehicleMode("GUIDED")
-	origin          = Location(-34.364114, 149.166022, 30, is_relative=True)
 
-	commands.goto(origin)
-	vehicle.flush()
+RTL - Return to launch
+------------------------
 
-It tells the vehicle to fly to a specified lat/long and hover at that location (30 meters in the air).  ``is_relative=True`` is the default and is recommended - it means that the altitude (30 meters) is *relative* to the vehicle home location.  If you had set ``is_relative`` to ``false``, it would have told the vehicle to fly to a specified mean-sea-level which is probably not what you want unless you are next to an ocean.
+To return to the home position and land, we set the mode to ``RTL``:
 
+.. code-block:: python	
 
-Building on the basic vehicle control you just learned, we now show how to write a small web application that allows you to command a drone to fly to a particular location.
+    vehicle.mode    = VehicleMode("RTL")
+    vehicle.flush()
 
 
 Source code
 ===========
 
-The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/example/simple_goto/simple_goto.py>`_):
+The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/simple_goto/simple_goto.py>`_):
 
-.. include:: ../../example/simple_goto/simple_goto.py
-    :literal:
+.. literalinclude:: ../../examples/simple_goto/simple_goto.py
+    :language: python