Merge pull request dronekit#505 from dronekit/hgw_prgramming_guide

Restructured DroneKit Documentation

Author: mrpollo

docs/about/index.rst

@@ -12,6 +12,7 @@ After reading, you will understand what the kit offers and the opportunities it
 
    overview
    release_notes
+   migrating
    license
 
 

docs/guide/migrating.rst renamed to docs/about/migrating.rst

@@ -19,7 +19,7 @@ The sections below outline the main migration areas.
 Installation
 ============
 
-DKPY 2.0 is now installed from `pip` on all platforms - see :ref:`get-started` for more information.
+DKPY 2.0 is now installed from `pip` on all platforms - see :ref:`installing_dronekit` for more information.
 
 Installation is generally simpler than on DK 1.x because there are far fewer dependencies (both MAVProxy and numpy 
 are no longer needed).

docs/contributing/developer_setup_linux.rst

@@ -5,7 +5,8 @@ Building DroneKit-Python on Linux
 ===================================
 
 The setup for *developing* DroneKit-Python on Linux is almost the same as for *using* 
-DroneKit-Python. We therefore recommend that you start by following the instructions in :ref:`Getting Started <getting_started_installing_dronekit_linux>`. 
+DroneKit-Python. We therefore recommend that you start by following the instructions in 
+:ref:`installing_dronekit`. 
 
 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/contributing/developer_setup_windows.rst

@@ -11,7 +11,7 @@ Install DroneKit using WinPython command line
 =============================================
 
 
-First set up a command line DroneKit-Python installation using *WinPython*. This process is the same as described in :ref:`Getting Started <get_started_install_dk_windows>`.
+First set up a command line DroneKit-Python installation. We recommend *WinPython* or *ActivePython*, as discussed in :ref:`installing_dronekit`.
 
 
 

docs/guide/MissionPlanner_ConnectPort.png renamed to docs/develop/MissionPlanner_ConnectPort.png

