Step by step, this tutorial will help you install and configure the software needed to start
developing IOIO applications for Android!
While there is already a Beginner's guide on github's IOIO page, the information is quite scattered. The aim of this is to regroup all the needed information into a simple and convenient tutorial, to quickly get you developing your first IOIO for Android application!
Note: This tutorial involves a lot of downloads and installations, so make sure you have some time ahead of you!
STEP 1: System Requirements
Supported Operating Systems
- Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit)
- Mac OS X 10.5.8 or later (x86 only)
- Linux (tested on Ubuntu Linux, Lucid Lynx)
- GNU C Library (glibc) 2.7 or later is required.
- On Ubuntu Linux, version 8.04 or later is required.
- 64-bit distributions must be capable of running 32-bit applications.
For information about how to add support for 32-bit applications,
see the Ubuntu Linux installation notes.
STEP 2: Installing Java Development Kit (JDK)
Get the latest Java SE version on the Java SE download page
Click on the JDK, accept the license agreement, and download the right Java
Development Kit version for your Operating System.
Note: if using a 64 bit OS, you must download the 64 bit version.
Follow the installation wizard's steps and install all of the components.
You don't have to register.
STEP 3: Installing Eclipse IDE
Go to the Eclipse Download Page
While any of those 3 is recommended to develop Android Applications, just take the Classic version if you're a IOIO beginner.
- Eclipse IDE for Java Developers
- Eclipse Classic
- Eclipse IDE for Java EE Developers
Download Eclipse for your OS.
Eclipse Classic is a standalone program, you don't have to install it. Just put the Eclipse folder wherever you want on your computer, and the "Eclipse" executable is the application.
STEP 4: Installing the Android SDK
Go to the SDK download page and download the installer for your OS.
Run the installer and follow the steps.
Troubleshoot: If the installer cannot find your Java SDK and you have the
JAVA_HOME variable error, follow these steps.
When the installation finishes, the installer will ask you to run the SDK manager.
Don't, we will go through this step later.
STEP 5: Run Eclipse IDE
This is the easiest step!
Run the "eclipse" application and create a shortcut if you want. Upon first launch, Eclipse will ask you to create a workspace. Think about it is as your "My Documents for Eclipse", this is where your projects will be. Set this folder as you please. This can be changed later.
STEP 6: Install the Android Development Tools (ADT) Plugin
- Start Eclipse, then select Help > Install New Software....
- In the "Work With:" area, click Add, in the top-right corner.
- In the Add Repository dialog that appears, enter "ADT Plugin"
- for the Name and the following URL for the Location:
Note: If you have trouble acquiring the plugin, try using "http" in the Location URL,
instead of "https" (https is preferred for security reasons).
- In the Available Software dialog, select the checkbox next to Developer Tools, and click Next.
- In the next window, you'll see a list of the tools to be downloaded. Click Next.
- Read and accept the license agreements, then click Finish.
Note: If you get a security warning, saying that the authenticity or validity of the software can't be established, click OK.
When the installation completes, restart Eclipse.
Note: If you get the following error: "ADT requires 'org.eclipse.wst.sse.core 0.0.0' but it could not be found". For Eclipse 4.2 (Juno), you need to use this url first:
For other versions, replace "juno" with your version, (indigo, helios....) and under the category, " Web,XML, and Java EE development", download "WST Server Adapters".
Now you have to point the SDK to the Eclipse Plugin.
- Select Window > Preferences to open the Preferences panel.
(Mac OS X: Eclipse > Preferences).
- Select Android from the left panel.
- For the SDK Location in the main panel, click Browse...
- Locate your downloaded SDK directory.
- Click Apply, then OK.
If you're having problems, look at the troubleshooting section from the source mentioned at the beginning of this step.
STEP 7: Install Android packages
In Eclipse, do Window > Android SDK Manager.
The IOIO libraries need older API versions, so you should install them too. You will also be
able to make your application compatible with older Android versions.
Install the Google USB Driver too.
This procedure will download and install the selected components. There are a few GB, so make sure you have time in front of you.
STEP 8: Create an Android emulator
- In Eclipse, select Window > AVD Manager.
- Select Virtual Devices in the left panel.
- Click New....
- The Create New AVD dialog appears.
- Type the name of the AVD, such as "my_avd".
- Choose a target.
The target is the platform (that is, the version of the Android SDK, such as 2.3.3)
you want to run on the emulator.
- For this tutorial, choose the latest platform that you have installed
- Ignore the rest of the fields.
- Click Create AVD.
STEP 9: Compile your first IOIO project!
Import the IOIO libraries and examples
Go to the Android Software and IOIO Application Firmware Images download page, and download the latest version.
Unzip the files to a safe location. Time to import the libraries and the IOIO example project!
In Eclipse, do File > Import, and in General, select Existing Projects Into Workspace.
In "Select Root Directory" browse, and point to the IOIOLib folder you just unzipped.
Make sure the box is ticked in the "Projects" area, and that Copy projects into
workspace is also ticked, and click on Finish
Repeat this step for IOIOLibBT and IOIOLibAccessory.
IOIOLib has to be included in every IOIO project as this is the core library.
IOIOLibBT adds Bluetooth support.
Now that you have the libraries, import the Example project!
Repeat the previous steps with the HelloIOIO folder located in the Applications folder.
Link the IOIO libraries to the project
In the Package Explorer on the left, right click on HelloIOIO and select Properties In the Android menu, click on Add at the bottom, and add IOIOLib, IOIOLibBT, and IOIOLibAccessory. Remove the error lines if needed
You should now have that:
Configure the JAVA compiler
Android applications require the JAVA 1.6 compiler.
Right now you should have this error:
Android requires compiler compliance level 5.0 or 6.0. Found '1.7' instead. Please use
Android Tools > Fix Project Properties If you closed the project properties, open it again.
This time, in the Java Compiler menu, enable project specific settings, and select
the Compiler compliance level: 1.6
Repeat this step for every library and included project.
Now you may have this error:
The project cannot be built until build path errors are resolved.
Relaunch Eclipse, then press F5 (or File > Refresh), and you should have something that looks like that! I opened 2 files, one in src, MainActivity.java, this is where all your application code is located, the second one in res, main.xml is your application layout, that is to say what your application will look like on an Android device!
Give internet permissions to your app
In the package explorer, for the HelloIOIO project, open the AndroidManifest.xml file.
You will be in the "Manifest" tab. Open the "Permissions" tab (at the bottom), and make sure there are android.permission.INTERNET and android.permission.BLUETOOTH
If not, click on "add", "Uses permission" and search for android.permission.
INTERNET in the "Name" field. Repeat for android.permission.BLUETOOTH
STEP 10: Run the app!
The configuration was complicated and long, but that's it! You're a few minutes away from running your first IOIO application!
You can run it with the configured Android emulator.
Just click on Run > Run and the emulator will load (it can take several minutes). But the emulator doesn't have any IOIO functionality,
So take your Android phone, set it in USB debugging mode:
Settings ==> Applications ==> Development ==> USB debugging
And plug it into your computer! The Google USB Driver you installed before with the ADT plugin will take care of the rest.
Click on Run > Run and the application should be transferred and started on the phone.
When you click Run, a stand-alone application is also created in your workspace.
It is located in the bin folder (HelloIOIO.apk). You can also transfer it to your phone and install it from there.
Be careful about how you power the IOIO.
- Power the IOIO either from 5V-15V input on the VIN line or from 5V directly on the 5V line.
- Avoid accidental contact between the power lines and other pins / conductors.
- Not all of the IOIO pins are 5V tolerant. Some of them can only tolerate up to 3.3V.
- You should input 5V to the IOIO only on those pins marked with a circle on the back of the board.
Now plug your phone to the IOIO and start playing around! You just entered a world full of amazing possibilites!!