Merge pull request #158 from hamishwillee/tmp_guide_restructure

Restructure to getting started and removal of quickstart

Author: mrpollo

docs/about/overview.rst

@@ -13,7 +13,7 @@ Open source community
 DroneKit-Python is an open source and community-driven project. 
 
 You can find all the source code on `Github here <https://github.com/diydrones/dronekit-python>`_ and check out our permissive :doc:`Apache v2 Licence <license>`. 
-If you want to join the community, then see our :doc:`contributing page <contributing>` for lots of ideas on how you can help.
+If you want to join the community, then see our :doc:`contributing section <contributing>` for lots of ideas on how you can help.
 
 
 Compatibility

docs/contributing/developer_setup_windows.rst

@@ -5,8 +5,7 @@ Building DroneKit-Python on Windows
 ===================================
 
 The setup for *developing* DroneKit-Python on Windows is almost the same as for *using* 
-DroneKit-Python. We therefore recommend that you start by following the instructions in the :ref:`get-started` and/or 
-:ref:`quick-start`. 
+DroneKit-Python. We therefore recommend that you start by following the instructions in the :ref:`get-started`. 
 
 When you've got DroneKit and a vehicle (simulated or real) communicating, you can 
 then build and install your own fork of DroneKit, as discussed below.

docs/examples/running_examples.rst

@@ -2,7 +2,7 @@
 Running the Examples
 ====================
 
-To run the examples you will need to set up DroneKit as described in :ref:`get-started` or the :ref:`quick-start`. 
+To run the examples you will need to set up DroneKit as described in :ref:`get-started`. 
 Once you have the `source code <https://github.com/diydrones/dronekit-python/tree/master/example>`_, examples are 
 started as described in the *Getting Started* section :ref:`getting-started-running_examples`.
 

docs/examples/simple_goto.rst

@@ -23,7 +23,7 @@ to use more appropriate positions for your own vehicle.
 Running the example
 ===================
 
-The vehicle and DroneKit should be set up as described in the :ref:`quick-start` or :ref:`get-started`.
+The vehicle and DroneKit should be set up as described in :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.

docs/examples/vehicle_state.rst

@@ -14,7 +14,7 @@ should be used.
 Running the example
 ===================
 
-The vehicle and DroneKit should be set up as described in the :ref:`quick-start` or :ref:`get-started`.
+The vehicle and DroneKit should be set up as described in :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.
 

docs/guide/getting_started.rst

@@ -4,28 +4,24 @@
 Getting Started
 ===============
 
-DroneKit-Python apps are typically run on Linux-based :ref:`companion computers <supported-companion-computers>` that travel on the vehicle and communicate with the autopilot via a serial port. However, it is usually easier to first prototype your app on a standard Mac, Windows, or Linux computer using a simulated autopilot. The instructions in this document apply to both scenarios.
+DroneKit-Python apps are typically run on Linux-based *companion computers* that travel 
+on the vehicle and communicate with the autopilot via a serial port. However, during development it is usually easier to 
+prototype apps on a standard Mac, Windows, or Linux computer using a *simulated* autopilot. 
 
-.. tip:: If you want to develop for *DroneKit* on Windows using a simulated autopilot, our :ref:`quick-start` shows how to get up and running fast!
 
+This topic explains how to set up and run DroneKit-Python (within MAVProxy) on the different host operating systems
+and then run a basic DroneKit app. 
 
-Setting up the vehicle/autopilot
-=================================
 
-The topic :ref:`supported-companion-computers` has links to a number of tested hardware/software configurations for onboard Linux computers. These  
-include information about how to set up the hardware and physically connect to the vehicle. 
 
-If you wish to use a simulated vehicle, the Software-In-The-Loop (SITL) environment can be used to simulate a Copter, Plane, or Rover. It runs natively on Linux, 
-but can also run on Linux hosted in a virtual machine:
 
-* `Setting up SITL on Linux <http://dev.ardupilot.com/wiki/setting-up-sitl-on-linux/>`_ (for Linux).
-* :ref:`QuickStart: Set up the simulated vehicle <vagrant-sitl-from-full-image>` (for Windows or Mac OSX). 
+Setting up the vehicle/autopilot
+================================
 
-  .. note::
+For information on how to set up a vehicle (real and simulated) see:
 
-      The method used in the QuickStart is fast and reliable because it uses Vagrant to load an image that is pre-built and fully configured with SITL. 
-      Other approaches are described in the wiki topics `Setting up SITL using Vagrant <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/setting-up-sitl-using-vagrant/>`_ 
-      and `Setting up SITL on Windows <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/setting-up-sitl-on-windows/>`_.
+* :ref:`supported-companion-computers` for links to tested hardware/software configurations for a number of onboard Linux computers. 
+* :ref:`sitle_setup` for links explaining how to set up a simulated vehicle for Copter, Plane, or Rover.
 
 
 
