This document provides a quick start and programming guide. Read this page first before using the MxUPort API.

See:
          Description

Packages
com.moxa.mxuportapi  

 

This document provides a quick start and programming guide. Read this page first before using the MxUPort API.

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.

 

2. Development prerequisites

 

3. Quick start

3.1 Driver files

Unzip the file "driv_android_mxuport_vX.Y_build_yymmddhh.zip" to extract the driver files. The following files will be extracted.

3.2 Follow these steps to use the MxUPortAPI library.

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

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

     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
         }
     }

3.3 Follow these steps to run the demo program (MxUPortAPIDemo.apk)

     adb push $(SDK_ROOT)\mxuport\demo\bin\MxUPortAPIDemo.apk /mnt/sdcard"       

     adb shell pm install /mnt/sdcard/MxUPortAPIDemo.apk"

3.4 Rebuild the demo program

You may 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 Workspace] 
    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 running on your Android device.

 

4. Programming guide

4.1 MxUPort objects

The MxUPort API contains Java objects and is designed to be easy to use. Developers are not required to have USB programming knowledge since the MxUPort object presents real serial ports. A service routine, MxUPortService, offers the system wide server like enumeration and product ID definition. The MxException object handles errors and exceptions in the program.

4.2 Requesting USB permission

Android requires user permission to access USB devices like UPort. (more) There are two ways to inform the user that we need a permission.

  1. Add the USB vendor ID and product ID to your application. When a suitable USB device is plugged in, the application is launched and a request dialog appears.
  2. Call android.hardware.usb.UsbManager.requestPermission at run-time and wait for user to grant permission.

The MxUPort API wraps the wecond method and offers MxUPortService.requestPermission to easily ask a permission. It also offers a MxUPort.hasUsbPermission to query whether the port has permission or not. Once the USB has permission it can be used by the MxUPort API.

4.3 Enumerating MxUPort

Call MxUPortService.getPortInfoList() to query the list of MxUPort devices currently connected to Android system. The list is presented in the same sequence as Android discovered them.

     UsbManager mgr = (UsbManager)getSystemService(Context.USB_SERVICE); 
     List<MxUPort> portList = MxUPortService.getPortInfoList(mgr);
     if( portList!=null ){
         // Process the MxUPort operation

     }

MxUPortService.getPortInfoList() returns a standard Java List array containing all MxUPorts. Note: With respect to lack of USB permission, the MxUPort represents a NullPortDriver object. The NullPortDriver has only one method hasUsbPermission(). Developers can use this method to find any device they have not been permitted to use.

4.4 Controlling MxUPort

Get the returned MxUPort from the standard Java list. MxUPort also offers the getPortName() method for more information about the current port.

     MxUPort.IoctlMode m = new MxUPort.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'};

     MxUPort p = portList.get(0);
     try {
          // Request permission before calling these APIs.
          p.open();
          p.setIoctlMode(m);
          p.write(buf, buf.length);
          p.close();
     } catch (MxException e) {
          // Error handling
     }

The port should be opened before processing most APIs; otherwise it returns MxException.PortIsNotOpened. Use MxUPort.IoctlMode to create basic serial parameters and pass them to MxUPort.setIoctlMode(). The parameters will be applied to the serial port. At this point, you can read or write data to the serial port. If an error occurs, an MxException will be caught by a try / catch loop. Developers can call MxException.getErrorCode() to check the cause when handling errors.

4.5 Closing MxUPort

Although Java has a mechanism to collect garbage, it can't release the resources out of the Java system. Therefore, remember to close the port when the program exits. The Android application offers a finish() that can perform this job. Refer to the Managing the Activity Lifecycle for more information.

5. Troubleshooting

5.1 The UPort 11x0 series requires 2nd time permission

Booting up the UPort 11x0 series requires resetting the device to finish the initialization. Users give the UPort 11x0 series permission to do an initialization the first time. When the initialization process is done, the UPort 11x0 series will be reset. This behavior causes the Android system to assign a different USB address for the 11x0 device. Users must give this newly addressed UPort a new permission for normal operation.

In your program, call MxUPortService.getPortInfoList() the first time. It finishes the initialization and returns an MxUPort without permission. The user application can call MxUPort.hasUsbPermission() to check this state. The the application should ask permission again. Refer to the MxUPortAPIDemo source code for a detailed implementation.