Merge pull request #555 from dronekit/hgw_running_examples

UPdate running examples page and simulation instructions

Author: peterbarker

docs/develop/sitl_setup.rst

@@ -8,17 +8,19 @@ The `SITL (Software In The Loop) <http://dev.ardupilot.com/wiki/simulation-2/sit
 simulator allows you to create and test DroneKit-Python apps without a real vehicle (and from the comfort of 
 your own developer desktop!).
 
-SITL can run natively on Linux, Mac and Windows, or within a virtual machine. It can be 
+SITL can run natively on Linux (x86 architecture only), Mac and Windows, or within a virtual machine. It can be 
 installed on the same computer as DroneKit, or on another computer on the same network.
 
 The sections below explain how to install and run SITL, and how to connect to DroneKit-Python and Ground
 Stations at the same time.
 
 
+.. _dronekit_sitl:
+
 DroneKit-SITL
 =============
 
-DroneKit-SITL is the simplest, fastest and easiest way to run SITL on Windows, Linux, or MAC OSX.
+DroneKit-SITL is the simplest, fastest and easiest way to run SITL on Windows, Linux (x86 architecture only), or Mac OS X.
 It is installed from Python's *pip* tool on all platforms, and works by downloading and running pre-built 
 vehicle binaries that are appropriate for the host operating system.
 
@@ -27,8 +29,12 @@ the `project on Github <https://github.com/dronekit/dronekit-sitl>`_.
 
 .. note:: 
 
-    DroneKit-SITL is still relatively experimental. There are only a few pre-built vehicles and
-    they have not been as well tested as the native builds.  
+    DroneKit-SITL is still relatively experimental and there are only a few pre-built vehicles.
+    
+    The binaries are built and tested on Windows 10, Ubuntu Linux, and Mac OS X
+    "El Capitan". Binaries are only available for x86 architectures. ARM builds 
+    (e.g. for RPi) are not supported.
+    
     Please report any issues on `Github here <https://github.com/dronekit/dronekit-sitl/issues>`_.
 
 Installation
@@ -68,42 +74,38 @@ There are a number of other useful arguments:
     dronekit-sitl --reset       #Delete all downloaded vehicle binaries.
     dronekit-sitl ./path [args...]  #Start SITL instance at target file location.
 
-
-.. note:: 
-
-    DroneKit-SITL also `exposes a Python API <https://github.com/dronekit/dronekit-sitl#api>`_, which you can use to start simulation from within your scripts. This is particularly useful for test code!
         
 
 .. _connecting_dronekit_sitl:
 
-Connecting to (DroneKit-) SITL
-------------------------------
+Connecting to DroneKit-SITL
+---------------------------
 
-SITL waits for TCP connections on ``127.0.0.1:5760``. DroneKit-Python scripts running on the same
+DroneKit-SITL waits for TCP connections on ``127.0.0.1:5760``. DroneKit-Python scripts running on the same
 computer can connect to the simulation using the connection string as shown:
 
 .. code-block:: python
 
     vehicle = connect('tcp:127.0.0.1:5760', wait_ready=True)
 
-If you need to connect to DroneKit-Python and a ground station at the same time you will need to
-`install MAVProxy <http://dronecode.github.io/MAVProxy/html/getting_started/download_and_installation.html>`_ 
-for your system.
+After something connects to port ``5760``, SITL will then wait for additional connections on port ``5763``
+(and subsequently ``5766``, ``5769`` etc.)
+
+.. note::
 
-Then in a second terminal you spawn an instance of *MAVProxy* to forward messages from
-TCP ``127.0.0.1:5760`` to UDP ports ``127.0.0.1:14550`` and ``127.0.0.1:14551`` (this is what **sim_vehicle.sh** does
-if you build SITL from source):
+    While you can connect to these additional ports, some users have reported problems when
+    viewing the running examples with *Mission Planner*. If you need to connect a ground station
+    and DroneKit at the same time we recommend you use *MAVProxy* (see :ref:`viewing_uav_on_map`).
 
