New topic for installing old releases

doc/contributing_building_from_source.rst

@@ -0,0 +1,105 @@
+=====================================
+Building DroneKit-Android from Source
+=====================================
+
+Developers who want to contribute to DroneKit-Android will need to to modify and build the 
+*3DR Services* (**ServiceApp**) source code, which contains the DroneKit-Android client library (**ClientLib**).
+
+The build process creates a 
+`.aar file <https://sites.google.com/a/android.com/tools/tech-docs/new-build-system/aar-format>`_ 
+*definition* of the client API. In order to use the modifications your DroneKit-Android apps must specify 
+this file as a dependency rather than the definition file hosted online for official releases.
+
+.. tip::
+
+    If you just want to access old releases you don't need to rebuild the source 
+    (see :doc:`contributing_working_with_releases` for more information).
+
+
+
+Build 3DR Services App (DroneKit-Android)
+=========================================
+
+The steps to modify and build the *3DR Services* app are:
+
+#. Fork and clone the `DroneKit-Android Repo <https://github.com/dronekit/dronekit-android>`_. 
+
+#. Import the project root directory into Android Studio. Android Studio will automatically recognize all the sub-apps inside), as shown below:
+
+   .. figure:: _static/images/Android_Studio_Import_Dronekit_Android.png
+       :width: 400px
+
+#. Modify DroneKit-Android as needed.
+
+   .. tip::
+
+       You might want to skip this step for now and come back when you've verified that you can built the project.
+
+#. Build the project (**Build | Rebuild Project**). 
+
+
+   .. note:: 
+
+       Android Studio will generate an **.aar** file in the directory **DroneKit-Android/ClientLib/build/outputs/aar/** 
+       (for example, **dronekit-android.2.7.0.aar**). This file contains the definition of the locally built 
+       DroneKit-Android client API, including any changes you made to the project. This is the dependency file that
+       DroneKit-Android apps will have to link against in order to access your new functionality.
+
+       The version number of the **.aar** file is generated automatically.
+
+#. Select the **Run** button in Android-Studio (with your Android device connected). 
+   This will install your rebuilt *3DR Services* app to your device. 
+
+
+
+Update your DroneKit-Android App
+================================
+
+This section shows how to update your project to use the locally generated *aar* file created in the previous section (instead of
+the cloud hosted definition used when making releases).
+
+For easy comparison with the "normal" case, here we use the same *Hello Drone Android App* described earlier.
+
+#. Fork and Clone `Hello Drone Android App <https://github.com/3drobotics/DroneKit-Android-Starter>`_.
+
+#. Open the app in Android Studio. 
+
+#. Update the app build dependencies so that it uses the local **.aar** file rather than the definition in the online repo:
+
+   * Find **build.gradle** file for the project and open it. 
+     Add a ``flatDir`` attribute inside the ``allprojects | repositories`` entry. 
+     This should contain the path to the directory **DroneKit-Android/ClientLib/build/outputs/aar**:
+
+     .. code-block:: text
+         :emphasize-lines: 5-7
+
+         allprojects {
+             repositories {
+                 jcenter()
+
+                 flatDir {
+                     dirs 'libs','../../DroneKit-Android/ClientLib/build/outputs/aar'
+                 }
+
+             }
+         }
+
+   * Find the *build.gradle* (for the Module:app) and open it. Find the entry for the online definition of
+     DroneKit-Android ``compile 'com.o3dr.android:dronekit-android:2.3.+'`` 
+     and replace it with the local file ``compile(name:'dronekit-android.2.7.0', ext:'aar')``:
+
+     .. code-block:: cpp
+         :emphasize-lines: 5-6
+
+         dependencies {
+             compile fileTree(dir: 'libs', include: ['*.jar'])
+             compile 'com.android.support:appcompat-v7:21.0.3'
+
+             // compile 'com.o3dr.android:dronekit-android:2.3.+' 
+             compile(name:'dronekit-android.2.7.0', ext:'aar')
+         }
+
+
+#. Save everything and then select the *Android-Studio* menu: **Tools | Android | Sync Android with Gradle Files**. This will automatically search all dependency libs (including our local DroneKit build) and link it in our code.
+
+That's it - the build process will now use your locally created version of DroneKit-Android.

doc/contributing_working_with_releases.rst

@@ -0,0 +1,61 @@
+=====================
+Working with Releases
+=====================
+
+The latest stable version of the *3DR Services App* (which contains the DroneKit-Android Client library) 
+can be always be installed from the 
+`Play Store <https://play.google.com/store/apps/details?id=org.droidplanner.services.android>`_ (on both
+devices and on the Android simulator).
+
+Sometimes it is useful to be able to access new features that are available only in beta releases, or to test your
+application against older releases. In this case you will need to install the appropriate Android application package (APK).
+
+You can find all releases (beta and stable) on the `Project Releases <https://github.com/dronekit/dronekit-android/releases>`_ page on
+Github, along with source code for the release. The file's with extension **.apk** can be installed using the 
+`Android Debug Bridge tool (adb) <http://developer.android.com/tools/help/adb.html>`_.
+
+
+
+Installation steps
+==================
+
+#. Install the **adb** tool using the *Android SDK Manager*.
+
+   .. figure:: _static/images/Android_SDK_Manager_Platform_tools.png
+
+   The tool is part of the *Android SDK Platform tools* as shown. 
+   It is installed to *<sdk path>/sdk/platform-tools*. The path to the **sdk** is shown in the SDK Manager
+   above (highlighted in blue).
+
+#. Connect your device. Instructions for launching a `virtual device are here <http://developer.android.com/tools/devices/index.html>`_
+   and instructions for using `Hardware Devices are here <http://developer.android.com/tools/device.html>`_.
+
+   You can verify the connection by running *adb*:
+
+   .. code-block:: bash
+
+       > adb devices
+
+       List of devices attached
+       3204672ab49bc1f5        device
+
+#. Download the `adk file/release of interest <https://github.com/dronekit/dronekit-android/releases>`_ and install it.
+   For example, running adb from the **platform-tools** directory, we might install a file as shown
+
+
+   .. code-block:: bash
+
+       > adb install D:\MyFiles\3dr-services-release.104022.apk
+
+       5331 KB/s (3762561 bytes in 0.689s)
+               pkg: /data/local/tmp/3dr-services-release.104022.apk
+       Success
+
+   .. note:: 
+
+       Installation will fail if a version of the file already exists. 
+       If you need to install a new version, manually uninstall the old
+       version first/.
+
+After installation the *3DR Services* app icon will appear on your device. You can confirm the version is 
+correct by viewing the version string in the app footer.