com.embeddedunveiled.serial.vendor

Class SerialComSLabsUSBXpress

java.lang.Object

com.embeddedunveiled.serial.vendor.SerialComVendorLib

com.embeddedunveiled.serial.vendor.SerialComSLabsUSBXpress

public final class SerialComSLabsUSBXpress
extends SerialComVendorLib

Silicon labs provides libraries to communicate with their USB-UART devices. More information can be found here : http://www.silabs.com/products/mcu/Pages/USBXpress.aspx

[0] The data types used in java layer may be bigger in size than the native layer. For example; if native function returns 16 bit signed integer, than java method will return 32 bit integer. This is done to make sure that no data loss occur. This library take care of sign and their applicability internally.

[1] Developers are requested to check with vendor library documentation if a particular function is supported for desired platform or not and also how does a particular API will behave. Also consider paying attention to valid values and range when passing arguments to a method.

[2] The application note for USBXpress library is here : http://www.silabs.com/Support%20Documents/TechnicalDocs/an169.pdf

[3] It seems like USBXpress library uses user space drivers. So if you encounter any problems with permissions add the following udev rules file at appropriate location in your system : https://github.com/RishiGupta12/serial-communication-manager/blob/master/tools-and-utilities/99-scm-cp210x.rules

SCM version 1.0.4 is linked to v4.0 version of USBXpress from silicon labs.

Author:

Rishi Gupta

Field Summary

Fields

Modifier and Type	Field and Description
static int	SI_FIRMWARE_CONTROLLED
static int	SI_HANDSHAKE_LINE
static int	SI_HELD_ACTIVE
static int	SI_HELD_INACTIVE
static int	SI_RECEIVE_FLOW_CONTROL
static int	SI_RETURN_DESCRIPTION
static int	SI_RETURN_LINK_NAME
static int	SI_RETURN_PID
static int	SI_RETURN_SERIAL_NUMBER
static int	SI_RETURN_VID
static int	SI_RX_EMPTY
static int	SI_RX_NO_OVERRUN
static int	SI_RX_OVERRUN
static int	SI_RX_READY
static int	SI_STATUS_INPUT
static int	SI_TRANSMIT_ACTIVE_SIGNAL

Fields inherited from class com.embeddedunveiled.serial.vendor.SerialComVendorLib

VLIB_FTDI_D2XX, VLIB_MCHP_SIMPLEIO, VLIB_SLABS_CP210XMANUFACTURING, VLIB_SLABS_CP210XRUNTIME, VLIB_SLABS_USBXPRESS

Constructor Summary

Constructors

Constructor and Description
SerialComSLabsUSBXpress(File libDirectory, String vlibName, int cpuArch, int osType, SerialComSystemProperty serialComSystemProperty) Allocates a new SerialComSLabsUSBXpress object and extract and load shared libraries as required.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancelIO(long handle) Executes SI_CancelIo function of USBXpress library.
long[]	checkRXQueue(long handle) Executes SI_CheckRXQueue function of USBXpress library.
boolean	close(long handle) Executes SI_Close function of USBXpress library.
int	deviceIOControl(long handle, int ctrlCode, byte[] inputBuf, int numBytesToRead, byte[] outputBuf, int numOfBytesToWrite) Executes SI_DeviceIOControl function of USBXpress library.
boolean	flushBuffer(long handle, byte flushTransmit, byte flushReceive) Executes SI_FlushBuffers function of USBXpress library.
long	getDllVersion(long handle) Executes SI_GetDLLVersion function of USBXpress library.
long	getDriverVersion(long handle) Executes SI_GetDriverVersion function of USBXpress library.
byte	getModemStatus(long handle) Executes SI_GetModemStatus function of USBXpress library.
int	getNumDevices() Executes SI_GetNumDevices function of USBXpress library.
String	getPartNumber(long handle) Executes SI_GetPartNumber function of USBXpress library.
String	getProductString(int index, int flag) Executes SI_GetProductString function of USBXpress library.
long[]	getTimeouts(long handle, long readTimeOut, long writeTimeOut) Executes SI_GetTimeouts function of USBXpress library.
long	open(int index) Executes SI_Open function of USBXpress library.
int	read(long handle, byte[] buffer, int numOfBytesToRead) Executes SI_Read function of USBXpress library.
long	readLatch(long handle) Executes SI_ReadLatch function of USBXpress library.
boolean	setBaudDivisor(long handle, int divisor) Executes SI_SetBaudDivisor function of USBXpress library.
boolean	setBaudRate(long handle, int baudrate) Executes SI_SetBaudRate function of USBXpress library.
boolean	setBreak(long handle, int breakValue) Executes SI_SetBreak function of USBXpress library.
boolean	setFlowControl(long handle, int ctsMaskCode, int rtsMaskCode, int dtrMaskCode, int dsrMaskCode, int dcdMaskCode, int flowXonXoff) Executes SI_SetFlowControl function of USBXpress library.
boolean	setLineControl(long handle, int lineControl) Executes SI_SetLineControl function of USBXpress library.
boolean	setTimeouts(long handle, long readTimeOut, long writeTimeOut) Executes SI_SetTimeouts function of USBXpress library.
int	write(long handle, byte[] buffer, int numOfBytesToWrite) Executes SI_Write function of USBXpress library.
boolean	writeLatch(long handle, long mask, long latchValue) Executes SI_WriteLatch function of USBXpress library.

Methods inherited from class com.embeddedunveiled.serial.vendor.SerialComVendorLib

getVendorLibInstance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SI_RETURN_SERIAL_NUMBER

public static final int SI_RETURN_SERIAL_NUMBER

See Also:

Constant Field Values

SI_RETURN_DESCRIPTION

public static final int SI_RETURN_DESCRIPTION

See Also:

Constant Field Values

SI_RETURN_LINK_NAME

public static final int SI_RETURN_LINK_NAME

See Also:

Constant Field Values

SI_RETURN_VID

public static final int SI_RETURN_VID

See Also:

Constant Field Values

SI_RETURN_PID

public static final int SI_RETURN_PID

See Also:

Constant Field Values

SI_RX_NO_OVERRUN

public static final int SI_RX_NO_OVERRUN

See Also:

Constant Field Values

SI_RX_EMPTY

public static final int SI_RX_EMPTY

See Also:

Constant Field Values

SI_RX_OVERRUN

public static final int SI_RX_OVERRUN

See Also:

Constant Field Values

SI_RX_READY

public static final int SI_RX_READY

See Also:

Constant Field Values

SI_HELD_INACTIVE

public static final int SI_HELD_INACTIVE

See Also:

Constant Field Values

SI_HELD_ACTIVE

public static final int SI_HELD_ACTIVE

See Also:

Constant Field Values

SI_FIRMWARE_CONTROLLED

public static final int SI_FIRMWARE_CONTROLLED

See Also:

Constant Field Values

SI_RECEIVE_FLOW_CONTROL

public static final int SI_RECEIVE_FLOW_CONTROL

See Also:

Constant Field Values

SI_TRANSMIT_ACTIVE_SIGNAL

public static final int SI_TRANSMIT_ACTIVE_SIGNAL

See Also:

Constant Field Values

SI_STATUS_INPUT

public static final int SI_STATUS_INPUT

See Also:

Constant Field Values

SI_HANDSHAKE_LINE

public static final int SI_HANDSHAKE_LINE

See Also:

Constant Field Values

Constructor Detail

SerialComSLabsUSBXpress

public SerialComSLabsUSBXpress(File libDirectory,
                       String vlibName,
                       int cpuArch,
                       int osType,
                       SerialComSystemProperty serialComSystemProperty)
                        throws UnsatisfiedLinkError,
                               SerialComLoadException,
                               SerialComUnexpectedException,
                               SecurityException,
                               FileNotFoundException

Allocates a new SerialComSLabsUSBXpress object and extract and load shared libraries as required.

Parameters:

libDirectory - directory in which native library will be extracted and vendor library will be found.

vlibName - name of vendor library to load and link.

cpuArch - architecture of CPU this library is running on.

osType - operating system this library is running on.

serialComSystemProperty - instance of SerialComSystemProperty to get required java properties.

Throws:

SerialComUnexpectedException - if a critical java system property is null in system.

SecurityException - if any java system property can not be accessed.

FileNotFoundException - if the vendor library file is not found.

SerialComLoadException - if any file system related issue occurs.

UnsatisfiedLinkError - if loading/linking shared library fails.

SerialComException - if initializing native library fails.

Method Detail

getNumDevices

public int getNumDevices()
                  throws SerialComException

Executes SI_GetNumDevices function of USBXpress library.

Returns the number of devices connected to the host.

Returns:

number of the devices connected to host presently.

Throws:

SerialComException - if an I/O error occurs.

getProductString

public String getProductString(int index,
                      int flag)
                        throws SerialComException

Executes SI_GetProductString function of USBXpress library.

Returns product description, serial number, vid, pid or full path based on flag passed.

The argument flag can be one of the constant SI_RETURN_SERIAL_NUMBER, SI_RETURN_DESCRIPTION, SI_RETURN_LINK_NAME, SI_RETURN_VID and SI_RETURN_PID.

Parameters:

index - index of device in list.

flag - indicates which property is to be fetched.

Returns:

product description, serial number or full path.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if invalid flag is passed.

open

public long open(int index)
          throws SerialComException

Executes SI_Open function of USBXpress library.

Open the device and return a handle which will be used for subsequent accesses.

Parameters:

index - of the device that needs to be opened.

Returns:

handle of the opened device or -1 if method fails.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if index is negative.

close

public boolean close(long handle)
              throws SerialComException

Executes SI_Close function of USBXpress library.

Closes an opened device.

Parameters:

handle - of the device that is to be close.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

read

public int read(long handle,
       byte[] buffer,
       int numOfBytesToRead)
         throws SerialComException

Executes SI_Read function of USBXpress library.

Read data from the device.

Parameters:

handle - handle of the device from which to read data.

buffer - byte buffer where data read will be placed.

numOfBytesToRead - number of bytes to be tried to read.

Returns:

number of bytes read.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if buffer is null or numOfBytesToRead is negative or zero.

write

public int write(long handle,
        byte[] buffer,
        int numOfBytesToWrite)
          throws SerialComException

Executes SI_Write function of USBXpress library.

Write data from given buffer to the device.

Parameters:

handle - handle of the device to which data is to be sent.

buffer - byte buffer that contains the data to be written to the device.

numOfBytesToWrite - Number of bytes to write to the device.

Returns:

number of bytes written to the device.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if buffer is null or numOfBytesToWrite is negative or zero.

cancelIO

public boolean cancelIO(long handle)
                 throws SerialComException

Executes SI_CancelIo function of USBXpress library.

Cancels any pending IO on a device opened with an OVERLAPPED object.

Parameters:

handle - handle of the device whose pending IO operations are to be cancelled.

Returns:

true if the operation executed successfully.

Throws:

SerialComException - if an I/O error occurs.

flushBuffer

public boolean flushBuffer(long handle,
                  byte flushTransmit,
                  byte flushReceive)
                    throws SerialComException

Executes SI_FlushBuffers function of USBXpress library.

Flushes buffers of device or drivers as requested through additional arguments.

Parameters:

handle - of the device whose buffer is to be flushed.

flushTransmit - indicates whether transmit buffer is to be flushed or not.

flushReceive - indicates whether receive buffer is to be flushed or not.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

setTimeouts

