Building IOIO Applications With Gradle
Note: The information in this page is relevant only for IOIO software release 5.05 or later. Earlier versions relied on a completely different set of build tools.
Starting at release 5.05 of the IOIO software, the recommended way to build IOIO applications is using the Gradle build system. To those not familiar with Gradle, it is a flexible build tool that is becoming very popular among Java developers and has been adopted by the Android SDK as the official way to build Android applications. Using Gradle, software can easily be built, tested and published via a simple command-line interface, but Gradle is also tightly integrated into various IDEs, making the IDE understand the structure of the project, simplify editing of build scripts and execute different build tasks from a GUI. The official IDE of choice for Android development is Android Studio, which, despite its name, is a general purpose Java IDE, based on the popular IntelliJ IDEA. Starting at release 5.05 of the IOIO software, this is the official IDE for developing IOIO based applications for either Android or PC. Users preferring to use Eclipse for PC applications can still do so, using the Gradle plugin for Eclipse, but this mode is not officially supported and thus not recommended.
Moreover, along with this change the IOIO libraries are no longer needed to be built by users, but rather made available on Maven Central. Maven Central is a universal repository of canonically named and versioned software packages including meta information such as their source code, documentation and dependencies on other packages. Maven Central is supported by many build tools and IDEs, typically requiring a user of those components to merely state the name ("coordinates") and version of the component they want to use, thus greatly reducing the complexity of distributing and using those components. Specifically, using Maven packages is seamlessly integrated into the Gradle build system mentioned above.
A typical Android application source tree will have a structure similar to the following:
HelloIOIO
├── build.gradle
└── src
└── main
├── AndroidManifest.xml
├── java
│ └── ioio
│ └── examples
│ └── hello
│ └── MainActivity.java
└── res
├── drawable
│ └── icon.png
├── layout
│ └── main.xml
└── values
└── strings.xml
You can find detailed information about building Android applications on the Android Developer website. In order to enable this application to use the IOIO functionality, the gradle.build file needs to reference the relevant IOIO libraries from the Maven Central repository:
// This part is also the regular Android application boilerplate.
apply plugin: 'com.android.application'
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:1.3.0'
}
}
android {
buildToolsVersion "22.0.1"
compileSdkVersion 19
}
// And this it what makes it IOIO-enabled.
dependencies {
compile 'com.github.ytai.ioio:IOIOLibAndroid:5.05'
compile 'com.github.ytai.ioio:IOIOLibAndroidBluetooth:5.05'
compile 'com.github.ytai.ioio:IOIOLibAndroidAccessory:5.05'
compile 'com.github.ytai.ioio:IOIOLibAndroidDevice:5.05'
}
repositories {
mavenCentral()
}While the IOIOLibAndroid dependency is required, the other three are optional and add different ways to communicate between the Android and the IOIO. Typically, there is no reason not to include all of them.
The AndroidManifest.xml should be similar to the following:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
android:versionCode="1" android:versionName="1.0" package="ioio.examples.hello">
<uses-sdk android:targetSdkVersion="10" android:minSdkVersion="3" />
<application android:icon="@drawable/icon" android:label="@string/app_name">
<uses-library android:name="com.android.future.usb.accessory"
android:required="false" />
<activity android:label="@string/app_name" android:name="MainActivity"
android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" />
</intent-filter>
<intent-filter>
<action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
</intent-filter>
<meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"
android:resource="@xml/accessory_filter" />
<meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
android:resource="@xml/device_filter" />
</activity>
</application>
</manifest>The intent-filter and meta-data tags ensure that your activity gets registered as one that is automatically opened when connecting the IOIO as a USB accessory or device, the uses-library tag ensures compatibility with older Android devices that have legacy OpenAccessory support, and the singleTask launch mode ensures that there is only ever one instance of your activity running, to avoid contention on using the IOIO.
A typical PC Java application source tree will have a structure similar to the following:
HelloIOIOConsole/
├── build.gradle
└── src
└── main
└── java
└── ioio
└── examples
└── hello_console
└── HelloIOIOConsole.java
This build.gradle file illustrates how we would package the entire application into a single executable JAR file, as well as add IOIO support by depending on the relevant Maven packages:
apply plugin: 'gradle-one-jar'
task distJar(type: OneJar) {
mainClass = 'ioio.examples.hello_console.HelloIOIOConsole'
}
tasks.build.dependsOn distJar
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.github.rholder:gradle-one-jar:1.0.4'
}
}
// From here on is the stuff required for IOIO support.
dependencies {
compile 'com.github.ytai.ioio:IOIOLibPC:5.05'
}
repositories {
mavenCentral()
maven { url "http://www.sparetimelabs.com/maven2" }
}Note that using the gradle-one-jar plugin is not a requirement for using the IOIO with your app. It is just a recommended practice for cases where a single, self-contained executable JAR is to be produced. Do not forget to add the second Maven repository. Otherwise the build might fail, complaining about not being able to find one of the packages ("PureJavaComm") that the IOIO library depends on.
Building either your Android application or your PC application with Gradle from the command line is as easy as typing:
gradle build
from the directory that contains the gradle.build file. The resuling .apk file (Android) or .jar (PC) will be found under build/outputs/apk/... or build/libs/..., respectively. The first time building, you'd need an Internet connection, so that Gradle can fetch the libraries from Maven. After the first build, they will remain cached locally and builds can happen offline.
For advanced users preferring a fully-offline build, the archives are distributed under the lib directory of the software bundle, but the dependencies for PC (PureJavaComm, JNA) need to be fetched from their respective owners.
Once you have extracted the software bundle, you can easily import the example projects, either Android or PC into Android Studio, by following the following steps.
Import a project into Android Studio either from the Welcome screen pictured below or from the menu File > New > Import Project...
Then, browse to the application directory and select the build.gradle file in it:
You might see this screen, dismiss it:
If everything went OK, your project should appear similar to this:
