README.md 6.97 KB
Newer Older
Larry Sachs's avatar
Larry Sachs committed
1
IoTivity-Lite Android port
George Nash's avatar
George Nash committed
2
=================================================
Larry Sachs's avatar
Larry Sachs committed
3 4

Getting Started
George Nash's avatar
George Nash committed
5
-------------------------------------------------
Larry Sachs's avatar
Larry Sachs committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
To use this code you will need the following:
  - git version control system
  - IoTivity-lite
  - SWIG
  - Java Development kit.
  - Android SDK
  - Android NDK
  - Gradle build system

The following contains instructions to obtain and run the tools on Linux.

### Get Tools
It can be installed on Ubuntu Linux using the following command.

    sudo apt-get install git make openjdk-8-jdk swig

### Get IoTivity-Lite
Checkout IoTivity-lite git project run the following command to get a anonymous copy of
24
iotivity-lite.
Larry Sachs's avatar
Larry Sachs committed
25

26
    git clone https://gitlab.iotivity.org/iotivity/iotivity-lite.git
Larry Sachs's avatar
Larry Sachs committed
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74

### Android SDK tools
Download the [Android SDK command line tools](https://developer.android.com/studio#downloads)
run `sdkmanager` found in the `tools/bin` directory to install the platform-tools and Android platform

    ./sdkmanager "platform-tools" "platforms;android-23"

if behind a proxy use the proxy connection options

    ./sdkmanager --proxy=<http|socks> --proxy_host=<host address> --proxy_port=<number> "platform-tools" "platforms;android-23"

### Android NDK
Download Android NDK

https://developer.android.com/ndk/downloads/index.html

Unzip downloaded package.

    cd <NDK>/build/tools
    sudo apt-get install python
    ./make_standalone_toolchain.py --arch <architecture> --api <level> --install-dir <path>

valid values for `--arch`
 - arm
 - arm64
 - x86
 - x86_64

The `make_standalone_toolchain` script only supports api level 16 and newer. We recommend using api
level 23 or newer.

For example:

    ./make_standalone_toolchain.py --arch arm --api 23 --install-dir ~/android-arm-23

Note: running the `make_standalone_toolchain.py` script may print a WARNING stating it is no longer
necessary.  This is expected.  At this time the make files expect the stand alone tool chain.

For further setup see:

https://developer.android.com/ndk/guides/standalone_toolchain.html

### Android Studio (optional)
Developers wishing to use Android Studio can find details here:

[Android Studio](https://developer.android.com/studio)

Building IoTivity-Lite libraries
George Nash's avatar
George Nash committed
75
-------------------------------------------------
76
To build for Android cd to
Larry Sachs's avatar
Larry Sachs committed
77 78 79

    cd <iotivity-lite>/android/port

80
The Makefile uses then the Android NDK that was installed above.
Larry Sachs's avatar
Larry Sachs committed
81

82
Either set ANDROID_API and ANDROID_BASE in the Makefile or invoke like this:
Larry Sachs's avatar
Larry Sachs committed
83 84 85 86 87

    make NDK_HOME=/opt/android-ndk ANDROID_API=23

Example Usage:

88
    make IPV4=1 DEBUG=1
Larry Sachs's avatar
Larry Sachs committed
89 90 91

or

92
    make NDK_HOME=~/android-arm-23 ANDROID_API=23 IPV4=1 DEBUG=1
Larry Sachs's avatar
Larry Sachs committed
93

94 95
The Make file will build and copy the library files (*.so and *.jar) into the
provided samples.
Larry Sachs's avatar
Larry Sachs committed
96

97 98 99
If developing your own project you may need to manually copy the libraries from
`<iotivity-lite-root>/swig/iotivity-lite-java/libs` to the location expected
by your project.
Larry Sachs's avatar
Larry Sachs committed
100 101

Building and Running Samples
George Nash's avatar
George Nash committed
102
-------------------------------------------------
Larry Sachs's avatar
Larry Sachs committed
103 104
All samples have the default out of the box behavior of IoTivity-Lite which means they are are not
onboarded or provisioned.  The default security will prevent the samples from communicating with
105 106
one another till onboarding and provisioning has been completed.  See **Onboarding and Provisioning**
section of the top level README file for instructions on using the onboarding tool that is part of
Larry Sachs's avatar
Larry Sachs committed
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
iotivity-lite.

A sample server and client can be found in `<iotivity-lite>/swig/apps/<sample>`

Note that gradlew will require a `local.properties` to exist or ANDROID_HOME to be defined.  An
installation of Android Studio should create the `local.properties` file.

example:

    export ANDROID_HOME=~/Android/sdk

To resolve any proxy issues reference [gradle user guide for proxy](https://docs.gradle.org/current/userguide/build_environment.html#sec:accessing_the_web_via_a_proxy)

The server sample is in `android_simple_server/SimpleServer`.  To build and install the sample
execute the following command:

### Method 1
    ./gradlew installDebug

### Method 2
    ./gradlew assembleDebug

To install

    cd app/build/outputs/apk
    adb install app-armeabi-debug.apk

The client sample is in `android_simple_client/SimpleClient`.  To build and install the sample
execute the following command:

### Method 1
    ./gradlew installDebug

### Method 2
    ./gradlew assembleDebug

To install

    cd app/build/outputs/apk
    adb install app-armeabi-debug.apk

George Nash's avatar
George Nash committed
148 149 150 151 152
The Android version of the onboarding tool can be found in
`<iotivity-lite>/swig/apps/oc/android_on_boarding_tool`

It is built and installed using the same instructions as other Android samples documented above.

George Nash's avatar
George Nash committed
153 154
See the Simple Step-by-Step guide for onboarding and provisioning section found in the root level
README for step-by-step instructions to onboard and test the samples.
Larry Sachs's avatar
Larry Sachs committed
155 156

Building Custom Android Applications
George Nash's avatar
George Nash committed
157
-------------------------------------------------
158 159 160
These libraries and examples were built with Android API 23.  When creating a new Android project a
different API level may be chosen.  When building these examples, the native code libraries were
copied to specific directories in the project.  The project structure is:
Larry Sachs's avatar
Larry Sachs committed
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

```
    project/
    ├──libs/
    |  └── iotivity-lite.jar
    ├──src/
       └── main/
           ├── AndroidManifest.xml
           ├── java/
           └── jniLibs/
               ├── armeabi/
               │   └── libiotivity-lite-jni.so.so
               └── x86-64/
                   └── libiotivity-lite-jni.so.so
```

This structure is reflected in the app `build.gradle` file:

```
    android {
        .
        .
        .
        sourceSets {
            main {
                jniLibs.srcDirs = ["src/main/jniLibs", "$buildDir/native-libs"]
            }
        }
        splits {
            abi {
                enable true
                reset()
                include 'x86_64', 'armeabi'
                universalApk false
            }
        }
    }
George Nash's avatar
George Nash committed
198

Larry Sachs's avatar
Larry Sachs committed
199 200 201 202 203 204 205 206
    dependencies {
        compile fileTree(dir: 'libs', include: ['*.jar'])
        .
        .
        .
    }
```

207 208
To allow these example applications to work, permissions had to be granted in the 
`AndroidManifest.xml` file.
Larry Sachs's avatar
Larry Sachs committed
209 210 211

```
    <manifest ...>
George Nash's avatar
George Nash committed
212

Larry Sachs's avatar
Larry Sachs committed
213 214 215 216 217 218
        <uses-permission android:name="android.permission.INTERNET"/>
        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
        <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
        <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE"/>
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
        <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
George Nash's avatar
George Nash committed
219

Larry Sachs's avatar
Larry Sachs committed
220 221 222 223 224
        <application
            .
            .
            .
        </application>
George Nash's avatar
George Nash committed
225

Larry Sachs's avatar
Larry Sachs committed
226 227 228 229
    </manifest>
```

Send Feedback
George Nash's avatar
George Nash committed
230
-------------------------------------------------
Larry Sachs's avatar
Larry Sachs committed
231
Questions
232
[IoTivity-Lite Developer Mailing List](https://iotivity.groups.io/g/iotivity-dev)
Larry Sachs's avatar
Larry Sachs committed
233 234

Bugs
235
[IoTivity-lite gitlab issues](https://gitlab.iotivity.org/iotivity/iotivity-lite/issues)