=============================================================================
      MOXA UPort 2000 Series USB to Serial Hub Driver Installation Guide
                      for Linux Kernel 6.x
                    Copyright (C) 2012, Moxa Inc.
=============================================================================
Date: 02/24/2023

CONTENTS

0. Note
1. Introduction
2. System Requirements
3. Installation
   3.1 Driver files
   3.2 Device naming convention
   3.3 Module driver configuration
   3.4 Static driver configuration
   3.5 Verify driver installation
4. Utility
5. Troubleshooting

-----------------------------------------------------------------------------
0. Note

   The Moxa UPort 2000 series USB to Serial Hub driver can be used in
   the Linux kernel with the usbcore and usbserial modules. These two modules
   are built-in modules in the Linux kernel version 2.6.x and follow. In the
   Linux kernel version, you must check these two build-in modules existed.
   Otherwise, you will fail to using MOXA UPort 2000 series USB to Serial Hub
   driver.

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

   The MOXA UPort 2000 series USB to Serial Hub Linux driver supports following 
   devices. 

    - UPort 2210, 2 port RS-232 USB to Serial Hub.
    - UPort 2410, 4 port RS-232 USB to Serial Hub.

   This driver supports x86 and x64(AMD64/EM64T) hardware platform. In
   order to maintain compatibility, this version has also been properly
   tested with several Linux distribution (see version.txt). However,
   if compatibility problem occurs, please contact Moxa Inc. technical
   support. (support@moxa.com)

   All the drivers are published in form of source code under
   GNU General Public License in this version. Please refer to GNU General
   Public License announcement in each source code file for more detail.

   Before you install the driver, please refer to hardware installation
   procedure in the User's Manual.

