Overview | Package | Class | Use | Tree | Index
PREV NEXT | FRAMES NO FRAMES

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

- Refer to the Android developer's getting started website for information on application development. (here)
- Download the Android SDK which includes Eclipse, ADT, SDK tools and platform tools. (here)
- 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 following result.

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.

> > - demo A simple example to demonstrate the use of this library created by the Android SDK.
> > - help Includes a programming guide and API references.
> > - lib Includes the Java library driver mxuportapi.jar and COPYING-MOXA.TXT
> > - readme.txt Driver information in text file format.
> > - version.txt Release notes.

> 3.2 F ollow 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.*;

> - If USB permission is required, see Section 4.2 about USB permission 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 UPort discovered.

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

> - 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, t ype:

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

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

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

> - On your Android device, click the MxUPortAPIDemo.apk to install it.
> - The demo program should now be visible and ready to run on your Android device.

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

Overview | Package | Class | Use | Tree | Index
PREV NEXT | FRAMES NO FRAMES