@@ -70,6 +66,7 @@ If you're on Mac OSX, you can use `Homebrew <http://brew.sh/>`_ to install *WXMa
 
     brew tap homebrew/science
     brew install wxmac wxpython opencv
+
 	
 Uninstall *python-dateutil* (OSX and Windows come bundled with a version that is not supported for some dependencies):
 
@@ -94,15 +91,19 @@ You will need remove *python-dateutil* as the installation comes bundled with a
 
 The steps to install this package and our add-on modules are:
 
-1. Run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ (**v2.7**) for your platform (win32 vs win64)
+#. Download and run the correct `WinPython installer <http://sourceforge.net/projects/winpython/files/WinPython_2.7/2.7.6.4/>`_ (**v2.7**) for your platform (win32 vs win64).
+   
+   * Run the installer as an administrator (**Right-click** on file, select **Run as Administrator**). 
+   * When prompted for the destination location, specify **C:\Program Files (x86)** 
+     (the default location is under the Downloads folder).
 
-2. Register the python that came from *WinPython* as the preferred interpreter for your machine:
+#. Register the python that came from *WinPython* as the preferred interpreter for your machine:
 
    Open the folder where you installed WinPython, run *WinPython Control Panel* and choose **Advanced/Register Distribution**.
 
    .. image:: http://dev.ardupilot.com/wp-content/uploads/sites/6/2014/03/Screenshot-from-2014-09-03-083816.png
 
-3. Install DroneKit-Python and its remaining dependencies (including `MAVProxy <http://tridge.github.io/MAVProxy/>`_) from the public PyPi repository:
+#. Install DroneKit-Python and its remaining dependencies (including `MAVProxy <http://tridge.github.io/MAVProxy/>`_) from the public PyPi repository:
 
    Open the *WinPython Command Prompt* and run the following two commands:
 
