com.moxa.mxuportapi
Interface MxUPort


public interface MxUPort

The MxUPort class includes all Host mode APIs for UPort devices. An MxUPort object is an abstraction of a UPort serial port. Although some MxUPorts are distributed from one USB port, the user can process each MxUPort, even without any knowledge of USB programming.

The MxUPort is created by MxUPortService.getDevieInfoList. Users should not create an MxUPort by themselves due to lack of internal initialization.

The MxUPort offers these categories for serial communication.

Port control
open
close
setIoctlMode
setFlowCtrl
setBaud
setRTS
setDTR
flush

Input/Output
read
write

Port status inquiry
getBaud
getFlowCtrl
getIoctlMode
getLineStatus
getModemStatus
getOQueue

Miscellaneous
setBreak
getInterface
setInterface
getPortName
setPortName
getUsbDevice
getUsbDeviceName
getUsbReadTimeout
setUsbReadTimeout
getUsbWriteTimeout
setUsbWriteTimeout
hasUsbPermission


Nested Class Summary
static class MxUPort.FlowCtrl
          This class represents serial flow control settings.
static class MxUPort.IoctlMode
          This class represents serial parameters such as baud rate, data bits, parity, and stop bits.
static class MxUPort.LineError
          This class represents errors on line.
static class MxUPort.ModemStatus
          This class represents modem status, such as CTS, DSR, DCD, and RI.
 
Field Summary
static int CTS_FLOW_ENABLE
          Defines CTS hardware flow control
static int CTS_OFF
          Defines CTS state OFF
static int CTS_ON
          Defines CTS state ON
static int DATA_BITS_5
          Defines serial communication with 5 data bits
static int DATA_BITS_6
          Defines serial communication with 6 data bits
static int DATA_BITS_7
          Defines serial communication with 7 data bits
static int DATA_BITS_8
          Defines serial communication with 8 data bits
static int DCD_OFF
          Defines DCD state OFF
static int DCD_ON
          Defines DCD state ON
static int DSR_FLOW_ENABLE
          Defines DSR hardware flow control
static int DSR_OFF
          Defines DSR state OFF
static int DSR_ON
          Defines DSR state ON
static int DTR_FLOW_ENABLE
          Defines DTR hardware flow control
static int DTR_OFF
          Defines DTS state OFF
static int DTR_ON
          Defines DTS state ON
static int DTRDSR_FLOW_ENABLE
          Defines DTR/DSR software flow control
static int DTRDSR_FLOW_MASK
          Defines the bit mask of DTR/DSR hardware flow control
static int FLUSH_INPUT
          Defines the flush to read buffer
static int FLUSH_OUTPUT
          Defines the flush to write buffer
static int LINE_ERROR
          Defines the error state for each field
static int LINE_NO_ERROR
          Defines the non-error state for each field
static int MODE_RS232
          Defines the RS232 interface
static int MODE_RS422
          Defines the RS422 interface
static int MODE_RS485_2W
          Defines the 2-wire RS485 interface
static int MODE_RS485_4W
          Defines the 4-wire RS485 interface
static int PARITY_EVEN
          Defines even parity checking
static int PARITY_MARK
          Defines mark parity checking
static int PARITY_NONE
          Defines no parity checking
static int PARITY_ODD
          Defines odd parity checking
static int PARITY_SPACE
          Defines space parity checking
static int RI_OFF
          Defines RI state OFF
static int RI_ON
          Defines RI state ON
static int RTS_FLOW_ENABLE
          Defines RTS hardware flow control
static int RTS_OFF
          Defines RTS state OFF
static int RTS_ON
          Defines RTS state ON
static int RTSCTS_FLOW_ENABLE
          Defines RTS/CTS hardware flow control
static int RTSCTS_FLOW_MASK
          Defines bit mask of RTS/CTS hardware flow control
static int STOP_BITS_1
          Defines 1 stop bit on serial communication
static int STOP_BITS_1_5
          Defines 1.5 stop bits on serial communication
static int STOP_BITS_2
          Defines 2 stop bits on serial communication
static int XOFF_FLOW_ENABLE
          Defines software auto receive flow control
static int XON_FLOW_ENABLE
          Defines software auto transmit flow control
static int XONXOFF_FLOW_ENABLE
          Defines XON/XOFF software flow control
static int XONXOFF_FLOW_MASK
          Defines the bit mask of RTS/CTS hardware flow control
 
Method Summary
 void close()
          Closes the serial port.
 void flush(int mode)
          Flushes any data in the driver's input/output buffer.
 int getBaud()
          Get the serial port baud rate setting.
 MxUPort.FlowCtrl getFlowCtrl()
          Get the serial port's hardware and software flow control settings.
 int getInterface()
          Gets the interface for products that support multiple interface.
 MxUPort.IoctlMode getIoctlMode()
          Gets the serial port's mode settings, such as data bits, parity, and stop bits.
 MxUPort.LineError getLineStatus()
          Checks if errors occurred when receiving data; returns and cleans the error during the transaction.
 MxUPort.ModemStatus getModemStatus()
          Gets the line status, such as CTS, DSR, DCD, or RI.
 int getOQueue()
          Gets the length (in bytes) remaining in the output buffer.
 java.lang.String getPortName()
          Gets the name of the serial port; returns customized friendly name if it is available.
 android.hardware.usb.UsbDevice getUsbDevice()
          Gets the parent USB device handle of this MxUPort.
 java.lang.String getUsbDeviceName()
          Gets the device name from the USB descriptor.
 int getUsbReadTimeout()
          Gets the read timeout value for a USB read request.
 int getUsbWriteTimeout()
          Gets the write timeout value for a USB write request.
 boolean hasUsbPermission()
          Indicates whether the parent USB has permission to be accessed.
 void open()
          Opens the serial port.
 int read(byte[] buffer)
          Reads data from the port; returns the data if the buffer is full.
 int read(byte[] buffer, int length)
          Reads data from a port; returns the data if the given length of data has been received.
 int read(byte[] buffer, int length, int timeout)
          Reads data from the port; returns the data if the given length of data has been received.
 void setBaud(int speed)
          Sets the baud rate using the actual speed value.
 void setBreak(int time)
          Sends out a break signal.
 void setDTR(int mode)
          Sets the DTR state for a serial port.
 void setFlowCtrl(MxUPort.FlowCtrl flow)
          Sets the hardware and/or software flow control.
 void setInterface(int intf)
          Sets the interface for products that support multiple interface.
 void setIoctlMode(MxUPort.IoctlMode mode)
          Configures communication parameters, such as baud rate, parity, data bits and stop bits.
 void setPortName(java.lang.String name)
          Sets the port name on the device.
 void setRTS(int mode)
          Sets the RTS state for a serial port.
 void setUsbReadTimeout(int time)
          Sets the read timeout value for a USB read request.
 void setUsbWriteTimeout(int time)
          Sets the write timeout value for a USB write request.
 int write(byte[] buffer)
          Puts a block of data to the driver's output buffer.
 int write(byte[] buffer, int length)
          Puts a block of data to the driver's output buffer.
 int write(byte[] buffer, int length, int timeout)
          Puts a block of data to the driver's output buffer.
 

Field Detail

CTS_FLOW_ENABLE

static final int CTS_FLOW_ENABLE
Defines CTS hardware flow control

See Also:
Constant Field Values

CTS_OFF

static final int CTS_OFF
Defines CTS state OFF

See Also:
Constant Field Values

CTS_ON

static final int CTS_ON
Defines CTS state ON

See Also:
Constant Field Values

DATA_BITS_5

static final int DATA_BITS_5
Defines serial communication with 5 data bits

See Also:
Constant Field Values

DATA_BITS_6

static final int DATA_BITS_6
Defines serial communication with 6 data bits

See Also:
Constant Field Values

DATA_BITS_7

static final int DATA_BITS_7
Defines serial communication with 7 data bits

See Also:
Constant Field Values

DATA_BITS_8

static final int DATA_BITS_8
Defines serial communication with 8 data bits

See Also:
Constant Field Values

DCD_OFF

static final int DCD_OFF
Defines DCD state OFF

See Also:
Constant Field Values

DCD_ON

static final int DCD_ON
Defines DCD state ON

See Also:
Constant Field Values

DSR_FLOW_ENABLE

static final int DSR_FLOW_ENABLE
Defines DSR hardware flow control

See Also:
Constant Field Values

DSR_OFF

static final int DSR_OFF
Defines DSR state OFF

See Also:
Constant Field Values

DSR_ON

static final int DSR_ON
Defines DSR state ON

See Also:
Constant Field Values

DTR_FLOW_ENABLE

static final int DTR_FLOW_ENABLE
Defines DTR hardware flow control

See Also:
Constant Field Values

DTR_OFF

static final int DTR_OFF
Defines DTS state OFF

See Also:
Constant Field Values

