OS - Android

Android is a mobile OS commonly used on smartphones and tablet computers.

Tablets with a USB port and Android version 3.1 or greater can control Phidgets directly plugged in to them. Earlier Android versions (tested down to 2.1) can control Phidgets over a network using the WebService. We do not currently support Android devices acting as a Phidget WebService server, but if you are looking for a compact and cheaper-than-a-tablet way to host Phidgets over a network, take a look at our Single Board Computer.

Quick Downloads

Already a pro, and just need the downloads? Here they are.

Android does not need special drivers installed, though for developing code you will need the Android Java libraries when you start writing code:

• Phidget Android libraries
• Phidget Android examples
• Android Java page

Note that you will also need the libraries for the operating system your Phidget is directly connected to, if you don't have an Android 3.1+ tablet with USB:

Windows:

• 32-bit Windows Drivers Installer
• 64-bit Windows Drivers Installer
• Windows Driver and Library Files (Zipped)
• Or refer to the main Windows page

OS X:

• OS X Drivers Installer
• Or refer to the main OS X page

Linux and the SBC:

• Linux Libraries (Source Code)
• Or refer to the main Linux page
• Direct connections work automatically with our SBC, you can refer to its Getting Started page

Getting Started with Android

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found in its user guide.

Android code is developed on an external platform anyway (i.e. Windows, Mac OS, or Linux), and so getting your Phidget to work locally on that platform first will help you distinguish any issues from network ones later.

Near the end of the Windows, Mac OS, or Linux setup process, we direct you to choose a language. At that point, please remember to return here to this Android Java page.

Alternately, you can first try using mainstream Java to control the Phidget on your host computer and become familiar with it. On the mainstream Java page, we provide example code - including code that works on the Android development platform of Eclipse - to test your Phidget directly from your development computer.

For directly controlling a Phidget with your Android device (i.e. plugging a Phidget directly in to your tablet), you will need a USB host controller on your tablet. Some tablets have these; some do not. Just having a port that the USB cable can fit into does not necessarily indicate that the port can host a USB device. Alternatively, some tablets (like the Samsung Galaxy Tab, for example) have the large 30-pin connectors that can be changed into a USB host using Samsung's adaptor.

The best way is to locate within the specifications for your device whether the ports on your device can serve as a USB host. Another way to know is that you can host other devices (such as using a USB memory key) on your tablet.

Installing

The 'installation' of the Phidget Android libraries is simply linking and distributing the libraries with your code. As the most common platform to do this (on Windows, Mac, and Linux) is through Eclipse, we provide brief instructions on how to get and install Eclipse so you can more easily follow along with our already-linked examples later.

Eclipse (Android Java Development Platform)

Development for your Android OS Phidget application can occur on Linux, Mac OSX, or Windows.

To install Eclipse, you will need the following:

1. The JDK and Java on your development system
   • See the mainstream Java page for details on Java for Windows, Mac, and Linux
2. Eclipse (a Java Integrated Development Environment) on your development system
   • http://www.eclipse.org/downloads/ (for Windows or MacOS)
   • sudo apt-get install eclipse (for Linux)
   • For 64-bit Linux, you will need the ia32-libs package (the bridge to 32-bit software) as well for Android development, try:

     sudo apt-get install ia32-libs

Android SDK (and ADT Eclipse Plugin)

After installing Java and Eclipse, you can install the Android Software Developer's Toolkit (SDK) and the Android plugin for Eclipse (ADT).

1. Download and install the Android SDK package for your development system:
   • See the download instructions link at http://developer.android.com/sdk/
   • Google's instructions for installing are here: http://developer.android.com/sdk/installing.html
2. Download and install the ADT Eclipse Plugin for Android
   • Follow the instructions at http://developer.android.com/sdk/eclipse-adt.html

To check that the JDK, the Android SDK, and Eclipse have all been configured correctly, use the Google HelloAndroid example:

http://developer.android.com/resources/tutorials/hello-world.html

Once you have confirmed that the Android SDK has been correctly installed, you are ready to begin developing applications with Phidgets.

