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

- Refer to the Android developer's getting started website for information on application development. (here)
- Download the Android Studio, 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 tge following result.

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

> > - 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 mxnportapi.arr and COPYING-MOXA.TXT
> > - readme.txt Driver information in text file format.
> > - version.txt Release note.

> #### 3.2 Follow these steps to use the MxNPortAPI library

> - Extract android_mxnportapi_vX.Y_yymmddhh.zip to $(SDK_ROOT)\mxnport
> - In an existing project, import $(SDK_ROOT)\mxnport\lib\mxnportapi.aar as a new project module.
> - Select the mxnportapi module as the current nodule should depend on.
> - Add the following code to import libraries.

> > import com.moxa.mxnportapi.*;

> - Add the following permissions in your AndroidManifest.xml.

> > <uses-permission android:name="android.permission.INTERNET" />
> > <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
> > <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
> > <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
> > <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

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

> > Thread thread = new Thread() {
> > @Override
> > public void run() {
> > /* Enumerate and initialize NPorts on system */
> > List<MxNPort> NPortList = MxNPortService.getNPortInfoList();
> > if(NPortList!=null){
> > 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;
> > /* Get first NPort device */
> > 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
> > }
> > }
> > }
> > };
> > thread.start();

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

> - On your Android device, open [setting] > [security] and check the checkbox to allow unknown sources.
> - Open a prompt, and change the directory to %(SDK_ROOT)\sdk\platform-tools.
> - To copy MxNPortAPIDemo.apk to the Android device, type:

> > adb push $(SDK_ROOT)\mxnport\demo\app\build\outputs\apk\MxNPortAPIDemo.apk /mnt/sdcard

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

> > adb shell pm install /mnt/sdcard/MxNPortAPIDemo.apk

> - On your Android device, click the MxNPortAPIDemo.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 following steps to rebuild the demo project:

> - Use the following steps to import the MxNPortAPIDemo project:
> 1. Run [File] > [New] > [Import Project...]
> 2. Browse to the location of MxNPortAPIDemo
> 3. Click finish.

> A Project MxNPortAPIDemo will be created in the project list.

> - Run [Build] > [Make Project]
> - Run [Run] > [Run 'app'] or [Debug 'app']
> - Select your Android device which you want to run the demo program.
> - The demo program should start running on your Android device.

### 4. Programming guide

> #### 4.1 MxNPort objects

> > The MxNPort API contains Java objects and is designed to be easy to use. Developers are not required to have network or WI-FI programming knowledge since the MxNPort object presents real serial ports. A service routine, MxNPortService, provides the function to search NPort devices in your environment. 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 them 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 garbage, it can't release the resource 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 MxNPort API won't be allowed to call in main thread

> > Most of MxNPort API functions are using the network I/O operation, and the application will block on the I/O operation. Applications which target Android 3.0 or higher versions won'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 why the NPort can not correctly reply command.

> > 1. The network is disconnected, the MxNPort API can't send command to the NPort or can't receive the reply from NPorts
> > 2. When you call some functions of the MxNPort API to set serial parameter, the NPort can't support that configuration. The NPort won't reply the command that it can't support.
> >    For example:

> >    > the setBaud(int speed) can accept user input 921600 as true baud rate. If the NPort can't support baud rate 921600, it will ignore the command. After five seconds, the MxNPort API will throw the CommandTimeout MxException.