DTR_ON

static final int DTR_ON
Defines DTS state ON

See Also:
Constant Field Values

DTRDSR_FLOW_ENABLE

static final int DTRDSR_FLOW_ENABLE
Defines DTR/DSR software flow control

See Also:
Constant Field Values

DTRDSR_FLOW_MASK

static final int DTRDSR_FLOW_MASK
Defines the bit mask of DTR/DSR hardware flow control

See Also:
Constant Field Values

FLUSH_INPUT

static final int FLUSH_INPUT
Defines the flush to read buffer

See Also:
Constant Field Values

FLUSH_OUTPUT

static final int FLUSH_OUTPUT
Defines the flush to write buffer

See Also:
Constant Field Values

LINE_ERROR

static final int LINE_ERROR
Defines the error state for each field

See Also:
Constant Field Values

LINE_NO_ERROR

static final int LINE_NO_ERROR
Defines the non-error state for each field

See Also:
Constant Field Values

MODE_RS232

static final int MODE_RS232
Defines the RS232 interface

See Also:
Constant Field Values

MODE_RS422

static final int MODE_RS422
Defines the RS422 interface

See Also:
Constant Field Values

MODE_RS485_2W

static final int MODE_RS485_2W
Defines the 2-wire RS485 interface

See Also:
Constant Field Values

MODE_RS485_4W

static final int MODE_RS485_4W
Defines the 4-wire RS485 interface

See Also:
Constant Field Values

PARITY_EVEN

static final int PARITY_EVEN
Defines even parity checking

See Also:
Constant Field Values

PARITY_MARK

static final int PARITY_MARK
Defines mark parity checking

See Also:
Constant Field Values

PARITY_NONE

static final int PARITY_NONE
Defines no parity checking

See Also:
Constant Field Values

PARITY_ODD

static final int PARITY_ODD
Defines odd parity checking

See Also:
Constant Field Values

PARITY_SPACE

static final int PARITY_SPACE
Defines space parity checking

See Also:
Constant Field Values

RI_OFF

static final int RI_OFF
Defines RI state OFF

See Also:
Constant Field Values

RI_ON

static final int RI_ON
Defines RI state ON

See Also:
Constant Field Values

RTS_FLOW_ENABLE

static final int RTS_FLOW_ENABLE
Defines RTS hardware flow control

See Also:
Constant Field Values

RTS_OFF

static final int RTS_OFF
Defines RTS state OFF

See Also:
Constant Field Values

RTS_ON

static final int RTS_ON
Defines RTS state ON

See Also:
Constant Field Values

RTSCTS_FLOW_ENABLE

static final int RTSCTS_FLOW_ENABLE
Defines RTS/CTS hardware flow control

See Also:
Constant Field Values

RTSCTS_FLOW_MASK

static final int RTSCTS_FLOW_MASK
Defines bit mask of RTS/CTS hardware flow control

See Also:
Constant Field Values

STOP_BITS_1

static final int STOP_BITS_1
Defines 1 stop bit on serial communication

See Also:
Constant Field Values

STOP_BITS_1_5

static final int STOP_BITS_1_5
Defines 1.5 stop bits on serial communication

See Also:
Constant Field Values

STOP_BITS_2

static final int STOP_BITS_2
Defines 2 stop bits on serial communication

See Also:
Constant Field Values

XOFF_FLOW_ENABLE

static final int XOFF_FLOW_ENABLE
Defines software auto receive flow control

See Also:
Constant Field Values

XON_FLOW_ENABLE

static final int XON_FLOW_ENABLE
Defines software auto transmit flow control

See Also:
Constant Field Values

XONXOFF_FLOW_ENABLE

static final int XONXOFF_FLOW_ENABLE
Defines XON/XOFF software flow control

See Also:
Constant Field Values

XONXOFF_FLOW_MASK

static final int XONXOFF_FLOW_MASK
Defines the bit mask of RTS/CTS hardware flow control

See Also:
Constant Field Values
Method Detail

close

void close()
           throws MxException
Closes the serial port.

Throws:
MxException - If an error occurs.

flush

void flush(int mode)
           throws MxException
Flushes any data in the driver's input/output buffer.

Parameters:
mode - [in] is one or both of FLUSH_INPUT and FLUSH_OUTPUT.
Throws:
MxException - If an error occurs.

getBaud

int getBaud()
            throws MxException
Get the serial port baud rate setting. The return value is the actual baud rate. For example, a return value of 9600 means 9600 bps whereas 200 means 200bps.