public boolean setTimeouts(long handle,
                  long readTimeOut,
                  long writeTimeOut)
                    throws SerialComException

Executes SI_SetTimeouts function of USBXpress library.

Sets the read and write time out values for the given device.

Parameters:

handle - handle of the device whose timeout values need to be set.

readTimeOut - read time out in milliseconds.

writeTimeOut - write time out in milliseconds.

Returns:

true if the operation executed successfully.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if divisor is negative.

getTimeouts

public long[] getTimeouts(long handle,
                 long readTimeOut,
                 long writeTimeOut)
                   throws SerialComException

Executes SI_GetTimeouts function of USBXpress library.

Gets the current read and write time out values for the given device.

Parameters:

handle - handle of the device whose timeout values need to be fetched.

Returns:

array of timeout in sequence of read timeout and write out at index 0 and 1 respectively.

Throws:

SerialComException - if an I/O error occurs.

checkRXQueue

public long[] checkRXQueue(long handle)
                    throws SerialComException

Executes SI_CheckRXQueue function of USBXpress library.

Returns the number of bytes in the receive queue and a status value that indicates if an overrun (SI_QUEUE_OVERRUN) has occurred and if the RX queue is ready (SI_QUEUE_READY) for reading. The application can compare return value with constant SI_RX_XXXXX defined in this class.

Parameters:

handle - handle of the device whose status need to be fetched.

Returns:

array containing number of bytes and flag at index 0 and 1 respectively.

Throws:

SerialComException - if an I/O error occurs.

setBaudRate

public boolean setBaudRate(long handle,
                  int baudrate)
                    throws SerialComException

Executes SI_SetBaudRate function of USBXpress library.

Sets the Baud Rate. Refer to the device data sheet for a list of Baud Rates supported by the device.

Parameters:

handle - of the device whose baud rate is to be set.

baudrate - baud rate value to set.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

setBaudDivisor

public boolean setBaudDivisor(long handle,
                     int divisor)
                       throws SerialComException

Executes SI_SetBaudDivisor function of USBXpress library.

Sets the Baud Rate directly by using a specific divisor value. This function is obsolete; use SI_SetBaudRate instead.

Parameters:

handle - of the device whose baud rate is to be set.

divisor - divisor value to set.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

setLineControl

public boolean setLineControl(long handle,
                     int lineControl)
                       throws SerialComException

Executes SI_SetLineControl function of USBXpress library.

Adjusts the line control settings: word length, stop bits, and parity. Refer to the device data sheet for valid line control settings.

Parameters:

handle - of the device whose baud control settings is to be set.

lineControl - bit mask of line control settings.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

setFlowControl

public boolean setFlowControl(long handle,
                     int ctsMaskCode,
                     int rtsMaskCode,
                     int dtrMaskCode,
                     int dsrMaskCode,
                     int dcdMaskCode,
                     int flowXonXoff)
                       throws SerialComException

Executes SI_SetFlowControl function of USBXpress library.

Adjusts the following flow control settings: set hardware handshaking, software handshaking, and modem control signals.

Parameters:

handle - of the device whose flow control settings is to be set.

ctsMaskCode - can be SI_STATUS_INPUT or SI_HANDSHAKE_LINE.

rtsMaskCode - can be SI_HELD_INACTIVE, SI_HELD_ACTIVE, SI_FIRMWARE_CONTROLLED or SI_TRANSMIT_ACTIVE_SIGNAL.

dtrMaskCode - can be SI_HELD_INACTIVE, SI_HELD_ACTIVE or SI_FIRMWARE_CONTROLLED.

dsrMaskCode - can be SI_STATUS_INPUT or SI_HANDSHAKE_LINE.

dcdMaskCode - can be SI_STATUS_INPUT or SI_HANDSHAKE_LINE.

flowXonXoff - Sets software flow control to be off if the value is 0, and on using the character value specified if value is non-zero.

Returns:

true on success.

Throws:

