This document is the programming guide for the MxNPortAPI. You can get information about how to code with the MxNPortAPI quickly and how to link the MxNPortAPI Library into your program.

1. Introduction to the NPort Android API

The MxNPortAPI is layered between the Android application and Android network manager framework, Programmers can write Android applications with the MxNportAPI to easily access NPort in Real COM mode.

This Android library is compatible with Java 1.7 and Android 3.1 (Honeycomb - API version 12) or later verions. 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 libraries are published in form of library binary under Moxa License in this version. Please refer to the COPYING-MOXA.TXT file for more detail.

2. Development prerequisites

3. Quick start

3.1 Driver files

The released driver name is "android_mxnportapi_vX.Y_build_yymmddhh.zip". Unzip this file to decompress the driver files. It contains following files.

3.2 Follow these steps to use the MxNPortAPI library

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

3.4 Rebuild the demo program

 You may refer to following steps to rebuild the demo project:

4. Programming guide

4.1 MxNPort objects

The MxNPort API contains Java objects and is designed to be easy to use. Developers are not requires to have network or WI-FI programming knowledge since the MxNPort object presents real serial ports. A service routine, MxNPortService, offers the system wide server like enumeration and product ID definition. The MxException object handles errors and exceptions in the program.

4.2 Requesting Network permission

We need these permissions that allow applications to access network, such as INTERNET, ACCESS_NETWORK_STATE, CHANGE_NETWORK_STATE, ACCESS_WIFI_STATE and CHANGE_WIFI_STATE. All of these permissions are designated as Normal Permissions, the system will automatically grant the app these permissions at install time.

You can declare that your app needs permissions by listing those permissions in the App Manifest. (more

4.3 Enumerating MxNPort

Call MxNPortService.getNPortInfoList() to query the list of MxNPort devices currently connected to Android system in the same subnet. The list is presented in the same sequence as Android discovered them.

List<MxNPort> NPortList = MxNPortService.getNPortInfoList();
if(NPortList!=null){
    //Process the MxNPort operation
}

MxNPortService.getNPortInfoList() returns a standard Java List array containing all MxNPorts. Note: MxNPortService.getNPortInfoList() will block the thread about five seconds before it returns the list arrsy of MxNPorts. In Android system, you need to keep your application responsive to avoid the system displaying an ANR dialog to the user. (more

4.4 Controlling MxNPort

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

MxNPort.IoctlMode mode = new MxNPort.IoctlMode();
mode.baudRate = 38400;
mode.dataBits = MxNPort.DATA_BITS_8;
mode.parity = MxNPort.PARITY_NONE;
mode.stopBits = MxNPort.STOP_BITS_1;
MxNPort mxNPort = NPortList.get(0);
try {
    byte[] buf = {'H','e','l','l','o',' ','W','o','r','l','d'};
    mxNPort.open();
    mxNPort.setIoctlMode(mode);
    mxNPort.write(buf, buf.length);
    mxNPort.close();
} catch (MxException e){
    //Error handling
}

The port should be opened before processing most APIs; otherwise it returns MxException.PortIsNotOpened. Use MxNPort.IoctlMode to create basic serial parameters and pass then to MxNPort.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 MxNPort

 Although Java has a mechanism to collect garbege, it can't release the resource out of the Java system. Therefore, remeber 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 MxNPort API don't be allowed to call in main thread

Most of MxNPort API functions are use the network I/O operation, and the application will block on the I/O operation. Applications which is targeting the Android 3.0 or higher versions don't be allowed to do networking on their main event loop threads, or the Android system will throw NetworkOnMainThreadException. Therefore, you should create another thread to use these functions.

5.2 The MxNPort throw the CommandTimeout MxException

When the MxNPort API can not correctly receive the NPort reply command, it will throw the CommandTimeout MxException after five seconds. There are several reasons cause the NPort can not correctly reply command.