Returns:
The actual baud rate.
Throws:
MxException - If an error occurs.

getFlowCtrl

MxUPort.FlowCtrl getFlowCtrl()
                             throws MxException
Get the serial port's hardware and software flow control settings.

Returns:
FlowCtrl
Throws:
MxException - If an error occurs.

getInterface

int getInterface()
                 throws MxException
Gets the interface for products that support multiple interface.

Returns:
The interface: MODE_RS232, MODE_RS485_2W, MODE_RS485_4W, or MODE_RS422.
Throws:
MxException - If an error occurs.

getIoctlMode

MxUPort.IoctlMode getIoctlMode()
                               throws MxException
Gets the serial port's mode settings, such as data bits, parity, and stop bits.

Returns:
IoctlMode
Throws:
MxException - If an error occurs.

getLineStatus

MxUPort.LineError getLineStatus()
                                throws MxException
Checks if errors occurred when receiving data; returns and cleans the error during the transaction.

Returns:
LineError
Throws:
MxException - If an error occurs.

getModemStatus

MxUPort.ModemStatus getModemStatus()
                                   throws MxException
Gets the line status, such as CTS, DSR, DCD, or RI.

Returns:
ModemStatus
Throws:
MxException - If an error occurs.

getOQueue

int getOQueue()
              throws MxException
Gets the length (in bytes) remaining in the output buffer.

Returns:
The length output buffer.
Throws:
MxException - If an error occurs.

getPortName

java.lang.String getPortName()
                             throws MxException
Gets the name of the serial port; returns customized friendly name if it is available. For the UPort 1100 series, it returns the USB device name. For the UPort 1200/1400/1600 series, it returns the friendly name if it has one; otherwise it returns the USB device name with the port index.

Returns:
The port name String
Throws:
MxException - If an error occurs.

getUsbDevice

android.hardware.usb.UsbDevice getUsbDevice()
Gets the parent USB device handle of this MxUPort. Uses this handle to operate the native USB Host mode API from Android.

Returns:
The UsbDevice object.

getUsbDeviceName

java.lang.String getUsbDeviceName()
                                  throws MxException
Gets the device name from the USB descriptor. This name represents the parent of the MxUPort.

Returns:
The USB device name, or null if it is not available.
Throws:
MxException - If an error occurs.

getUsbReadTimeout

int getUsbReadTimeout()
                      throws MxException
Gets the read timeout value for a USB read request. The default value is 2000 milliseconds.

Returns:
The timeout value in milliseconds.
Throws:
MxException - If an error occurs.
See Also:
setUsbReadTimeout(int)

getUsbWriteTimeout

int getUsbWriteTimeout()
                       throws MxException
Gets the write timeout value for a USB write request. The default value is 2000 milliseconds.

Returns:
The timeout value in milliseconds.
Throws:
MxException - If an error occurs.
See Also:
setUsbWriteTimeout(int)

hasUsbPermission

boolean hasUsbPermission()
                         throws MxException
Indicates whether the parent USB has permission to be accessed. If it returns false then the USB needs to request permission from the user. Refer to MxUPortService.getPortInfoList for more information. Tips: The UPort 1100 series has a 2-step boot up process. The UPort 1100 series will be discovered again after it is reset. Checking the return value can help to determine whether the UPort need to request permission again.

Throws:
MxException
See Also:
com.moxa.mxuportapi.MxUPortService.requestPermission

open

void open()
          throws MxException
Opens the serial port.

Throws:
MxException - If an error occurs.

read

int read(byte[] buffer)
         throws MxException
Reads data from the port; returns the data if the buffer is full.

Parameters:
buffer - [in][out] The repository for the incoming data.
Returns:
The actual read data in the buffer.
Throws:
MxException - If an error occurs.

read

int read(byte[] buffer,
         int length)
         throws MxException
Reads data from a port; returns the data if the given length of data has been received.

Parameters:
buffer - [in][out] The repository for the incoming data.
length - [in] The required data length. It must not exceed the size of the buffer.
Returns:
The actual read data in the buffer.
Throws:
MxException - If an error occurs.

read

int read(byte[] buffer,
         int length,
         int timeout)
         throws MxException
Reads data from the port; returns the data if the given length of data has been received. Otherwise, if a timeout has occurred, the received data will be stored in the buffer and the length of received data will be returned.

