|
|
| (10 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| | <metadesc>Communicate over USB with sensors, controllers and relays with Phidgets! Program in Android using Android Java.</metadesc> |
| [[Category:OS]] | | [[Category:OS]] |
| {{OSLang|[[File:Icon-Android.png|64x64px|left|link=]]|Android is a mobile OS commonly used on smartphones and tablet computers.}} | | {| |
| __TOC__
| | |style="vertical-align:middle; width: 60%;"| |
| | |
| 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 [[#Network Service|Network Service]]. We do not currently support Android devices acting as a [[Phidget Network Service]] 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 [{{SERVER}}/products.php?product_id=1073 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:
| |
| * [{{SERVER}}/downloads/libraries/phidget21-android.tar.gz Phidget Android libraries]
| |
| * [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Android examples]
| |
| * [[Language - Android Java#Quick Downloads|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:'''
| |
| {{WindowsQuickDownloads}}
| |
| * Or refer to the main [[OS - Windows|Windows page]]
| |
| | |
| '''OS X:'''
| |
| {{MacQuickDownloads}}
| |
| * Or refer to the main [[OS - OS X|OS X page]]
| |
| | |
| '''Linux and the SBC:'''
| |
| {{LinuxQuickDownloads}}
| |
| * Or refer to the main [[OS - Linux|Linux page]]
| |
| * Direct connections work automatically with our [{{SERVER}}/products.php?product_id=1073 SBC], you can refer to its [[1073 User Guide#Getting Started|Getting Started]] page
| |
| | |
| ==Getting Started with Android== | | ==Getting Started with Android== |
| | Welcome to using Phidgets 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 [[:Category:UserGuide|user guide]]. | | 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 [[:Category:UserGuide|user guide]]. If you are ready to go, the first step to creating an Android application with Phidgets is downloading the Phidget libraries on your development machine! |
| | | |{{TOC limit|2}} |
| 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.
| | |} |
| | | ==Download== |
| 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.
| | The Phidget libraries for Android development are available here: |
| | | *[https://cdn.phidgets.com/downloads/phidget22/libraries/android/phidget22-android.zip Android Java Libraries] |
| Alternately, you can first try using [[Language - Java|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:
| |
| | |
| # The JDK and Java on your development system
| |
| #*See the [[Language - Java|mainstream Java]] page for details on Java for Windows, Mac, and Linux
| |
| # Eclipse (a Java Integrated Development Environment) on your development system
| |
| #*[http://www.eclipse.org/downloads/ http://www.eclipse.org/downloads/] (for Windows or MacOS)
| |
| #*<code>sudo apt-get install eclipse</code> (for Linux)
| |
| #*For 64-bit Linux, you will need the <code>ia32-libs</code> package (the bridge to 32-bit software) as well for Android development, try:
| |
| #*:{{Code|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).
| |
| | |
| # Download and install the Android SDK package for your development system:
| |
| #*See the download instructions link at [http://developer.android.com/sdk/ http://developer.android.com/sdk/]
| |
| #*Google's instructions for installing are here: [http://developer.android.com/sdk/installing.html http://developer.android.com/sdk/installing.html]
| |
| # Download and install the ADT Eclipse Plugin for Android
| |
| #*Follow the instructions at [http://developer.android.com/sdk/eclipse-adt.html 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 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 [[#Android SDK (and ADT Eclipse Plugin)|just above]]), run the Android SDK manager. If {{Code|android-sdk-linux}} is the unpacked directory that was downloaded, try:
| |
| :{{Code|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 ({{Code|Window}} → {{Code|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 {{Code|adb}} is in your path (e.g. by adding it to {{Code|/etc/environment}}).
| |
| | |
| ====Phidget Libraries====
| |
| | |
| The libraries from the [{{SERVER}}/downloads/examples/android-examples.tar.gz 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:
| |
| | |
| # A libs/ folder
| |
| # A jar file containing the general Phidget java library (phidget21.jar)
| |
| # 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 [[Language - Android Java#Write Your Own Code | 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.
| | Download and unpack the libraries. You will need to reference these files from your project in order to use Phidgets. This step is covered in detail in the [[Language - Android Java | Android Java page]]. If you need to access older versions of the libraries, [https://www.phidgets.com/downloads/phidget22/libraries/android/ click here]. |
|
| |
|
| First, though, it will be useful to check to make sure Phidgets work with your Android system.
| | ==Direct USB Connection== |
| | For directly controlling a Phidget with your Android device (i.e. plugging a Phidget directly into your device), you will need to ensure the device is capable of being a USB host. Just having a port that the USB cable can fit into does not necessarily indicate that the port can host a USB device. On the other hand, some phones can use an OTG (on-the-go) cable to allow plugging USB devices into their charging port. Some tablets (like the Samsung Galaxy Tab, for example) have the large 30-pin connectors that can be changed into a USB host using an adapter. |
|
| |
|
| ===Checking===
| | The best way to know before getting your hands on a device is to check its specifications for whether it can serve as a USB host. Alternately, a quick way to figure out if your device can serve as a USB host is to try plugging other devices (such as a mouse, or USB memory stick) into your Android device. |
|
| |
|
| 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.
| | ==Network Server== |
| | In applications where you aren't plugging Phidgets into your Android device directly, you must have a host computer that is running the Phidget Network Server. |
|
| |
|
| ====Software==== | | [[Image:android-connection.jpg|link=|center]] |
|
| |
|
| 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 {{Code|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.
| | *Host computer: the computer that is physically connected to the Phidgets via USB and is running the Phidget Network Server. |
| | *Client computer: a computer running a Phidgets application that accesses Phidgets connected to the host computer. When developing for Android, your Android device acts as the client. |
|
| |
|
| ====Hardware====
| |
|
| |
|
| If you are having problems running the examples, you should check the [[#Remote Phidget|hardware of the host computer]] if your Android device is controlling the Phidget over the Network Service. Or, you should check the hardware of your [[#Directly Connected Phidget|Android device]] if the Phidget is directly connected to the tablet's USB port.
| | In this case, you will need to install the Phidget libraries on your host computer, and get the Phidget Network Server up and running. Follow the ''Getting Started'' guide, and continue with the ''Network Server'' guide for your operating system. When you are done, come back and finish this guide! |
| | | *[[OS - Windows| Windows]] |
| =====Remote Phidget=====
| | *[[OS - macOS| macOS]] |
| | | *[[OS - Linux| Linux]] |
| When using the [[#Network Service|Network Service]] 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 network service and (b) the USB connection are working by using the instructions on the [[Software Overview#Operating System Support|page specific to the operating system]]
| | *[[OS - Phidget SBC| Phidget Single Board Computer]] |
| | |
| =====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 [[OS - Linux|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 {{Code|dmesg}} on your Android device:
| |
| | |
| <div class="source">
| |
| <syntaxhighlight lang=bash>
| |
| adb shell dmesg
| |
| </syntaxhighlight>
| |
| </div>
| |
| | |
| 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 {{Code|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 {{Code|tail -n 50}} or so. If you are on Windows, you may consider using a command redirection operator like {{Code|>}} 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:
| |
| | |
| <div class="source">
| |
| <syntaxhighlight lang=text>
| |
| <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
| |
| </syntaxhighlight>
| |
| </div>
| |
| | |
| 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|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| quick downloads section]] to download them) | |
| * If using the Phidget over the network service, make sure the network service 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 and Solutions|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|hardware]] (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please {{ContactUs|ask us}}!
| |
|
| |
|
| ==Programming Languages== | | ==Programming Languages== |
|
| |
|
| Android OS programs are written in [[Language - Android Java|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 Network Service, or you can jump ahead right now to the [[Language - Android Java|Android Java]] page and start writing code!
| | Now that you have the basics set up, check out the [[Language - Android Java|Android Java]] page for information on how to write code for Phidgets to run on your Android device. |
|
| |
|
| 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 [[Language - Java|mainstream Java]] Phidget Examples. | | 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 [[Language - Java|mainstream Java]] Phidget Examples. |
|
| |
|
| ==Network Service== | | ==Software License== |
| | | By downloading the Android library you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Phidgets_EULA.pdf Phidgets End User License Agreement]. The C API section of Phidget22 is covered by the [https://opensource.org/licenses/BSD-3-Clause The 3-Clause BSD License]. The source code of C API can be found [{{SERVER}}/downloads/phidget22/libraries/linux/libphidget22.tar.gz here]. |
| The Phidget Network Service allows you to remotely control a Phidget over a network.<br>This section helps you use the Network Service on Android, but we also have an overview of the [[Phidget Network Service]] in general.
| |
| | |
| Currently, Android devices cannot ''host'' the Network Service, but they can use data streaming from another computer over the Network Service.
| |
| | |
| ===Setting Up the Network Service===
| |
| | |
| Using an Android device, your network-controlled Phidget system will probably look something like this:
| |
| | |
| [[Image:Webservice general pctoandroid.png|600px|link=|alt=]] | |
| | |
| 1. Start the Network Service on the host computer
| |
| * How to do this [[OS - Windows#Network Service|on Windows]]
| |
| * How to do this [[OS - OS X#Network Service|on Mac OS]]
| |
| * How to do this [[OS - Linux#Network Service|On Linux]]
| |
| * How to do this [[OS - Phidget SBC#Network Service|On the Phidget Single Board Computer]]
| |
| | |
| 2. Download the [{{SERVER}}/downloads/examples/android-examples.tar.gz Android Examples].
| |
| * Edit the IP address and port in the {{Code|HelloWorldRemote}} example to match the IP address of the host computer (5001 is the default port)
| |
| * Transfer the example {{Code|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 Network Service===
| |
| | |
| After performing the steps above, you will be using the Network Service already. Plugging in the Phidget to the host computer will probably give you a screen like this:
| |
| | |
| [[Image:android_helloworld_remotehello.png|700px|alt=|link=]]
| |
| | |
| (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:
| |
| | |
| [[Image:android_helloworld_remotegoodbye.png|700px|alt=|link=]]
| |
| | |
| ===Debugging the Network Service===
| |
| | |
| As currently an Android device can only be a user and not a host of the Network Service, you should use debugging server side. Refer to the network service sections for each operating system:
| |
| * [[OS - Windows#Network Service|Windows]]
| |
| * [[OS - OS X#Network Service|Mac OS]]
| |
| * [[OS - Linux#Network Service|Linux]]
| |
| * [[OS - Phidget SBC#Network Service|Phidget Single Board Computer]]
| |
| In addition, if you are having network service problems, you will probably find the network service section of our [[General Troubleshooting#Network Service Troubleshooting|General Troubleshooting Guide]] helpful as well.
| |
| | |
| ==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).
| |
