Site Tools


Android Build Instructions

This section explains the steps to build the IoTivity project for Android.

This section assumes that you have completed the steps in "How to use IoTivity Gerrit" .

Prerequisites for building IoTivity for Android

  • A working Internet connection. During the process of the SCons build, the build script will need to download some or all of the following software from these respective sites especially if it is the first time you are building and/or if new versions of the Android Tools are detected. This is one time set-up requirement:
  • The installation script uses the pre-installed system variables if they are set. These system variables can be used as the location on your Android Tools that you already have installed on your development system. Otherwise they will be pulled down automatically as part of the initial one time set-up requirement if they are not found in the default paths. Here is a list of system variables:
System Variables Description Default Path (if they are not set)
GRADLE_HOME Path to Gradle GRADLE_HOME=<iotivity>/extlibs/android/gradle
ANDROID_NDK Path to Android NDK ANDROID_NDK=<iotivity>/extlibs/android/ndk
ANDROID_HOME Path to Android SDK ANDROID_HOME=<iotivity>/extlibs/android/sdk

Step 1: Installing the JDK

To install and verify OpenJDK 1.7 or later on Ubuntu, perform the steps shown below. The examples shown are for installing OpenJDK 1.7.

  1. At a command prompt, enter the following commands:
    $ sudo apt-get update 
    $ sudo apt-get install openjdk-7-jdk
  2. When installation is complete, check the install by issuing the following command:
    $ java -version
  3. The installation is correct if the output text contains the following:
    java version "1.7..."

Step 2: Build Steps for Android

  1. Navigate to the root directory of the downloaded IoTivity project using the terminal window. In the examples that follow, we use <iotivity> to refer to the root directory of the IoTivity project.
  2. The basic command to build IoTivity for Android is shown below:
    $ scons TARGET_OS=android

    This builds IoTivity for Android using the default values for architecture, transport, mode, and security.

In addition to TARGET_OS , the following command-line argument options can be passed to the SCons build script to build IoTivity for Android:

TARGET_ARCH Supported architectures:
x86 (default)
TARGET_TRANSPORT Supported transport types:
ALL (default)
Note: You may also build permutations of the above options by passing a comma-separated list.
RELEASE Supported release modes:
1 (release mode) (default)
0 (debug mode)
SECURED Supported security modes: DTLS (Datagram Transport Layer Security)
1 (DTLS enabled) (default)
0 (DTLS disabled)
ANDROID_HOME This takes the path to the Android SDK (if installed). If not, the SCons script will try to install Android SDK.
ANDROID_NDK This takes the path to the Android NDK (if installed). If not, the SCons script will try to install Android NDK.
ANDROID_GRADLE This takes the path to the Gradle bin (if installed). If not, the SCons script will install Gradle.

The SCons build command including all the optional arguments for building IoTivity for Android might look like the example shown below:

$ scons TARGET_OS=android TARGET_ARCH=<target arch> TARGET_TRANSPORT=<target transport> RELEASE=<release mode> SECURED=<secure> ANDROID_HOME=<path to android SDK> ANDROID_NDK=<path to android NDK> ANDROID_GRADLE=<path to gradle/bin>

Step 3: Binary Output Files for Android

The basic command shown in Step 2 creates the binary distribution of the IoTivity Base Android API.

The output directory of the IoTivity Base Android API (.aar file) build is:

<iotivity>/java/iotivity-android/build/outputs/aar/iotivity-base-<release mode>.aar

The above command also builds all the android example apps.

The output directory for each example APK can be found at:

<iotivity>/java/android-examples/<example name>/build/outputs/apk/<example name>-<release mode>.apk

