Running Examples in Accessory Mode

The examples for the Mega ADK using the board in accessory mode require the following hardware and software:

• a Nexus S, a Nexus One, a Samsung Galaxy Tab 10.1 or any other device supporting accessory mode (refer to the Getting Started page for more information)
• Android SDK with all the updates up to the latest version of the APIs
• Processing 2.0a4 [TODO: Update when compatible]
• Arduino 1.0 or newer
• the UsbHost library for Arduino (includes the AndroidAccessory class)
• the Arduino ADK Tool for Processing
• Eclipse + ADT plugin (optional and not explained here)

1. Download required libraries/tools for Arduino and Processing

The libraries and tools required for Arduino and Processing can be downloaded in the file ArduinoADK.zip

Uncompress the file and inside the resulting folder ArduinoADK [TODO: Actually ArduinoADK-beta-001 currently] you will find two additional folders:

• Arduino
• Processing

The instructions below will tell you what to do with their content.

2. Install Android SDK

You can get the Android SDK from the Android Development website:

http://developer.android.com/sdk/installing.html

Unless you are planning on using Eclipse as part of your development, you can skip their step 3 of the installation.

Step 4 can be time consuming, you need to include the APIs for Google versions 10 and higher; consider installing everything at once.

This screenshot shows the minimum options you need selected for Android 2.3.4 and 4.0.3 support:

When you start the install you should see a confirmation screen similar to this:

[NOTE: Google seems to have broken the ability to download the needed Google APIs using Java 5 (a.k.a 1.5) —if you don’t see the Google APIs in the available packages list that’s probably why.

To work around this you may need to force the android application to run with Java 6 (a.k.a 1.6). For Mac OS X you can use the Java Preferences application to ensure the correct version of Java is used.

When you start the Java Preferences application it will look something like this (make a note of the exact settings for your computer):

Quit the android application and then temporarily change the Java preferences to deselect all variations of Java 5/1.5:

Then run the android application again to download the SDK.

When you have installed the SDK you should change the Java Preferences settings back to how they were when you started—if you do not change the settings back the Arduino and Processing IDEs or other Java applications may not run correctly.

The bug report for this issue.

TODO: Remove this note when the issue is fixed.]

3. Install Processing + Processing Libraries

Processing can normally be obtained from the following link:

• http://processing.org/download/

But we need to use a particular pre-release version of Processing 2.0 which can be downloaded from [TODO: Update when later version is compatible]:

• Processing 2.0a4

Download the appropriate version for your OS and run the application. The first time Processing is run it will create your sketchbook. This is the way Processing defines your workspace and where it will be storing all your work by default.

We now need to add a library and a tool to the standard installation.

First, exit Processing so that it will find the new libraries and tools when you next run it.

Look inside the folder Processing (not the Arduino folder) you uncompressed earlier (inside the ArduinoADK folder) and you will find two further folders:

• libraries
• tools

If your Processing sketchbook folder is empty you can copy the libraries and tools folders into your sketchbook folder.

If you already have a libraries or tools folder in your sketchbook you will need to copy the content of the libraries and tools folders into their respective folders in your sketchbook.

The next time you start Processing the tool and library will be ready to use.

Toward the upper right corner of the sketch editor window you will see a small button stating the work mode for Processing. By default you will be working in Standard mode. Click on the button to change to Android mode. That should also change the color of your application from grey to green.

At this stage Processing will ask you to select the location of the Android SDK which you downloaded earlier.

You can now use the editor to write code for your phone. In order to launch your ADK compatible code, you should look for the Arduino ADK option from the Tools menu.

4. Install Arduino 1.0 + Arduino Libraries

Download the Arduino IDE from the following link. You might have this software already installed in your computer:

• Arduino downloads for Windows, Mac OS X and Linux

As with Processing, you need to run the Arduino IDE once to create your sketchbook folder. Make sure you exit the IDE before performing the next step to install the library.

Once the Arduino sketchbook folder is created, copy the libraries folder (not the experimental libraries-v2 folder) from the Arduino folder you uncompressed earlier (the one inside the ArduinoADK folder) into the Arduino sketchbook folder. If you have an existing libraries folder in your Arduino sketchbook folder then copy the UsbHost library (from inside the ArduinoADK/Arduino/libraries folder) into it instead.

You can now upload the provided example accessory sketches and write sketches to create your own accessories.

Examples

The libraries you installed both in Processing and Arduino come with Examples for you to try out the technology.

You can browse the example sketches by going to the menu File > Examples > UsbHost in the Arduino IDE and File > Examples… > Contributed Libraries > ArduinoAdkUsb in the Processing IDE.

Workflow

These tools require a particular process. You are writing code for two different pieces of hardware:

• your phone/tablet, acting as USB client
• your Mega ADK board, acting as USB host
• since the Android device will be working in Accessory mode, the Arduino ADK board will be powering the device. Theoretically you should not worry about batteries as long as the Arduino ADK has power

A good way of working could be to:

1. write you Arduino sketch first
2. make sure you are getting the data you want by debugging the code using the serial monitor
3. write a basic Android App that reads the data or sends commands to the Mega ADK
4. design your Android App UI as needed

Known Issues

As of 7 June 2012 there are some known issues:

• Example apps may force close if the correct onStop() function is not provided in the sketch.
• Example apps may not correctly release the USB device on exit. This will result in subsequent attempts to connect a device not being recognised. You will need to force close the app or stop the app if it is listed under “cached applications”.
• Some versions of Android 3.x don’t work with the ADK apps generated by Processing due to not supporting the future USB class hierarchy.
• If an accessory that has worked before isn’t recognised when connected try the following steps:
  • Unplug the Arduino board from the Android device and power.
  • Force close/stop any apps on the Android device that use accessories.
  • Restore the power to the Arduino.
  • Plug the Arduino into the Android device.
  • The device should now be recognised.