SerialComException - if an I/O error occurs.

getModemStatus

public byte getModemStatus(long handle)
                    throws SerialComException

Executes SI_GetModemStatus function of USBXpress library.

Gets the Modem Status from the device. This includes the modem pin states.

Parameters:

handle - of the device whose modem status is to be fetched.

Returns:

modem status in following sequence DTR status bit 0, RTS status bit 1, CTS state bit 4, DSR state bit 5, RI state bit 6 and DCD state bit 7.

Throws:

SerialComException - if an I/O error occurs.

setBreak

public boolean setBreak(long handle,
               int breakValue)
                 throws SerialComException

Executes SI_SetBreak function of USBXpress library.

Sends a break state (transmit or reset) to a CP210x device. Note that this function is not necessarily synchronized with queued transmit data.

Parameters:

handle - of the device for whom break condition is to be set as given.

breakValue - break is reset of this is 0x0000 and break is transmitted if this is 0x0001.

Returns:

true if break condition set as given.

Throws:

SerialComException - if an I/O error occurs.

readLatch

public long readLatch(long handle)
               throws SerialComException

Executes SI_ReadLatch function of USBXpress library.

Gets the current port latch value (least significant four bits) from the device.

Parameters:

handle - handle of the opened COM port.

Returns:

GPIO latch value [Logic High = 1, Logic Low = 0].

Throws:

SerialComException - if an I/O error occurs.

writeLatch

public boolean writeLatch(long handle,
                 long mask,
                 long latchValue)
                   throws SerialComException

Executes SI_WriteLatch function of USBXpress library.

Sets the current port latch value (least significant four bits) from the device.

Parameters:

handle - handle of the opened COM port.

mask - determines which pins to change [Change = 1, Leave = 0].

latchValue - value to write to GPIO latch [Logic High = 1, Logic Low = 0].

Returns:

true if value gets set successfully.

Throws:

SerialComException - if an I/O error occurs.

getPartNumber

public String getPartNumber(long handle)
                     throws SerialComException

Executes SI_GetPartNumber function of USBXpress library.

Retrieves the part number of the CP210x device for a given handle.

Parameters:

handle - handle of the device for whose part number is to found.

Returns:

part number associated with the given handle.

Throws:

SerialComException - if an I/O error occurs.

deviceIOControl

public int deviceIOControl(long handle,
                  int ctrlCode,
                  byte[] inputBuf,
                  int numBytesToRead,
                  byte[] outputBuf,
                  int numOfBytesToWrite)
                    throws SerialComException

Executes SI_DeviceIOControl function of USBXpress library.

Interface for any miscellaneous device control functions. A separate call to SI_DeviceIOControl is required for each input or output operation. A single call cannot be used to perform both an input and output operation simultaneously.

Parameters:

handle - handle of the device for whom IO control operation is to be performed.

inputBuf - buffer in which data bytes will be saved.

numBytesToRead - number of bytes to read from port and place in input buffer.

outputBuf - buffer which contains data to be written to serial port.

numOfBytesToWrite - number of data bytes to write to port.

Returns:

number of bytes read if operation was read, number of written if operation was to write data.

Throws:

SerialComException - if an I/O error occurs.

getDllVersion

public long getDllVersion(long handle)
                   throws SerialComException

Executes SI_GetDLLVersion function of USBXpress library.

Obtains the version of the DLL that is currently in use.

Parameters:

handle - handle of the device for whose dll version is to found.

Returns:

driver version number for the requested device handle.

Throws:

SerialComException - if an I/O error occurs.

getDriverVersion

public long getDriverVersion(long handle)
                      throws SerialComException

Executes SI_GetDriverVersion function of USBXpress library.

Obtains the version of the Driver that is currently in the Windows System directory.

Parameters:

handle - handle of the device for whom driver version is to found.

Returns:

driver version number for the requested device handle.

Throws:

SerialComException - if an I/O error occurs.