@@ -0,0 +1,246 @@
+.. _best_practices:
+
+==============
+Best Practices
+==============
+
+This guide provides a broad overview of how to use the API, its main programming idioms 
+and best practices. More detail information is linked from each section.
+
+
+General considerations
+======================
+
+DroneKit-Python communicates with vehicle autopilots using the MAVLink protocol, 
+which defines how commands, telemetry and vehicle settings/parameters
+are sent between vehicles, companion computers, ground stations and other systems on
+a MAVLink network. 
+
+Some general considerations from using this protocol are:
+
+* Messages and message acknowledgments are not guaranteed to arrive (the protocol is not "lossless").
+* Commands may be silently ignored by the Autopilot if it is not in a state where it can
+  safely act on them. 
+* Command acknowledgment and completion messages are not sent in most cases
+  (and if sent, may not arrive).
+* Commands may be interrupted before completion.
+* Autopilots may choose to interpret the protocol in slightly different ways.
+* Commands can arrive at the autopilot from multiple sources.
+
+Developers should code defensively. Where possible:
+
+* Check that a vehicle is in a state to obey a command (for example, 
+  poll on :py:func:`Vehicle.is_armable <dronekit.Vehicle.is_armable>`
+  before trying to arm the vehicle).
+* Don't assume that a command has succeeded until the changed behaviour is observed.
+  In particular we recommend a launch sequence where you check that the mode and arming
+  have succeeded before attempting to take off.
+* Monitor for state changes and react accordingly. 
+  For example, if the user changes the mode from ``GUIDED`` your script should 
+  stop sending commands.
+* Verify that your script can run inside the normal latency limits for message passing
+  from the vehicle and tune any monitoring appropriately.
+
+
+Connecting
+==========
+
+In most cases you'll use the normal way to :ref:`connect to a vehicle <connecting_vehicle>`, 
+setting ``wait_ready=True`` to ensure that the vehicle is already populated with attributes
+when the :py:func:`connect() <dronekit.connect>` returns: 
+
+.. code:: python
+
+    from dronekit import connect
+
+    # Connect to the Vehicle (in this case a UDP endpoint)
+    vehicle = connect('REPLACE_connection_string_for_your_vehicle', wait_ready=True)
+    
+The ``connect()`` call will sometimes fail with an exception. 
+Additional information about an exception can be obtained by
+running the connect within a ``try-catch`` block as shown:
+
+.. code-block:: python
+    
+    import dronekit
+    import socket
+    import exceptions
+
+
+    try:
+        dronekit.connect('REPLACE_connection_string_for_your_vehicle', heartbeat_timeout=15)
+        
+    # Bad TCP connection
+    except socket.error:
+        print 'No server exists!'
+    except dronekit.APIException:
+        print 'Timeout!'
+ 
+    # Bad TTY connection
+    except exceptions.OSError as e:
+        print 'No serial exists!'
+    except dronekit.APIException:
+        print 'Timeout!'
+        
+    # Other error
+    except:
+        print 'Some other error!'
+
+.. tip::
+
+    The default ``heartbeat_timeout`` on connection is 30 sections. Usually a connection will 
+    succeed quite quickly, so you may wish to reduce this in the ``connect()`` method as shown in the 
+    code snippet above.
+    
+If a connection succeeds from a ground station, but not from DroneKit-Python it may be that your baud
+rate is incorrect for your hardware. This rate can also be set in the ``connect()`` method.
+
+
+Launch sequence
+===============
+
+Generally you should use the standard launch sequence described in :doc:`../guide/taking_off`:
+
+* Poll on :py:func:`Vehicle.is_armable <dronekit.Vehicle.is_armable>` 
+  until the vehicle is ready to arm.
+* Set the :py:attr:`Vehicle.mode <dronekit.Vehicle.mode>` to ``GUIDED``
+* Set :py:attr:`Vehicle.armed <dronekit.Vehicle.armed>` to ``True`` and 
+  poll on the same attribute until the vehicle is armed.
+* Call :py:func:`Vehicle.simple_takeoff <dronekit.Vehicle.simple_takeoff>` 
+  with a target altitude.
+* Poll on the altitude and allow the code to continue only when it is reached.
+
+The approach ensures that commands are only sent to the vehicle when it is able 
+to act on them (e.g. we know :py:func:`Vehicle.is_armable <dronekit.Vehicle.is_armable>` 
+is ``True`` before trying to arm, we know
+:py:attr:`Vehicle.armed <dronekit.Vehicle.armed>` is ``True`` before we take off).
+It also makes debugging takeoff problems a lot easier.
+
+
+Movement commands
+=================
+
+DroneKit-Python provides :py:func:`Vehicle.simple_goto <dronekit.Vehicle.simple_goto>` for moving to a specific position (at a defined speed). It is also possible to control movement by sending commands to specify the vehicle's :ref:`velocity components <guided_mode_copter_velocity_control>`. 
+
+.. note:: 
+
+    As with :py:func:`Vehicle.simple_takeoff <dronekit.Vehicle.simple_takeoff>`, movement 
+    commands are asynchronous, and will be interrupted if another command arrives 
+    before the vehicle reaches its target. Calling code should block and wait (or 
+    check that the operation is complete) before preceding to the next command.
+
+For more information see: :ref:`guided_mode_copter`.
+
+
+Vehicle information
+===================
+
+Vehicle state information is exposed through vehicle *attributes* which can be read and observed (and in some cases written)
+and vehicle settings which can be read, written, iterated and observed using *parameters* (a special attribute). All the attributes are documented in :doc:`../guide/vehicle_state_and_parameters`.
+
+Attributes are populated by MAVLink messages from the vehicle. 
+Information read from an attribute may not precisely reflect the actual value on the vehicle. Commands sent
+to the vehicle may not arrive, or may be ignored by the autopilot.
+
+If low-latency is critical, we recommend you verify that the update rate is achievable and 
+perhaps modify script behaviour if :py:attr:`Vehicle.last_heartbeat <dronekit.Vehicle.last_heartbeat>` falls outside
+a useful range.
+
+When setting attributes, poll their values to confirm that they have changed. This applies, in particular,
+to :py:attr:`Vehicle.armed <dronekit.Vehicle.armed>` and :py:attr:`Vehicle.mode <dronekit.Vehicle.mode>`.  
+
+
+
+Missions and waypoints
+======================
+
+DroneKit-Python can also :ref:`create and modify autonomous missions <auto_mode_vehicle_control>`.
+
+While it is possible to construct DroneKit-Python apps by dynamically constructing missions "on the fly", we recommend you use guided mode for Copter apps. This generally results in a better experience.
+
+.. tip::
+
+    If a mission command is not available in guided mode, 
+    it can be useful to switch to a mission and call it, then change 
+    back to normal guided mode operation.
+    
+
+Monitor and react to state changes
+==================================
+
+Almost all attributes can be observed - see :ref:`vehicle_state_observe_attributes` for more information.
+
+Exactly what state information you observe, and how you react to it, depends on your particular script:
+
+* Most standalone apps should monitor the :py:func:`Vehicle.mode <dronekit.Vehicle.mode>` and 
+  stop sending commands if the mode changes unexpectedly (this usually indicates 
+  that the user has taken control of the vehicle).
+* Apps might monitor :py:func:`Vehicle.last_heartbeat <dronekit.Vehicle.last_heartbeat>` 
+  and could attempt to reconnect if the value gets too high.
+* Apps could monitor :py:func:`Vehicle.system_status <dronekit.Vehicle.system_status>` 
+  for ``CRITICAL`` or ``EMERGENCY`` in order to implement specific emergency handling.
+
+
+Sleep the script when not needed
+================================
+
+Sleeping your script appropriately can reduce the memory overhead.
+
+For example, at low speeds you might only need to check whether you've reached a target every few seconds.
+Using ``time.sleep(2)`` between checks will be more efficient than checking more often.
+
+
+Exiting a script
+================
+
+Scripts should call :py:func:`Vehicle.close() <dronekit.Vehicle.close>` 
+before exiting to ensure that all messages have flushed before the script completes:
+
+.. code:: python
+
+    # About to exit script
+    vehicle.close()
+    
+
+Subclass Vehicle
+=====================================
+
+If you need to use functionality that is specific to particular hardware, we
+recommend you subclass :py:class:`Vehicle <dronekit.Vehicle>` and pass this new class into 
+:py:func:`connect() <dronekit.connect>`.
+
+:doc:`../examples/create_attribute` shows how you can do this.
+
+
+
+    
+Debugging
+=========
+
+DroneKit-Python apps are ordinary standalone Python scripts, and can be :doc:`debugged using standard Python methods <../guide/debugging>` (including the debugger/IDE of your choice). 
+
+    
+Launching scripts
+=================
+
+Scripts are run from an ordinary Python command prompt. For example:
+
+.. code:: bash
+
+    python some_python_script.py [arguments]
+
+Command line arguments are passed into the script as ``sys.argv`` variables (the normal)
+and you can use these directly or via an argument parser (e.g. 
+`argparse <https://docs.python.org/3/library/argparse.html>`_).
+
+
+Current script directory
+========================
+
+You can use normal Python methods for getting file system information:
+
+.. code-block:: python
+
+    import os.path
+    full_directory_path_of_current_script = os.path.dirname(os.path.abspath(__file__))
+