-.. code-block:: bash
 
-    mavproxy.py --master tcp:127.0.0.1:5760 --sitl 127.0.0.1:5501 --out 127.0.0.1:14550 --out 127.0.0.1:14551
 
-You can then connect to a ground station using one UDP address, and DroneKit-Python using the other. 
-For example:
+.. _dronekit_sitl_api:
 
-.. code-block:: python
+DroneKit-SITL Python API
+------------------------
+
+DroneKit-SITL `exposes a Python API <https://github.com/dronekit/dronekit-sitl#api>`_, which you can use to start and control simulation from within your scripts. This is particularly useful for test code and :ref:`examples <example-toc>`.
 
-    vehicle = connect('127.0.0.1:14550', wait_ready=True)
 
 
 
@@ -117,7 +119,14 @@ Building from source is useful if you want to need to test the latest changes (o
 a version for which DroneKit-SITL does not have pre-built binaries). 
 It can also be useful if you have problems getting DroneKit-SITL to work.
 
-The following topics from the ArduPilot wiki explain how:
+SITL built from source has a few differences from DroneKit-SITL:
+
+* MAVProxy is included and started by default. You can use MAVProxy terminal to control the autopilot.
+* You connect to SITL via UDP on ``127.0.0.1:14550``. You can use MAVProxy's ``output add`` command to add additional ports if needed.
+* You may need to disable arming checks and load autotest parameters to run examples.
+* It is easier to `add a virtual rangefinder <http://dev.ardupilot.com/wiki/using-sitl-for-ardupilot-testing/#adding_a_virtual_rangefinder>`_ and `add a virtual gimbal <http://dev.ardupilot.com/wiki/using-sitl-for-ardupilot-testing/#adding_a_virtual_gimbal>`_ for testing.
+
+The following topics from the ArduPilot wiki explain how to set up Native SITL builds:
 
 * `Setting up SITL on Linux <http://dev.ardupilot.com/wiki/setting-up-sitl-on-linux/>`_
 * `Setting up SITL on Windows <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/sitl-native-on-windows/>`_ 
@@ -129,24 +138,38 @@ The following topics from the ArduPilot wiki explain how:
 Connecting an additional Ground Station
 =======================================
 
-You can connect a ground station to an unused port to which messages 
-are being forwarded. You can forward messages to additional ports 
-when you start *MAVProxy* using the using ``-out`` 
-parameter (as shown :ref:`above <connecting_dronekit_sitl>`).
+You can connect a ground station to an unused port to which messages are being forwarded.
 
-Alternatively, once *MAVProxy* is started you can add new output ports in the *MAVProxy* console using: ``output add``:
+The most reliable way to add new ports is to use *MAVProxy*:
 
-.. code:: bash
+* If you're using SITL built from source you will already have *MAVProxy* running. 
+  You can add new ports in the MAVProxy console using ``output add``:
 
-    output add 127.0.0.1:14552
+  .. code:: bash
 
-.. note::
+      output add 127.0.0.1:14552
+
+* If you're using Dronekit-SITL you can:
+
+  * `Install MAVProxy <http://dronecode.github.io/MAVProxy/html/getting_started/download_and_installation.html>`_ 
+    for your system. 
+  * In a second terminal spawn an instance of *MAVProxy* to forward messages from
+    TCP ``127.0.0.1:5760`` to other UDP ports like ``127.0.0.1:14550`` and ``127.0.0.1:14551``:
+
+    .. code-block:: bash
 
-    Instead of the loopback address you can also specify the network IP address of your computer
-    (On Windows you can get this by running *ipconfig* in the *Windows Command Prompt*).
+       mavproxy.py --master tcp:127.0.0.1:5760 --sitl 127.0.0.1:5501 --out 127.0.0.1:14550 --out 127.0.0.1:14551
 
+Once you have available ports you can connect to a ground station using one UDP address, and DroneKit-Python using the other. 
 