Android SDK and ADT on Linux

After downloading and unpacking the Android SDK package (the link is just above), run the Android SDK manager. If android-sdk-linux is the unpacked directory that was downloaded, try:

android-sdk-linux/tools/android

This will give you the option to download the Android versions you want to support. Running the SDK from within Eclipse (Window → Android SDK) will let you add those Android versions to Eclipse, for emulating them before downloading to an Android device and using with Phidgets.

Then, to add Android support to your compilation process in Eclipse, make sure adb is in your path (e.g. by adding it to /etc/environment).

Phidget Libraries

The libraries from the Phidget Android examples (not our mainstream Java examples, despite the same name) are the libraries for including with your Android code.

When you download and unzip the examples, each project (in addition to the source files, resources, and so on) contain three things:

1. A libs/ folder
2. A jar file containing the general Phidget java library (phidget21.jar)
3. A jar file for directly driving USB devices from a USB port on the Android device (PhidgetsUSB.jar)

Feel free to browse around within these jar files to get a sense of what will be going on the Android OS side. We describe how to link and use these library files later on the Write your own Android code section of the Android Java page. For now, having found them means you can copy and 'install' them to any project directory you want.

First, though, it will be useful to check to make sure Phidgets work with your Android system.

Checking

When you run a Phidgets Android example, you transfer and link the libraries and code all at the same time. This should 'just work' with our examples, but if problems arise this section gives more detail on pinpointing the source of the problem. We recommend starting with running the software examples right away - if the software works, you know the hardware works too.

Software

The easiest way to see whether your libraries are set up correctly within our examples or your own project is just to download them to the Android device and run them. Detailed instructions for this (including choosing the right HelloWorld project to run) are on the Language - Android Java page. That page will be your next step - but if the examples do not run using the instructions, return here to debug your hardware.

Hardware

If you are having problems running the examples, you should check the hardware of the host computer if your Android device is controlling the Phidget over the WebService. Or, you should check the hardware of your Android device if the Phidget is directly connected to the tablet's USB port.

Remote Phidget

When using the WebService to control a Phidget, the problem may be with the USB connection on the remote computer. Make sure both the server-side of (a) the webservice and (b) the USB connection are working by using the instructions on the page specific to the operating system

Directly Connected Phidget

To check whether a Phidget is correctly connecting in your Android hardware (even if our examples do not work), you can use the kernel logs on your Android tablet in a similar way as you would on Linux.

You need to access the logs from your debugging computer - e.g. the computer where you have installed Google's development plugins as described above. Plug a USB Phidget into your Android device. Then, as soon as possible, from a command line on that computer, use the ADB (Android Debugging Bridge) program to access the program dmesg on your Android device:

adb shell dmesg

This will print out the entirety of the kernel logs on your Android device. Even if you have been running your device for only a little while, this could be thousands of lines of output. If you plugged the Phidget in and then ran dmesg right away, the kernel detection of the Phidget should be almost at the bottom of the logs. If you are on Linux or Mac OS, you can mitigate the length of this output using tail -n 50 or so. If you are on Windows, you may consider using a command redirection operator like > to write to a file and then view the last 50 or so lines.

Near the end of the output you will find something like this for a successful registration of a Phidget in the Android kernel:

<6>[ 3282.554249] usb 1-1.2: new full speed USB device using tegra-ehci and address 5
<6>[ 3282.612359] usb 1-1.2: New USB device found, idVendor=06c2, idProduct=0032
<6>[ 3282.612418] usb 1-1.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
<6>[ 3282.612466] usb 1-1.2: Product: PhidgetTemperatureSensor
<6>[ 3282.612504] usb 1-1.2: Manufacturer: Phidgets Inc.
<6>[ 3282.612540] usb 1-1.2: SerialNumber: 287638
<4>[ 3282.612576] device: '1-1.2': device_add
<4>[ 3282.615639] device: '1-1.2:1.0': device_add
<4>[ 3282.618632] device: '0003:06C2:0032.0003': device_add
<3>[ 3282.631412] generic-usb 0003:06C2:0032.0003: claimed by neither input, hiddev nor hidraw

If the kernel log Phidget attachment does not appear, make sure that other devices that are supposed to work with your tablet (USB data keys, keyboards, etc. - the list depending entirely on which tablet) do indeed work. Not having the Phidget appear in your kernel logs indicates there is a problem with your USB hardware on your Android device.

Note that in order to consider a port on your tablet to be compatible with Phidgets it must be able to host USB devices. Simply finding and using a USB cable to connect the Phidget to the power charging port on your phone or tablet is not enough! A host USB port should either say so explicitly, or at least act like a 'normal' USB port such as ones you would find on your PC, and be able to use many common USB devices like memory sticks.

If the kernel log attachment does appear, but your code doesn't run, the problem is probably with your code. Work through the Language - Android Java page to make sure you have all the libraries, jar files, and permissions set and linked properly to use your Phidget.

Troubleshooting

If the examples do not work but USB does work (i.e. your remote computer or Android device can consistently see the device in the hardware), take a moment to check the basics:

• No other programs, drivers, or processes are using that USB port in software
• You have properly set either android.permission.INTERNET or android.hardware.usb.host in your AndroidManifest.xml file (as described on the Language - Android Java page)
• You have copied and linked the Phidget jar libraries and libs/ folder into your project (as described on the Language - Android Java page)
• The Phidget libraries are the latest version (visit the quick downloads section to download them)
• If using the Phidget over the webservice, make sure the webservice drivers and the Android libraries are both the latest version
• If directly connecting to your Android device, the port you are using is a real USB host port (not a reduced-function power charging port)
• Check the common problems section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen consistently by USB in hardware (if it is erratic, try our general troubleshooting guide). If you are still having problems after using the troubleshooting guide, please ask us!

Programming Languages

Android OS programs are written in Android Java using the Android SDK and the Phidgets library. You can read on within this page to learn how to use Android with the WebService, or you can jump ahead right now to the Android Java page and start writing code!

Note that Android Java is NOT the same as mainstream Java. Any Java programs you have will probably need significant modification before they run on Android, including our mainstream Java Phidget Examples.

WebService

The Phidget WebService allows you to remotely control a Phidget over a network.
This section helps you use the WebService on Android, but we also have an overview of the Phidget WebService in general.

Currently, Android devices cannot host the WebService, but they can use data streaming from another computer over the WebService.

Setting Up the WebService

Using an Android device, your network-controlled Phidget system will probably look something like this:

1. Start the WebService on the host computer

• How to do this on Windows
• How to do this on Mac OS
• How to do this On Linux
• How to do this On the Phidget Single Board Computer

2. Download the Android Examples.

• Edit the IP address and port in the HelloWorldRemote example to match the IP address of the host computer (5001 is the default port)
• Transfer the example HelloWorldRemote to your Android Device
• Run the example on your Android device, making sure it is also connected to the local network
  • In Eclipse, right-click on project in Package Explorer (To open the Package Explorer, use Window → Show View → Package Explorer)
  • Select Run As... → Android Application

3. Plug a Phidget into the host computer

Using the WebService

After performing the steps above, you will be using the WebService already. Plugging in the Phidget to the host computer will probably give you a screen like this:

(The Phidget you actually plugged in will show up, be it a TemperatureSensor or something else)

And when you unplug that Phidget from the remote host computer, you should see something like this on your Android device:

Debugging the WebService

As currently an Android device can only be a user and not a host of the WebService, you should use debugging server side. Refer to the webservice sections for each operating system:

• Windows
• Mac OS
• Linux
• Phidget Single Board Computer

In addition, if you are having webservice problems, you will probably find the webservice section of our General Troubleshooting Guide helpful as well.

Advanced Uses

None yet, feel free to suggest some!

Common Problems and Solutions

Issue: Ad-Hoc Networking doesn't work

Unfortunately Ad-Hoc networking is not currently supported by Android devices. This might change in the future but there is no work-around for the problem at this point in time (current as of 2014-3-11).