docs/develop/best_practice.rst

@@ -0,0 +1,14 @@
+.. _coding_standards:
+
+==========================
+Coding Standards
+==========================
+
+DroneKit-Python does not impose (or recommend) a particular set of coding standards
+for third party code.
+
+Internally we run the `YAPF formatter <https://github.com/google/yapf#introduction>`_
+on major releases and we expect contributors to copy the patterns used in similar
+code within the existing code base.
+
+ 

docs/develop/coding_standards.rst

@@ -0,0 +1,24 @@
+========================
+Developing with DroneKit 
+========================
+
+DroneKit-Python is primarily intended for use on Linux-based :doc:`companion-computers` that travel 
+on a vehicle and communicate with the autopilot via a serial port. It can also be used 
+on ground-based computers running Linux, Windows or Mac OSX (communicating using WiFi or a telemetry radio). 
+
+During development you'll generally run it on a development computer, communicating with a 
+:doc:`simulated vehicle<sitl_setup>` running on the same machine (via a UDP connection).
+
+This section contains topics explaining how to develop with DroneKit-Python, 
+covering subjects like installation, setting up the target vehicle or simulator, best practices 
+and coding standards.
+
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    companion-computers
+    Simulated Vehicle <sitl_setup>
+    best_practice
+    coding_standards

docs/guide/companion-computers.rst renamed to docs/develop/companion-computers.rst

@@ -0,0 +1,40 @@
+.. _installing_dronekit:
+
+===================
+Installing DroneKit
+===================
+
+DroneKit-Python can be installed on a Linux, Mac OSX, or Windows computer that 
+has *Python 2.7* and can install Python packages from the Internet.
+
+It is installed from **pip** on all platforms:
+
+.. code-block:: bash
+
+    pip install dronekit
+
+
+**Installation notes:**
+
+* Mac and Linux require you prefix the command with ``sudo``.
+    
+  .. code-block:: bash
+
+      sudo pip install dronekit
+      
+* On Linux you may need to first install **pip** and **python-dev**:
+    
+  .. code-block:: bash
+
+      sudo apt-get install python-pip python-dev
+      
+* :doc:`companion-computers` are likely to run on stripped down versions of Linux. Ensure
+  you use a variant that supports Python 2.7 and can install Python packages from the Internet.
+* Windows does not come with Python by default, but there are 
+  `many distributions available <https://www.python.org/download/alternatives/>`_. 
+  We have tested against:
+    
+  * `WinPython 2.7 64bit <http://sourceforge.net/projects/winpython/files/WinPython_2.7/>`_ (see 
+    `these instructions for installation and registration <https://github.com/winpython/winpython/wiki/Installation>`_). This is the most tested version.    
+  * `ActiveState ActivePython 2.7 <http://www.activestate.com/activepython/downloads>`_.
+* Python 3 is not supported.

docs/develop/index.rst

@@ -24,7 +24,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`). 
+and DroneKit have been set up as described in :ref:`installing_dronekit`). 
 
 In summary, after cloning the repository:
 

docs/develop/installation.rst

@@ -31,7 +31,7 @@ Running the example
 ===================
 
 The example can be run as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`).
+and DroneKit have been set up as described in :ref:`installing_dronekit`).
 
 In summary, after cloning the repository:
 

docs/guide/sitl_setup.rst renamed to docs/develop/sitl_setup.rst

@@ -21,7 +21,7 @@ Running the example
 ===================
 
 The example can be run much as described in :doc:`running_examples` (which in turn assumes that the vehicle
-and DroneKit have been set up as described in :ref:`get-started`). The main exception is that you need to 
+and DroneKit have been set up as described in :ref:`installing_dronekit`). The main exception is that you need to 
 install the CherryPy dependencies and view the behaviour in a web browser.
 
 If you're using a simulated vehicle remember to :ref:`disable arming checks <disable-arming-checks>` so