@@ -129,7 +130,7 @@ Launch *MAVProxy* with the correct options for talking to your vehicle (simulate
      - ``mavproxy.py --master=/dev/ttyUSB0``
    * - Linux computer connected to the vehicle via Serial port (RaspberryPi example)
      - ``mavproxy.py --master=/dev/ttyAMA0 --baudrate 57600``
-   * - SITL Linux connected to the vehicle via UDP
+   * - SITL connected to the vehicle via UDP
      - ``mavproxy.py --master=127.0.0.1:14550``
    * - OSX computer connected to the vehicle via USB
      - ``mavproxy.py --master=/dev/cu.usbmodem1``	 
@@ -145,8 +146,9 @@ For other connection options see the `MAVProxy documentation <http://tridge.gith
 Loading DroneKit
 ================
 
-*DroneKit* is implemented as a *MAVProxy* module. You can automatically load this module into *MAVProxy*
-by `adding it to the startup script <http://tridge.github.io/MAVProxy/mavinit.html>`_ (**mavinit.scr**).
+*DroneKit* is implemented as a *MAVProxy* module (MAVProxy is installed automatically with DroneKit). 
+The best way to load the *DroneKit* module into *MAVProxy* is to 
+`add it to the startup script <http://tridge.github.io/MAVProxy/mavinit.html>`_ (**mavinit.scr**).
 
 Linux/MAC OSX:
 
@@ -213,34 +215,3 @@ The output should look something like that shown below
      Waiting for mode change ...
     Got MAVLink msg: COMMAND_ACK {command : 11, result : 0}
     ...
-
-
-
-.. _viewing_uav_on_map:
-
-Watching the action
-====================
-
-Watching your DroneKit script run inside *MAVProxy* is useful, but you can go one step further and watch the behaviour of your simulated vehicle in *Mission Planner*. 
-
-To do this you first need to get SITL to output to an additional UDP port of your computer:
-
-* Find the network IP address of your Windows computer (you can get this by running *ipconfig* in the *Windows Command Prompt*). 
-* In the command prompt *for your simulated environment* (SITL), add the IP address of the host computer (e.g. 192.168.2.10) and an unused port (e.g. 145502) as an output:
-  
-  .. code:: bash
-   
-      output add 192.168.2.10:14552
-
-Then connect Mission Planner to this 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. 
-  When prompted, enter the port number (in this case 14552).
-  
-  .. figure:: MissionPlanner_ConnectPort.png
-      :width: 50 %
-
-      Mission Planner: Listen Port Dialog
-
-After connecting, vehicle parameters will be loaded into *Mission Planner* and the vehicle is displayed on the map.

docs/guide/index.rst

@@ -10,6 +10,7 @@ The guide contains how-to documentation for using the DroneKit-Python API. These
 
     getting_started
     companion-computers
+    Simulated Vehicle <sitl_setup>
     vehicle_state_and_parameters
     taking_off
     debugging

docs/guide/sitl_setup.rst

@@ -0,0 +1,134 @@
+.. _sitle_setup:
+
+=====================================
+Setting up a Simulated Vehicle (SITL)
+=====================================
+
+The `SITL (software in the loop) <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/>`_ 
+simulator allows you to create and test DroneKit-Python apps without a real vehicle (and from the comfort of 
+your own developer desktop!)
+
+SITL runs natively on Linux and Windows, or within a virtual machine on Mac OSX, Linux or Windows. It can be 
+installed on the same computer as DroneKit, or on another computer on the same network.
+
+The sections below explain how set up SITL for the different operating systems, 
+and how you can set up SITL to connect to Mission Planner and DroneKit at the same time.
+
+Setting up SITL on Linux
+========================
+
+Build and install SITL on Linux using the instructions in: 
+`Setting up SITL on Linux <http://dev.ardupilot.com/wiki/setting-up-sitl-on-linux/>`_ (ArduPilot wiki)
+
+
+Setting up SITL on Windows
+==========================
+
+Build and install SITL on Windows using the instructions in:  
+`Setting up SITL on Windows <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/sitl-native-on-windows/>`_ 
+(ArduPilot wiki)
+
+
+.. _vagrant-sitl-from-full-image:
+
+Set up SITL using Vagrant (MacOS)
+=================================
+
+This section shows how to bring up a pre-built SITL instance hosted in a `Vagrant <https://www.vagrantup.com/>`_ 
+virtual machine. This approach should be used if you need to run SITL on MacOS. It can also be used for Windows 
+and Linux (though we recommend the native installations linked above).
+
+.. warning:: 
+
+       The Vagrant virtual machine is "headless" (has no UI) and so SITL cannot display the MAVProxy map and console. 
+       You can still see and send messages in the SITL Command Prompt.
+     
+
+#. Get the software for hosting the Simulator onto your computer (Windows, OS-X and Linux are supported):
+
+   * `Download and install VirtualBox <https://www.virtualbox.org/wiki/Downloads>`_.
+   * `Download and install Vagrant <https://www.vagrantup.com/downloads.html>`_.
+
+#. Install SSH (Windows only - SSH is present by default on Linux/Mac OSX)
+
+   * Download and install `Git for Windows <https://git-scm.com/download/win>`_ (or another client that comes with SSH).
+     After installing you can locate the file using the command ``C:\where ssh`` (normally it is installed to **C:\Program Files (x86)\Git\bin\ssh.exe**
+   * Add the ssh.exe location to the *Path* (**System Properties | Advanced tab | Environment Variables | Path**)
+
+#. Create a new directory where you will run *Vagrant*, and open a command prompt/terminal in it: 
+
+#. Enter the following commands to fetch a *Vagrantfile* for the pre-built SITL image:
+
+   .. code:: bash
+
+       vagrant init 3drobotics/ardupilot-sitl
+
+#. Launch the new image. This takes a long time the *first time* it is run while it downloads the image from the Internet.
+
+   .. code:: bash
+
+       vagrant up
+
+#. SSH into the vagrant instance, and start a vehicle:
+
+   .. code:: bash
+
+       vagrant ssh
+       ./sitl.sh
+   
+   When prompted, enter your desired vehicle (e.g. "copter") to build/start SITL.
+   Once complete, you will see a MAVProxy prompt displaying periodic vehicle-status updates: 
+
+   .. code:: bash
+
+       Ready to FLY  ublox Received 454 parameters
+       fence breach
+       APM: PreArm: RC not calibrated
+       ...
+
+.. _disable-arming-checks:
+
+#. Load a default set of parameters and disable the arming check:
+
+   .. code:: bash
+       
+       STABILIZE>param load ../Tools/autotest/copter_params.parm
+       STABILIZE>param set ARMING_CHECK 0
+
+   .. note:: 
+   
+       SITL simulates (by default) a vehicle that may not pass the arming check. This change makes the simulated
+       vehicle more forgiving, which allows the examples to arm and run. 
+	   
+       You should never disable the arming check in a script or on a real vehicle.
+
+
+.. _viewing_uav_on_map:
+
+Connecting an additional Ground Station
+=======================================
+
+This section explains how you can connect multiple ground stations to a running SITL instance in addition to your DroneKit MAVProxy link.
+
+To do this you first need to get SITL to output to an additional UDP port of your computer:
+
+* Find the network IP address of your computer (On Windows you can get this by running *ipconfig* in the *Windows Command Prompt*). 
+* In the *SITL Command Prompt*, add the IP address of the GCS computer (e.g. 192.168.2.10) and an unused port (e.g. 145502) as an output:
+  
+  .. code:: bash
+   
+      output add 192.168.2.10:14552
+
+Then connect Mission Planner to this 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. 
+  When prompted, enter the port number (in this case 14552).
+  
+  .. figure:: MissionPlanner_ConnectPort.png
+      :width: 50 %
+
+      Mission Planner: Listen Port Dialog
+
+After connecting, vehicle parameters will be loaded into *Mission Planner* and the vehicle is displayed on the map.
+

docs/index.rst

@@ -18,7 +18,6 @@ Contents:
     :maxdepth: 2
 
     Introduction <about/index>
-    quick_start
     guide/index
     examples/index
     contributing/index