Skip to content

O
opencv
Commit a682ee40 authored by Andrey Pavlenko's avatar Andrey Pavlenko
Browse files
Options

android tutorial, part 1 - adding 'device connection via usb' section, sections reordering

parent 40c76b9d
Hide whitespace changes
Inline Side-by-side
Showing with 125 additions and 101 deletions
doc/tutorials/introduction/android_binary_package/android_dev_intro.rst
View file @ a682ee40
......@@ -11,77 +11,6 @@ This guide was written with Windows 7 in mind, though it works with Linux (Ubunt
If you encounter any error after thoroughly following these steps, feel free to contact us via `OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
Android application structure
=============================
Usually source code of an Android application has the following structure:
+ :file:`root folder of the project/`
- :file:`jni/`
- :file:`libs/`
- :file:`res/`
- :file:`src/`
- :file:`AndroidManifest.xml`
- :file:`project.properties`
- :file:`... other files ...`
where:
* the :file:`src` folder contains Java code of the application,
* the :file:`res` folder contains resources of the application (images, xml files describing UI layout , etc),
* the :file:`libs` folder will contain native libraries after a successful build,
* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts :file:`Android.mk` and :file:`Application.mk`
producing the native libraries,
* :file:`AndroidManifest.xml` file presents essential information about application to the Android system
(name of the Application, name of main application's package, components of the application, required permissions, etc).
It can be created using Eclipse wizard or :command:`android` tool from Android SDK.
* :file:`project.properties` is a text file containing information about target Android platform and other build details.
This file is generated by Eclipse or can be created with :command:`android` tool included in Android SDK.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application,
since Android NDK build system relies on them. If any of these files does not exist, compile the Java part of the project before the C++ part.
:file:`Android.mk` and :file:`Application.mk` scripts
==================================================================
The script :file:`Android.mk` usually has the following structure:
.. code-block:: make
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := <module_name>
LOCAL_SRC_FILES := <list of .c and .cpp project files>
<some variable name> := <some variable value>
...
<some variable name> := <some variable value>
include $(BUILD_SHARED_LIBRARY)
This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`.
Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`:
.. code-block:: make
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := armeabi-v7a
Quick environment setup for Android development
===============================================
......@@ -251,6 +180,77 @@ You need the following software to be installed in order to develop for Android
That's it. Compilation of C++ code is fully integrated into Eclipse building process now.
Android application structure
=============================
Usually source code of an Android application has the following structure:
+ :file:`root folder of the project/`
- :file:`jni/`
- :file:`libs/`
- :file:`res/`
- :file:`src/`
- :file:`AndroidManifest.xml`
- :file:`project.properties`
- :file:`... other files ...`
where:
* the :file:`src` folder contains Java code of the application,
* the :file:`res` folder contains resources of the application (images, xml files describing UI layout , etc),
* the :file:`libs` folder will contain native libraries after a successful build,
* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts :file:`Android.mk` and :file:`Application.mk`
producing the native libraries,
* :file:`AndroidManifest.xml` file presents essential information about application to the Android system
(name of the Application, name of main application's package, components of the application, required permissions, etc).
It can be created using Eclipse wizard or :command:`android` tool from Android SDK.
* :file:`project.properties` is a text file containing information about target Android platform and other build details.
This file is generated by Eclipse or can be created with :command:`android` tool included in Android SDK.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application,
since Android NDK build system relies on them. If any of these files does not exist, compile the Java part of the project before the C++ part.
:file:`Android.mk` and :file:`Application.mk` scripts
==================================================================
The script :file:`Android.mk` usually has the following structure:
.. code-block:: make
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := <module_name>
LOCAL_SRC_FILES := <list of .c and .cpp project files>
<some variable name> := <some variable value>
...
<some variable name> := <some variable value>
include $(BUILD_SHARED_LIBRARY)
This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`.
Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`:
.. code-block:: make
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := armeabi-v7a
Debugging and Testing
=====================
In this section we will give you some easy-to-follow instructions on how to set up an emulator or hardware device for testing and debugging an Android project.
......@@ -263,9 +263,9 @@ AVD (*Android Virtual Device*) is not probably the most convenient way to test a
**TBD:** how to start AVD Manager without Eclipse...
#. Press the :guilabel:`New` button in :guilabel:`AVD Manager` window.
#. :guilabel:`Create new Android Virtual Device` window will let you select some properties for your new device, like target API level, size of SD-card and other.
.. image:: images/AVD_create.png
:alt: Configure builders
:align: center
.. image:: images/AVD_create.png
:alt: Configure builders
:align: center
#. When you click the :guilabel:`Create AVD` button, your new AVD will be availible in :guilabel:`AVD Manager`.
#. Press :guilabel:`Start` to launch the device. Be aware that any AVD (aka Emulator) is usually much slower than a hardware Android device, so it may take up to several minutes to start.
#. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one.
......@@ -274,41 +274,65 @@ Hardware Device
---------------
If you have an Android device, you can use it to test and debug your applications. This way is more authentic, though a little bit harder to set up.
Windows host computer
^^^^^^^^^^^^^^^^^^^^^
#. Enable USB debugging on the Android device (settings menu).
#. Attach the Android device to your PC with a USB cable.
#. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`. Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permittions.
#. Select :guilabel:`Device Manager` in the left pane and find an unknown device in the list. You may try unplugging it and then plugging back in order to check whether it's your exact equipment appearing in the list.
#. Right-click on your device to get to :guilabel:`Properties` and select the :guilabel:`Details` tab. Select :guilabel:`Device ID` and save both numbers (*e.g in a text file*).
.. image:: images/device_details.png
:alt: Details
:align: center
#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. You will see some default records there, perhaps looking similar to this:
.. code-block:: ini
;Google Nexus One
%SingleAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02
%CompositeAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02&MI_01
#. There should be a record like this for your device and since it hasn't appeared automatically you are free to add one manually. All you should do is to add another record similar to the above, but using the numbers you saved earlier. Second number goes to the first line and the first one goes to the second line. Notice, that the record should be inserted under *[Google.NTx86]* or *[Google.NTamd64]* tag, depending on what system you're currently running. For example, in my case it was Nvidia Tegra device and the record looked like this:
.. code-block:: ini
;NVIDIA Tegra
%SingleAdbInterface% = USB_Install, USB\VID_0955&PID_7100&MI_01
%CompositeAdbInterface% = USB_Install, USB\VID_0955&PID_7100&REV_9999&MI_01
#. Assuming you have your SDK installed to :file:`C:/android-sdk/`, you may try the following command in Windows console to acertain that your device was recognised and attached:
.. code-block:: ini
C:\android-sdk\platform-tools\adb devices
.. image:: images/cmd_adb_devices.png
:alt: Console
:align: center
.. image:: images/usb_device_connect_01.png
:alt: Unknown device
:align: center
#. Right-click on the unknoen device, select :guilabel:`Properties` then select the :guilabel:`Details` tab. Select :guilabel:`Hardware Ids` and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
.. image:: images/usb_device_connect_02.png
:alt: Device properties details
:align: center
#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. Select either ``Google.NTx86`` or ``Google.NTamd64`` section depending on your host system architecture.
.. image:: images/usb_device_connect_03.png
:alt: Device properties details
:align: center
#. There should be a record like existing ones for your device and you need to add one manually.
.. image:: images/usb_device_connect_04.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_05.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_06.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_07.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_08.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_09.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_10.png
:alt: Device properties details
:align: center
#. TBD.
.. image:: images/usb_device_connect_11.png
:alt: Device properties details
:align: center
#. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the devices.
Consult the official `Android Developers site <http://developer.android.com/tools/device.html>`_ for more information on configuring hardware devices to work with other operating systems.
**TODO:** Describe device setup on Linux & OSX.
Linux & MacOS host computer
^^^^^^^^^^^^^^^^^^^^^^^^^^^
**TODO:** Describe device setup.
What's next
===========
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment