diff --git a/doc/_static/images/Android_SDK_Manager_Platform_tools.png b/doc/_static/images/Android_SDK_Manager_Platform_tools.png new file mode 100644 index 0000000000..8f51ad154f Binary files /dev/null and b/doc/_static/images/Android_SDK_Manager_Platform_tools.png differ diff --git a/doc/_static/images/Android_Studio_Import_Dronekit_Android.png b/doc/_static/images/Android_Studio_Import_Dronekit_Android.png new file mode 100644 index 0000000000..718f2074cb Binary files /dev/null and b/doc/_static/images/Android_Studio_Import_Dronekit_Android.png differ diff --git a/doc/contributing_building_from_source.rst b/doc/contributing_building_from_source.rst new file mode 100644 index 0000000000..f01b0c0ae2 --- /dev/null +++ b/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 modify and build the +*3DR Services* source code, which contains the DroneKit-Android client library (**ClientLib**). + +The build process creates a +`.aar file `_ +*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 `_. + +#. 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 `_. + +#. 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. \ No newline at end of file diff --git a/doc/contributing_working_with_releases.rst b/doc/contributing_working_with_releases.rst new file mode 100644 index 0000000000..73234a044c --- /dev/null +++ b/doc/contributing_working_with_releases.rst @@ -0,0 +1,57 @@ +===================== +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 `_ (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 `_ 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) `_. + + + +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/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 `_ + and instructions for using `Hardware Devices are here `_. + + 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 `_ and install it + (replacing any exciting version). For example, running adb from the **platform-tools** directory, + we might install a file as shown + + + .. code-block:: bash + + > adb install -r 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 + + +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. \ No newline at end of file diff --git a/doc/first_app.rst b/doc/first_app.rst index 654097ba4c..cfe229ee75 100644 --- a/doc/first_app.rst +++ b/doc/first_app.rst @@ -30,7 +30,8 @@ Adding the Client Library To add the 3DR Services library to your project: -#. Open **build.gradle (Module:app)** and, under the dependencies section, add: +#. Open **build.gradle (Module:app)** and, under the dependencies section add a + reference to the 3DR Services Client library: .. code-block:: bash @@ -52,25 +53,25 @@ Implement a ``TowerListener`` on your ``MainActivity`` to listen for events sent :linenos: :emphasize-lines: 1,4-12 - public class MainActivity extends ActionBarActivity implements TowerListener { + public class MainActivity extends ActionBarActivity implements TowerListener { - // 3DR Services Listener - @Override - public void onTowerConnected() { - - } + // 3DR Services Listener + @Override + public void onTowerConnected() { - @Override - public void onTowerDisconnected() { - - } + } - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.activity_main); - } - } + @Override + public void onTowerDisconnected() { + + } + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + } + } Now you'll need to: @@ -116,7 +117,7 @@ Now you'll need to: @Override public void onTowerDisconnected() { - + } @Override @@ -148,65 +149,65 @@ Now that you have a virtual drone, let’s add the ability to connect to it. First, declare that your ``MainActivity`` can act as an interface for DroneListener and implement some methods to listen for drone events. .. code-block:: java - :linenos: - :emphasize-lines: 1-15 + :linenos: + :emphasize-lines: 1-15 - public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { - @Override - public void onDroneEvent(String event, Bundle extras) { + public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { + @Override + public void onDroneEvent(String event, Bundle extras) { + + } - } + @Override + public void onDroneConnectionFailed(ConnectionResult result) { - @Override - public void onDroneConnectionFailed(ConnectionResult result) { - - } + } - @Override - public void onDroneServiceInterrupted(String errorMsg) { + @Override + public void onDroneServiceInterrupted(String errorMsg) { - } + } - ... - } + ... + } Next, add an instance variable to the top of your ``MainActivity`` to keep track of the drone instance. .. code-block:: java - :linenos: - :emphasize-lines: 2-3 + :linenos: + :emphasize-lines: 2-3 - public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { - private Drone drone; - private int droneType = Type.TYPE_UNKNOWN; + public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { + private Drone drone; + private int droneType = Type.TYPE_UNKNOWN; In order to register with the control tower, the drone instance needs a generic Android handler. Go ahead and add a handler where you declare your instance variables. .. code-block:: java - :linenos: - :emphasize-lines: 4 + :linenos: + :emphasize-lines: 4 - public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { - private Drone drone; - private int droneType = Type.TYPE_UNKNOWN; - private final Handler handler = new Handler(); + public class MainActivity extends ActionBarActivity implements DroneListener, TowerListener { + private Drone drone; + private int droneType = Type.TYPE_UNKNOWN; + private final Handler handler = new Handler(); Add an instantiation of the new drone upon the creation of your ``MainActivity``. After creation, the new drone will need to be registered with the control tower to be active. .. code-block:: java - :linenos: - :emphasize-lines: 7 - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.activity_main); - - this.serviceManager = new ServiceManager(getApplicationContext()); - this.drone = new Drone(); - } + :linenos: + :emphasize-lines: 7 + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + this.serviceManager = new ServiceManager(getApplicationContext()); + this.drone = new Drone(); + } @Override public void onTowerConnected() { @@ -218,33 +219,33 @@ Add an instantiation of the new drone upon the creation of your ``MainActivity`` Make sure that when the ``MainActivity`` is stopped, the drone is unregistered from the control tower. .. code-block:: java - :linenos: - :emphasize-lines: 4-8 - - @Override - public void onStop() { - super.onStop(); - if (this.drone.isConnected()) { - this.drone.disconnect(); - updateConnectedButton(false); - } + :linenos: + :emphasize-lines: 4-8 + + @Override + public void onStop() { + super.onStop(); + if (this.drone.isConnected()) { + this.drone.disconnect(); + updateConnectedButton(false); + } this.controlTower.unregisterDrone(this.drone); this.controlTower.disconnect(); - } + } Now let's add a button in **activity_main.xml** that will connect to the drone on press. Open **activity_main.xml** and add the following: .. code-block:: xml - :linenos: + :linenos: -