=============================================================================
          MOXA UPort USB to Serial Family Driver Installation Guide
                               for Android Platform
                           Copyright (C) 2013, Moxa Inc.
=============================================================================
Date: 07/26/2013

CONTENTS

0. Note
1. Introduction
   1.1 Introduction to the UPort Android driver
   1.2 Development prerequisites
2. Quick Start Guide
   2.1 Driver files
   2.2 Using the library
   2.3 Programming guide and API reference
3. MxUPortAPIDemo
   3.1 Development environment setup
   3.2 Installation the demo program
   3.3 Rebuilding the demo program
4. Troubleshooting

-----------------------------------------------------------------------------
0. Note

   This driver applies to Android Host mode. For detailed information
   about USB host mode, please refer the official Android website
   (http://developer.android.com/guide/topics/connectivity/usb/host.html).

   Using USB on an Android device requires permission from the user. Refer to the Android 
   permission guide on the following website
   (http://developer.android.com/guide/topics/connectivity/usb/host.html#permission-d).

-----------------------------------------------------------------------------
1. Introduction

   The MOXA UPort series USB to Serial Android driver supports the following
   devices. 

   UPort 1110, 1130, 1150, 1150I
   UPort 1250, 1250I, 1410, 1450, 1450I, 1610-8, 1610-16, 1650-8, 1650-16

   This driver is intended to support Android 3.1.x and later versions. However, it
   was developed under Android 4.0.4 and ARM Cortex A8. In order to ensure
   compatibility, this version has been thoroughly tested with several
   platforms and OSs (see version.txt). However, if compatibility issues arise,
   please contact Moxa Inc. technical support (support@moxa.com) for assistance.

   All the drivers are published in form of library binary under Moxa License
   in this version. Please refer the to COPYING-MOXA.TXT file for more detail.


   1.1 Introduction to the UPort Android driver

       The MxUPortAPI is layered between the Android application and Android
       USB framework. Programmers can write Android applications with the
       MxUPortAPI to easily access UPort. 

       Traditionally, users who wanted to use UPort devices with the Android
       OS had no choice but to implement Android kernel programming. However,
       starting with Android 3.1, the Android OS supports USB host mode, which
       offers a native USB interface for operating USB devices. Moxa developed
       the MxUPortAPI to integrate the USB interface and serial programming for
       application developers. With the MxUPortAPI, programmers can easily
       create serial applications that read and write data to and from devices
       through UPort serial ports.


   1.2 Development prerequisites

       - Refer to the Android developer's getting started website for
         information on application development.
         (http://developer.android.com/training/index.html)

       - Download the Android SDK which includes Eclipse, ADT, SDK tools and
         platform tools.
         (http://developer.android.com/sdk/index.html)

       - Allow installing applications on your Android device that has a USB
         host. E.g., in Android 4.0, tap Settings > Security and then check the
         Unknown sources checkbox.

       - To setup your Android device, connect to the Android IDE, download the
         Google USB driver for Windows, or read Using Hardware Devices for Mac
         and Linux.

       - When everything is ready, type "adb devices" and you will get the
         serial number of your device.

-----------------------------------------------------------------------------
2. Quick Start Guide


   2.1 Driver files

       The released driver name is 
       "driv_android_mxuport_vX.Y_build_yymmddhh.zip"

       Unzip this file to decompress the driver files. It contains following
       files.

       demo        - Contains MxUPortAPIDemo, which is a simple example to
                     demostrate the use of this library created by Android SDK.
       help        - Includes MxUPortAPI references and programming guide.
       lib         - Includes Java library driver mxuportapi.jar and
                     COPYING-MOXA.TXT
       readme.txt  - This file
       version.txt - Release note


   2.2 Using the library

       Follow these steps to use the MxUPortAPI library.

       - Extract driv_android_mxuport_vX.Y_build_yymmddhh.zip to
         $(SDK_ROOT)\mxuport.

       - In an existing project, add $(SDK_ROOT)\mxuport\lib\mxuportapi.jar
         as an external JAR library.

       - Add the following code to import libraries.

           import com.moxa.mxuportapi.*;
           import com.moxa.mxuportapi.MxUPort.*;

       - Refer to the following link to request USB permission
         (http://developer.android.com/guide/topics/connectivity/usb/host.html#permission-d),
         or simply add the following code in your OnCreate() activity.

           UsbManager mgr = (UsbManager)getSystemService(Context.USB_SERVICE); 
           MxUPortService.requestPermission( this, mgr, 
                                             "MY_PERMISSION", 0, 0, null);

       - Add the following code to send a "Hello World" string to the first
         discovered UPort.

         UsbManager mgr = (UsbManager)getSystemService(Context.USB_SERVICE); 
         /* Enumerate and initialize UPorts on system */
         List<MxUPort> portList = MxUPortService.getPortInfoList(mgr);
         if( portList!=null ){
             IoctlMode m = new IoctlMode( 9600, MxUPort.DATA_BITS_8,
                                          MxUPort.PARITY_NONE,
                                          MxUPort.STOP_BITS_1 );
             byte [] buf = {'H', 'e', 'l', 'l', 'o', ' ',
                            'W', 'o', 'r', 'l', 'd'};

             /* Get first UPort device */
             MxUPort p = portList.get(0);
             try {
                p.open();
                p.setIoctlMode(m);
                p.write(buf, buf.length);
                p.close();
             } catch (MxException e) {
                  // Error handling
             }
         }


   2.3 Programming guide and API reference
       MxUPortAPI offers javadoc for programmers. Users can set the javadoc
       path in the class path of the current project to invoke the documatation
       during development.

       Users may also browse $(SDK_ROOT)\mxuport\help\index.html to read the
       programming guide and API reference for the Android SDK.

-----------------------------------------------------------------------------
3. MxUPortAPIDemo


   3.1 Development environment setup

       Refer to the following steps to build an environment to use the demo
       program in a Windows environment:

       - Download and install Android SDK (Eclipse + ADK) from the official website
         (http://developer.android.com/sdk/index.html).

       - Follow the setup wizard to install Android Studio.

       - Prepare an Android device and download the Google USB driver
         (http://developer.android.com/sdk/win-usb.html).

       - Use a USB cable to connect the Android device and PC. Manually install a
         suitable driver for your Android device.

       - Open a prompt and change the directory to $(SDK_ROOT)\sdk\platform-tools.
         Type "adb devices" to check whether the device is setup.

       Your PC should now be ready for developing Android applications on the
       Android device you just set up.


   3.2 Install the prebuild demo program

       - On your Android device, open [settings] > [security] and check the 
         checkbox to allow unknown sources.

       - Open a prompt, and change the directory to $(SDK_ROOT)\sdk\platform-tools.

       - To copy MxUPortAPIDemo.apk to the Android device, 
         type "adb push $(SDK_ROOT)\mxuport\demo\bin\MxUPortAPIDemo.apk /mnt/sdcard"

       - To install MxUPortAPIDemo.apk,
         type "adb shell pm install /mnt/sdcard/MxUPortAPIDemo.apk"

       - On your Android device, click MxUPortAPIDemo.apk to install it.

       The demo program should appear and be able to run on your
       Android device.


   3.3 Rebuilding the demo program

       Refer to the following steps to rebuild the demo project:

       - Use the following steps to import the MxUPortAPIDemo project:
         1. Run [File] > [Import...] > [Existing Android Code Into Workspack] 
         2. Browse to the location of MxUPOrtAPIDemo
         3. Click finish.
         A project "MxUPortAPIDemo" will be created in the project list.

       - Right click the MxUPortAPIDemo project.

       - Click [Run as ...] or [Debug as ...]

       - Click [Android application]

       The demo program should start to run on your Android device.

-----------------------------------------------------------------------------
4. Troubleshooting


   1. The UPort 11x0 series needs to reset the device to complete an initialization
      that includes upgrading the firmware. This behavior causes the Android system
      to discover the UPort 11x0 device again. User applications should be aware of
      and handle these changes.

-----------------------------------------------------------------------------
