=============================================================================
                MOXA NPort Android Library Programming Guide                
                             for Android Platform
                         Copyright (C) 2017, Moxa Inc.
=============================================================================
Date: 10/31/2017

CONTENTS

1. Introduction
   1.1 Introduction to the NPort Android Library
   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. MxNPortAPIDemo
   3.1 Development environment setup
   3.2 Installation the demo program
   3.3 Rebuilding the demo program
4. Troubleshooting

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

   The MOXA NPort Android Library supports the following devices. 

   CN2600 Series: CN2610-8, CN2610-16, CN2610-8-2AC, CN2610-16-2AC,CN2650-8, 
                  CN2650-16, CN2650-8-2AC, CN2650-16-2AC 
 CN2500 Series: CN2510-8, CN2510-16, CN2510-8-48V, CN2510-16-48V  
 NPort DE Series: DE-211, DE-311
 NPort 5100 Series: NPort 5110, NPort 5130, NPort 5150, NPort 5110-T,
                      NPort 5110A, NPort 5130A, NPort 5150A, NPort P5150A
 NPort 5200 Series: NPort 5210, NPort 5230, NPort 5232, NPort 5232I, 
                      NPort 5210-T, NPort 5230-T, NPort 5232-T, 
                      NPort 5232I-T, NPort 5210A, NPort 5230A, NPort 5250A
   NPort 5400 Series: NPort 5410, NPort 5430, NPort 5430I, NPort 5450, 
                      NPort 5450I, NPort 5450-T, NPort 5450I-T
 NPort 5600 Desktop Series: NPort 5610-8-DT, NPort 5610-8-DT-J, 
                              NPort 5650-8-DT, NPort 5650-8-DT-J, 
                              NPort 5650I-8-DT
 NPort 5600 Rackmount Series: NPort 5610-8, NPort 5610-8-48V, NPort 5630-8, 
                                NPort 5650-8, NPort 5610-16, 
                                NPort 5610-16-48V, NPort 5630-16, 
                                NPort 5650-16, NPort 5650-8-M-SC, 
                                NPort 5650-16-M-SC, NPort 5650-8-S-SC, 
                                NPort 5650-16-S-SC
   NPort Wireless Series: NPort W2150A, NPort W2250A
 NPort IA5000 Series: NPort IA5150, NPort IA5150I, NPort IA5150-S-SC, 
                        NPort IA5150I-S-SC, NPort IA5150-M-SC, 
                        NPort IA5150I-M-SC, NPort IA5250, NPort IA5150-T, 
                        NPort IA5150I-T, NPort IA5150-S-SC-T, 
                        NPort IA5150I-S-SC-T, NPort IA5150-M-SC-T, 
                        NPort IA5150I-M-SC-T, NPort IA5250-T, NPort IA5150A, 
                        NPort IA5150AI, NPort IA5250A, NPort IA5250AI
 NPort 6000 Series: NPort 6150, NPort 6250, NPort 6250-M-SC, 
                      NPort 6250-S-SC, NPort 6450, NPort 6610-8, 
                      NPort 6610-16, NPort 6610-32, NPort 6650-8, 
                      NPort 6650-16, NPort 6650-32, NPort 6610-8-48V, 
                      NPort 6610-16-48V, NPort 6610-32-48V, NPort 6650-8-48V, 
                      NPort 6650-16-48V, NPort 6650-32-48V
 NPort S8000 Series: NPort S8455I-MM-SC, NPort S8455I-SS-SC, NPort S8455I, 
                       NPort S8458-4S-SC-T
 MiiNePort Series: MiiNePort E1, MiiNePort E1-T, MiiNePort E2, 
                     MiiNePort E2-T, MiiNePort E3, MiiNePort E3-T, 
                     MiiNePort E1 SDK, MiiNePort E1-H SDK, MiiNePort E2 SDK, 
                     MiiNePort E2-H SDK, MiiNePort W1
 NPort I/O Series: NPort IAW5150A-6I/O, NPort IAW5250A-6I/O, 
                     NPort IAW5150A-12I/O, NPort IAW5250A-12I/O
   NPort S9450 Series: NPort S9450I-WV-T, NPort S9450I-HV-T, 
                       NPort S9450I-2M-SC-WV-T, NPort S9450I-2M-SC-HV-T, 
                       NPort S9450I-2M-ST-WV-T, NPort S9450I-2M-ST-HV-T, 
                       NPort S9450I-2S-SC-WV-T, NPort S9450I-2S-SC-HV-T, 
                       NPort S9450I-2S-ST-WV-T, NPort S9450I-2S-ST-HV-T


   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.
   	   
   1.1 Introduction to the NPort Android Library

	The MxNPortAPI is an android library. When NPort is using in the Real
        COM mode, the MxNPortAPI can provide the function to map NPort serial
        ports to network interface. With MxNPortAPI, Programmers can easily 
        create application that read and write data to and from devices 
        through NPort 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 Studio which includes SDK tools and platform 
         tools.
         (https://developer.android.com/studio/index.html)

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

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


   2.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        - Contains MxNPortAPIDemo, which is a simple example to
                     demostrate the use of this library created by Android SDK.
       help        - Includes MxNPortAPI references and programming guide.
       lib         - Includes Java library driver mxnportapi.aar and
                     COPYING-MOXA.TXT
       readme.txt  - This file
       version.txt - Release note

   2.2 Using the library

       Follow these steps to use the MxNPortAPI library.

       - Extract android_mxnport_vX.Y_build_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. MxNPortAPIDemo


   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 Studio and SDK tool from the official website
         (https://developer.android.com/studio/index.html).

       - Follow the setup wizard to install Android Studio.
         (https://developer.android.com/studio/install.html)

       - Prepare an Android device and download the Google USB driver
         (https://developer.android.com/studio/run/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 MxNPortAPIDemo.apk to the Android device, 
         type "adb push $(SDK_ROOT)\mxnport\demo\app\build\outputs\apk\MxNPortAPIDemo.apk /mnt/sdcard"

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

       - On your Android device, click MxNPortAPIDemo.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 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.

       - Right click the MxNPortAPIDemo project.

       - 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 to run on your Android device.

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

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

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