-Then connect Mission Planner to this UDP port:  
+For example, first connect the script:
+
+.. code-block:: python
+
+    vehicle = connect('127.0.0.1:14550', wait_ready=True)
+
+
+Then connect Mission Planner to the second UDP port:  
 
 * `Download and install Mission Planner <http://ardupilot.com/downloads/?did=82>`_
 * Ensure the selection list at the top right of the Mission Planner screen says *UDP* and then select the **Connect** button next to it. 
@@ -159,3 +182,12 @@ Then connect Mission Planner to this UDP port:
 
 After connecting, vehicle parameters will be loaded into *Mission Planner* and the vehicle is displayed on the map.
 
+.. tip::
+
+    If you're using the :ref:`dronekit_sitl_api` then you will instead have to 
+    connect to SITLs TCP port (as there is no way to set up MAVProxy in this case).
+    So if DroneKit is connecting to TCP port 5760, you would connect your GCS to 5763.
+    
+    Note that a few examples may not behave perfectly using this approach. If you need to 
+    observe them in a GCS you should run SITL externally and use MAVProxy to connect to it.
+

docs/examples/running_examples.rst

@@ -4,14 +4,20 @@
 Running the Examples
 ====================
 
-General instructions for running the `example source code <https://github.com/dronekit/dronekit-python/tree/master/examples>`_ are given below.
+General instructions for running the `example source code <https://github.com/dronekit/dronekit-python/tree/master/examples>`_ are given below. More explicit instructions are provided within the documentation for each example (and within the examples themselves by passing the ``-h`` (help) command line argument).
 
 .. tip::
 
-    More explicit instructions may be provided within the documentation for each example, and on the command line using the ``-h`` (help) parameter.
+    The examples all launch the :ref:`dronekit-sitl <dronekit_sitl>` simulator and connect to it by default. The ``--connect`` argument is used to instead specify the :ref:`connection string <get_started_connect_string>` for a target vehicle or an externally managed SITL instance.
+    
+To run the examples:
+
+#. :ref:`Install DroneKit-Python <installing_dronekit>` if you have not already done so! Install :ref:`dronekit-sitl <dronekit_sitl>` if you want to test against simulated vehicles.
 
 #. Get the DroneKit-Python example source code onto your local machine. The easiest way to do this 
-   is to clone the **dronekit-python** repository from Github. On the command prompt enter:
+   is to clone the **dronekit-python** repository from Github. 
+   
+   On the command prompt enter:
 
    .. code-block:: bash
 
@@ -22,24 +28,28 @@ General instructions for running the `example source code <https://github.com/dr
 #. Navigate to the example you wish to run (or specify the full path in the next step). The examples are all stored in 
    subdirectories of **dronekit-python\\examples\\**. 
 
-   To run the :ref:`vehicle_state <example-vehicle-state>` example, you would navigate as shown:
+   For example, to run the :ref:`vehicle_state <example-vehicle-state>` example, you would navigate as shown:
 
    .. code-block:: bash
 
        cd dronekit-python\examples\vehicle_state\
 
 
-#. Start the example, passing the :ref:`connection string <get_started_connect_string>` you wish to use in the ``--connect`` parameter:
+#. Start the example as shown:
 
-   .. code-block:: bash
+   * To connect to a simulator started/managed by the script:
+   
+     .. code-block:: bash
 
-       python vehicle_state.py --connect 127.0.0.1:14550
+         python vehicle_state.py
 
-   .. note::
+   * To connect to a specific vehicle, pass its :ref:`connection string <get_started_connect_string>` via the ``connect`` argument. 
+     For example, to run the example on Solo you would use the following command:
 
-       The examples all use the ``--connect`` parameter to pass the :ref:`connection string <get_started_connect_string>` into the script. 
-       The command above would be used to connect to :ref:`SITL <sitl_setup>` running on the local machine via UDP port 14550.
-          
+     .. code-block:: bash
+
+         python vehicle_state.py --connect udpin:0.0.0.0:14550
+
 
 .. warning::