IOIOLib Basics

IOIOLib Basics

Overview

IOIOLib is a collection of libraries, for Android and for the PC, which enable your application to control the IOIO board. The libraries expose a set of Java interfaces, covering the various features of the board. When you build your application, IOIOLib gets packaged into your target .jar or .apk file, so that your application is self-contained and does not require any further installation of dependent components. Now it is time to explain which libraries exist and what is the purpose of each one.

The IOIOLibPC library (whose Eclipse project files are under IOIOLib/target/pc) is the library you would use to interface IOIO from a PC. The IOIOLibAndroid library (whose Eclipse project files are under IOIOLib/target/android) is the library you would use to interface IOIO from an Android device. Two additional libraries, IOIOLibBT and IOIOLibAccessory are complementary to IOIOLibAndroid and add Bluetooth and Android Open Accessory functionality as possible connections to the IOIO, respectively. The reason why they are separate is that the IOIOLibAndroid library would work on any version of Android (as early as V1.5), while Bluetooth has been introduced in Android V2.x and Open Accessory is only available on select Android 2.3.4 or later devices. If you simply link any of those libraries (or both) to your application, your IOIO connection will automatically be established over whichever available channel, provided that your application is based on the Android utility classes (more on that later).

If you are not familiar with Android application development and/or have not yet setup your development environment, the IOIO Beginner's Guide page may provide useful information.
A good set of Java tutorials is available here.

The entire IOIOLib public API has standard Javadoc documentation, which is intended to be comprehensive and be used as reference while coding. In this User Guide, we try to cover usage of the library from a common-use-cases approach rather than be 100% formal.

Obtaining and Using IOIOLib

The latest version IOIOLib can be downloaded from the Downloads page. It is a part of the "Software" zip. This zip also includes some sample applications.

We're only going to cover usage with Eclipse here, with the assumption that users not using Eclipse for Android application development probably know what they're doing anyway :)

• Extract IOIOLib to somewhere where you normally want to keep your projects.
• Import the appropriate libraries into your Eclipse workspace, using File > Import... > General > Existing Projects into Workspace..., then choose the IOIOLib directory you just created. Two possible projects to import will appear.
  • If you are going to be developing an Android application:
    • Check IOIOLibAndroid and click "Finish".
    • Reference IOIOLibAndroid from your application project, according to these instructions.
    • If you want Bluetooth and/or Android Open Accessory connectivity, repeat the process for the IOIOLibBT and IOIOLibAccessory libraries.
    • Make sure your application declares using the android.permission.INTERNET permission. This can set by opening the AndroidManifest.xml file found at your project's root, going to the Permissions tab > Add... > Uses Permission > Select android.permission.INTERNET under "Name".
    • Make sure you enabled USB debugging on your Android device, by going to Settings > Applications > Development > Enable USB Debugging.
  • If you are going to be developing a PC application:
    • Check IOIOLibPC and click "Finish".
    • Reference IOIOLibPC from your application project, by editing your application's Java Build settings.

Writing Applications

IOIOLib includes two main parts:

• The IOIOLib Core API, which comprises a platform-independent API for controlling all the IOIO functions. Read more here.
• The IOIOLib Application Framework, which comprises platform- and application-type-specific utilities to simplify the creation of various common kinds of applications. It is not strictly necessary to use the application framework for working with the IOIO, but it is highly recommended, since it hides away many of the delicate bootstraping and threading issues required for a reliable and robust IOIO-based application. Read more here.

The libraries are organized in several Java packages. The ioio.lib.api package contains all the core API for controlling the IOIO. This is the package your application will be using. It is identical between the Android libraries and the PC libraries, so that your app can be easy to port from PC to Android or vice-versa and there is no need to learn two different interfaces. The sub-package, the ioio.lib.api.exception package contains some exceptions thrown by the IOIO API. The ioio.lib.impl package contains the implementation of these interfaces and is not intended to be used directly. The ioio.lib.util package contains useful utilities that may make your life a little easier when writing IOIO applications, but do not provide core functionality. Under this package, platform-specific packages are contained, in the respective libraries. ioio.lib.util.android contains utilities specific to Android, which simply the process of creating Android applications using the IOIO, and likewise, ioio.lib.util.pc contains utilities which help creating various kinds of Java applications for the PC.