Note: for convenience, a script ( is provided to run possible build at once. Following is the usage:

To build:

   $ <path-to-android-ndk>

To clean:

   $ -c

Android Build Error Message

If you see the following build error message :

The Android SDK Manager should automatically come up as follows:

Note: If the Android SDK Manager does not automatically come up make sure you are physically building on your development system or vnc into your system. The GUI will not pop up if you are just “ssh” into development system.

Just as the instructions say the Android SDK Manager GUI appears:

1. Under "Tools" select "Android SDK Build-tools" Revision 20.
2. Under "Android 5.0.1 (API 21)" select "SDK Platform"

After selecting the correct packages click on the “Install 2 Packages…” button and the following license dialogue box will come up:

Accepted all the licenses and click on the “Install” button. All the packages will install and the following Android SDK Manager Log dialogue box will come up when done.

You can now close Android SDK Manager Log and Android SDK Manager Application.

Note: If you installed the correct packages required the build system that build will continue on with the build and is one time set-up requirement as you do not delete the the android directory (i.e. gradle, ndk, and/or sdk directories).

Android Example Apps

After the IoTivity Base Android API and the example apps have been built, you can run the example apps on either the emulator or an android device.

The example android apps that you built in Step 2 can be found at:

<iotivity>/java/examples-android/<example name>/build/outputs/apk/<example name>-<release mode>.apk

Note : Iotivity main code build architecture and target emulator or an android device architecture should be same.

Below have possible architecture of apk files.

List of Android Example Apps

Below is a list of the android example apps. Most of the apps come in client-server pairs and need to be run together; note that the server apps should be started before the client apps.

Example Description
SimpleServer and SimpleClient A basic sample for hosting, discovering and performing GET, PUT, POST and OBSERVE operations on a resource. We recommend that you start with these two apps.
DeviceDiscoveryServer and DeviceDiscoveryClient Samples for the Platform and Device Discovery APIs.
FridgeServer and FridgeClient Fridge samples provide usage of constructResourceObject API.
FridgeGroupServer and FridgeGroupClient FridgeGroup samples provide usage of constructResourceObject API, default device entity handler and header options support.
GroupServer and GroupClient Example for demonstrating grouping resources into collections, discovering them and performing operations on them.
PresenceServer and PresenceClient Presence samples to demonstrate the usage of the Presence APIs.
ProvisioningClient Example for demonstrating Provisioning Manager

Running Android Example Apps

Android example apps can be run on Android Lollipop (5.0 and above). If running on an android device, please perform the following steps:

  1. Connect the android device to the computer with a USB cable.
  2. Enable USB Debugging on the android device by doing the following:
    1. On the android device, open Settings.
    2. Tap About tablet. If your android device is a phone, this option is About phone.
    3. Tap Build Number seven times. If a note appears: “No need, you are already a developer”, Developer Options is already available on the Settings pane under System.
    4. In Settings, in the System group, tap Developer Options. The Developer Options pane is displayed.
    5. Under Debugging, tap USB debugging.

      A query displays on the device.
    6. Tap OK. A green toggle indicates USB debugging is enabled.
  3. Verify that you can communicate with the android device. Open a terminal window and send the following command:
    $ adb devices

    Note: adb can be found at <path to Android sdk>/platform-tools.
    You should see something similar to the following output:

    List of devices attached 5C7DJ06J

    After your device is listed, you can install any example app APK on the device and run it.

  4. To install an APK on the device, run the following command from the terminal:
    $ adb install <iotivity>/java/examples-android/<example_name>/build/outputs/apk/<apk name>

    For example, assuming the APK location hasn't been changed, run the following command to install the simpleserver app APK on the device:

    $ adb install <iotivity>/java/examples-android/simpleserver/build/outputs/apk/simpleserver-release.apk

Using IoTivity Base Android API in an Android Studio Project

This section lists the steps to use the binary distribution of the IoTivity Base Android API in an Android Studio project.

The binary distribution of the IoTivity Base Android API (a .aar file) that you built previously can be found at:

<iotivity>/java/iotivity-android/build/outputs/aar/iotivity-base-<your arch>-<release mode>.aar

To import IoTivity Base Android API module into an existing Android Studio project, skip to Step 4.

Step 3: Create a New Project in Android Studio

  1. In Android Studio, create a new project.
  2. On the Configure your new project pane, fill in all the required fields and click Next.
  3. On the Select the form factors your app will run on pane, do the following:
    1. Check the box for Phone and Tablet.
    2. For Minimum SDK, select API 21: Android 5.0 (Lollipop).
    3. Leave all the other options unchecked and click Next.
  4. On the Add an activity to… pane, select the desired activity template and click Next.
  5. On the Choose options for your new file pane, for the Activity Name field, enter a name and click Finish.

Step 4: Import IoTivity Base Android API Binary Into an Android Studio Project

  1. From the File menu, select New Module.
  2. In the Choose Module Type window, do the following:
    1. Select Import .JAR or .AAR Package.
    2. Click Next.
  3. In the Create New Module window, click the button to locate the .aar file.
  4. Navigate to the <iotivity>/java/iotivity-android/base/build/outputs/aar directory and select the .aar file. In the example below, we selected iotivity-base-armeabi-release.aar.
  5. Click OK. Then in the Create New Module window, click Finish.
  6. In the Android Studio project view, right click the dependent module and select Open Module Settings.
  7. In the Project Structure window, select the Dependencies tab.
  8. Right click the + icon. From the dropdown, select Module dependency.
  9. Select the iotivity-base-<target arch>-<release> module from the list of available modules and click Ok.
    In the example below, we selected iotivity-base-armeabi-release.
  10. In the Project Structure window, click Ok.
    Android Studio rebuilds the module, including the contents of the library module the next time the project or module is built.
    IoTivity Base Android APIs can now be used in the Android Studio project.

Generate JavaDocs for the Android API

To generate JavaDocs for the Android API, do the following:

  1. Go to the resource/docs directory:
    <iotivity> $ cd resource/docs
  2. Execute the following command:
     $ ./

    This creates a Java_API directory to contain the JavaDocs for Android API in the current directory.

  3. Open the index.html file inside Java_API for explanation of the Android API.

This concludes the procedures.

android_build_instructions.txt · Last modified: 2018/10/10 12:50 by sanjaygrl