Parameters:
buffer - [in][out] The repository for the incoming data.
length - [in] The required data length. It must not exceed the size of the buffer.
timeout - [in] The timeout value for receiving data.
Returns:
The actual read data in the buffer.
Throws:
MxException - If an error occurs.

setBaud

void setBaud(int speed)
             throws MxException
Sets the baud rate using the actual speed value.

Parameters:
speed - [in] The true baud rate, e.g. 200, 1200, 9600, 19200, etc.
Throws:
MxException - If an error occurs.

setBreak

void setBreak(int time)
              throws MxException
Sends out a break signal. This function will block access for the given length of time.

Parameters:
time - [in] Break time in milliseconds.
Throws:
MxException - If an error occurs.

setDTR

void setDTR(int mode)
            throws MxException
Sets the DTR state for a serial port.

Parameters:
mode - [in] for the DTR setting, which is either DTR_ON or DTR_OFF.
Throws:
MxException - If an error occurs.

setFlowCtrl

void setFlowCtrl(MxUPort.FlowCtrl flow)
                 throws MxException
Sets the hardware and/or software flow control. The UPort 1100 series supports RTSCTS_FLOW_ENABLE and XONXOFF_FLOW_ENABLE flow control settings. The UPort 1200/1400/1600 series support RTSCTS_FLOW_ENABLE, XONXOFF_FLOW_ENABLE, and DTRDSR_FLOW_ENABLE.

Parameters:
mode - [in] FlowCtrl contains flow control settings.
Throws:
MxException - If an error occurs.

setInterface

void setInterface(int intf)
                  throws MxException
Sets the interface for products that support multiple interface.

Parameters:
intf - [in] for interface setting. Is one of MODE_RS232, MODE_RS485_2W, MODE_RS485_4W, and MODE_RS422.
Throws:
MxException - If an error occurs.

setIoctlMode

void setIoctlMode(MxUPort.IoctlMode mode)
                  throws MxException
Configures communication parameters, such as baud rate, parity, data bits and stop bits.

Parameters:
mode - [in] IoctlMode contains serial settings.
Throws:
MxException - If an error occurs.

setPortName

void setPortName(java.lang.String name)
                 throws MxException
Sets the port name on the device. This name is the same as the friendly name used by Windows (supported devices: UPort 1200/1400/1600 series).

Parameters:
string - [in] Specifies the name of this port. The maximum length is 20 bytes. Give an empty string to erase it. A null string will cause an exception.
Throws:
MxException - If an error occurs.

setRTS

void setRTS(int mode)
            throws MxException
Sets the RTS state for a serial port.

Parameters:
mode - [in] for RTS settings; is either RTS_ON or RTS_OFF.
Throws:
MxException - If an error occurs.

setUsbReadTimeout

void setUsbReadTimeout(int time)
                       throws MxException
Sets the read timeout value for a USB read request. The default value is 2000 milliseconds.

Parameters:
time - [in] The timeout value in milliseconds.
Throws:
MxException - If an error occurs.

setUsbWriteTimeout

void setUsbWriteTimeout(int time)
                        throws MxException
Sets the write timeout value for a USB write request. The default value is 2000 milliseconds.

Parameters:
time - [in] The timeout value in milliseconds.
Throws:
MxException - If an error occurs.

write

int write(byte[] buffer)
          throws MxException
Puts a block of data to the driver's output buffer. The actual length of data written depends on the amount of free space in the driver's output buffer. The write() returns when all data in the buffer has been sent.

Parameters:
buffer - [in] The buffer contains all data to send.
Returns:
The actual data written to the device.
Throws:
MxException - If an error occurs.

write

int write(byte[] buffer,
          int length)
          throws MxException
Puts a block of data to the driver's output buffer. The actual length of data written depends on the amount of free space in the driver's output buffer. The write() returns when the given length of data in the buffer has been sent.

Parameters:
buffer - [in] The buffer that contains data to send.
length - [in] The length of data to send.
Returns:
The actual data written to the device.
Throws:
MxException - If an error occurs.

write

int write(byte[] buffer,
          int length,
          int timeout)
          throws MxException
Puts a block of data to the driver's output buffer. The actual length of data written depends on the amount of free space in the driver's output buffer. The write() returns when the given length of data in the buffer has been sent. Otherwise, if a timeout occurs the write() returns the transmitted length of data. The caller should handle transmitting the other data.

Parameters:
buffer - [in] The buffer that contains data to send.
length - [in] The length of data to send.
timeout - [in] The timeout value to receive data.
-
Returns:
The actual data written to the device.
Throws:
MxException - If an error occurs.