-----------------------------------------------------------------------------
2. System Requirements
    - Hardware platform: x86, x64
    - Kernel version: 5.x
    - gcc version 3.x 
    - kernel source

   Additional requirements for Raspbian
    -  gcc-4.8.3 or above 
    -  ncurses-devel-5.9 or above
    -  rpi-source (https://github.com/notro/rpi-source/wiki)   

   Note:
    - rpi-source is a 3rd party package offering integrated kernel souce.
      However the requirement may be various for different Raspbian version.
      Please read the manual of Raspbian in order to get full kernel source.

-----------------------------------------------------------------------------
3. Installation

   3.1 Driver files
   3.2 Device naming convention
   3.3 Module driver configuration
   3.4 Static driver configuration
   3.5 Verify driver installation

   3.1 Driver files

       The driver may be obtained from Moxa website, under the product page.
       The first step is to copy driver file
       "driv_linux_uport2000_[VERSION]_[BUILD].tgz" into a user directory.
       e.g. /moxa. Please execute following commands.

       # cd /moxa
       # tar xvfz driv_linux_uport2000_vXX.YY_build_ZZ.tgz
       
       You may find all driver files in /moxa/mxuport2000.

   3.2 Device naming convention

       Dialin and callout port
       -----------------------
       This driver remains traditional serial device properties. Because the
       limitation of the usb build-in modules that are usbcore and usbserial,
       There is only one special file name for each serial port. This one is
       dial-in port which is named "ttyUSBxx".

   3.3 Module driver configuration

       3.3.1 Build the MOXA driver and utility

          Before using the MOXA driver, you need compile all the source 
          code. This step is only needed to be executed once.
          Besides, you have to re-compile the source code every time you
          modify the source code.

          Find "Makefile" in /moxa/mxuport2000, then run

          # make install

          The driver file "mxuport2000.ko" and utility file "mxustty" will be
          properly compiled and copied to system directories respectively.

          Or you can use "mxinstall" in /moxa/mxuport2000 to install Moxa
          software. "mxinstall" is a script that make it easy to install
          both driver and utility, and then load the driver in one single step.

          Please refer to section 4 to use the utility "mxustty".

       3.3.2 Load the MOXA driver  

          The driver will be loaded automatically while plugging the 
          UPort 2210/2410 into you PC, or you can load the 
          driver manually.

          # modprobe mxuport2000 

          It will activate the module driver. You may run "lsmod" to check
          if "mxuport2000" is activated. Before you load this module driver,
          you have to run "lsmod" to check if "usbcore" and "usbserial" are 
          activated.

       3.3.3 Unload the MOXA driver

          The driver will not be unloaded when you remove the MOXA UPort
          2210/2410 from PC. Once you want to unload the MOXA driver,
          you have to unload it manually.

          #make remove

       3.3.4 Remove the MOXA driver and utility files

          To remove the MOXA files, please go to the path /moxa/mxuport2000,
          then execute

          #make clean

          Both the driver and utility files will be removed respectively.

   3.4 Static driver configuration

       Note: To use static driver, you must install the linux kernel
             source package.

       3.4.1 Create link
          # cd /usr/src/<kernel-source directory>/drivers/usb/serial/
          # ln -s /moxa/mxuport2000/driver/mxuport2000.c mxuport2000.c
          # ln -s /moxa/mxuport2000/driver/mxuport2000.h mxuport2000.h

       3.4.2 Modify kernel configuration file.
          Add the following line into configuration file.
          /usr/src/<kernel-source directory>/drivers/usb/serial/Kconfig
          ...
          config USB_SERIAL_CONSOLE
          ...
          config USB_SERIAL_GENERIC
          ...
          config MOXA_UPORT_2000                <-- Add these lines.
          tristate "USB Moxa UPort 2000 Driver" <-- 
          depends on USB_SERIAL                 <--
          ...

       3.4.3 Modify the kernel Makefile 
          Add the following line to the last line of Makefile.
          /usr/src/<kernel-source directory>/drviers/usb/serial/Makefile
          ...
          ...
          ...
          obj-$(CONFIG_MOXA_UPORT_2000) += mxuport2000.o <-- Add these lines.

       3.4.4 Setup kernel configuration

          Configure the kernel:

            # cd /usr/src/<kernel-source directory>
            # make menuconfig

          You will go into a menu-driven system. Please select [Device Drivers]
          [USB Support], [USB Serial Converter support], enable both the 
          [USB Serial Converter support] and the [USB MOXA UPORT 2000 Driver]
          drivers with "[*]" by pressing space bar for built-in (not "[M]"),
          then select [Exit] to exit this program and save kernel
          configurations. 

       3.4.5 Rebuild kernel
          The following are for Linux kernel rebuilding, for your 
          reference only.
          For appropriate details, please refer to the Linux document.

          a. cd /usr/src/<kernel-source directory>
          b. make
          c. make modules	
          d. make modules_install
          e. make install

   3.5 Verify driver installation
       You may refer to /var/log/messages to check the latest status
       log reported by this driver whenever it's activated or type command
       "dmesg" to get driver information includes model name and tty name of
       installed UPorts.

       Following demonstrates the messages when installing UPort 2210.

         usbcore: registered new interface driver mxuport2000
         usbserial: USB Serial support registered for MOXA 2410 USB Serial Driver
         usbserial: USB Serial support registered for MOXA 2450 USB Serial Driver
         usbserial: USB Serial support registered for MOXA 2210 USB Serial Driver
         usbserial: USB Serial support registered for MOXA 2250 USB Serial Driver
         mxuport2000: 1.1.3:MOXA USB Serial Driver
         usb 1-4: new high-speed USB device number 5 using ehci-pci
         usb 1-4: New USB device found, idVendor=110a, idProduct=2210
         usb 1-4: New USB device strings: Mfr=2, Product=3, SerialNumber=1
         usb 1-4: Product: MOXA UPort Device    
         usb 1-4: Manufacturer: Moxa Inc                
         usb 1-4: SerialNumber: 0001BEE2
         mxuport2000 1-4:1.0: MOXA 2210 USB Serial Driver converter detected
         usb 1-4: MOXA 2210 USB Serial Driver converter now attached to ttyUSB0
         usb 1-4: MOXA 2210 USB Serial Driver converter now attached to ttyUSB1

       Above message indicates /dev/ttyUSB[0-1] are installed successfully.

-----------------------------------------------------------------------------
4. Utility

      The utility "mxustty" is a integrated tool for MOXA UPort 2000 series
      to locate the device.

      The "mxustty" allows you to locate the device with the "l" operation,
      the device alarms the buzzer(UPort 2410) and twinkles the status LED to
      indicate the UPort 2000 series device.

      Usage of "mxustty" is listed below.

      mxustty <operation> device

      operation : Set the operation of the tool.
      device    : The UPort 2000 series device node.

      parameter  value     comment

      operation  -h        Help
                 -l        Locate the device

      For example:

      To find the device:
         # mxustty -l /dev/ttyUSB3

-----------------------------------------------------------------------------
5. Limitation 
   1. Max. ports
      If you want to install more than one UPort 2000 series USB serial Hub,
      the best way is to connect to USB port directly. In lab test, four USB
      ports with four UPort 2210/2410 still work very well.

   2. Compile error
      To build Moxa driver, it needs kernel header files. If you got
      some compile error, please run "rpm -qa | grep kernel" to check 
      whether the kernel-source package is installed properly. If not,
      please get the kernel-source irpm package and run "rpm -ivh <pacakge>"
      to install. You also need to make sure the build tool is ready,
      including make/gcc/lib. Please see Linux relative document for 
      more information.

  3. Compatibility
     The UPort 2210/2410 might be detected fail under kernel 2.6.12
     (Fedora Core 2 (2.6.5), Red Hat Enterprise Linux 4 (2.6.9),
     Fedora Core 3 (2.6.9), Fedora Core 4 x64 (2.6.11)). Once the
     Linux is running, the UPort 2210/2410 may not be found while plugging
     to the PC. If it happened, try to plug the UPort 2210/2410 into the PC
     few more times. The other way is to update the kernel above 2.6.11,
     the UPort 2210/2410 can be found correctly.

  4. Data Lost
     Between kernel 2.6.15 and 2.6.17, it may cause data lost. So far, we
     tested the UPort 2210/2410 in Fedora Core 5 (2.6.15) with four different
     PC for high speed (921600bps) burn-in, and it happened within three hours.
     Update the kernel to newer version to solve the issue. We tested the
     UPort 2210/2410 again in Fedora Core 5 (2.6.21) for high speed (921600bps)
     long time (8hr) burn-in and it works fine.

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