com.serialpundit.usb

Class SerialComUSB

java.lang.Object

com.serialpundit.usb.SerialComUSB

public final class SerialComUSB
extends Object

Encapsulates USB related operations and values.

An end product may be based on dedicated USB-UART bridge IC for providing serial over USB or may use general purpose microcontroller like PIC18F4550 from Microchip technology Inc. and program appropriate firmware (USB CDC) into it to provide UART communication over USB port.

[1] If your USB-UART converter based design is not working, consider not connecting USB connector shield directly to ground. Further, double check if termination resistors in D+/D- lines are really required or not.

Author:

Rishi Gupta

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEV_ADDED The value indicating that a USB device has been added into system.
static int	DEV_ANY The value indicating that the USB device can have any vendor id and product id.
static int	DEV_REMOVED The value indicating that a USB device has been removed from system.
static int	V_ALL Value indicating all vendors (vendor neutral operation).
static int	V_ATML Value indicating vendor - Atmel corporation.
static int	V_CYPRS Value indicating vendor - Cypress semiconductor corporation.
static int	V_EXAR Value indicating vendor - Exar corporation.
static int	V_FTDI Value indicating vendor - Future technology devices international, Ltd.
static int	V_MCHIP Value indicating vendor - Microchip technology Inc.
static int	V_MOSCHP Value indicating vendor - MosChip semiconductor.
static int	V_NXP Value indicating vendor - NXP semiconductors.
static int	V_PL Value indicating vendor - Prolific technology Inc.
static int	V_QHE Value indicating vendor - QinHeng electronics.
static int	V_RNSAS Value indicating vendor - Renesas electronics (NEC electronics).
static int	V_SLABS Value indicating vendor - Silicon Laboratories.
static int	V_TI Value indicating vendor - Texas instruments, Inc.
static int	V_WCH Value indicating vendor - WinChipHead.

Constructor Summary

Constructors

Constructor and Description
SerialComUSB(String libDirectory, String loadedLibName) Allocates a new SerialComUSB object and load/link native libraries if required.

Method Summary

Methods

Modifier and Type	Method and Description
String[]	findComPortFromUSBAttributes(int usbVidToMatch, int usbPidToMatch, String serialNumber) Gives COM port (COMxx/ttySx) of a connected USB-UART device (CDC/ACM Interface) assigned by operating system.
SerialComUSBPowerInfo	getCDCUSBDevPowerInfo(String comPort) Read all the power management related information about a particular USB device.
String[]	getFirmwareRevisionNumber(int usbvid, int usbpid, String serialNumber) Gets the USB device firmware revision number as reported by USB device descriptor in its device descriptor using bcdDevice field.
int	getLatencyTimer(String comPort) Gets the current latency timer value for FTDI devices.
SerialComUSBHID	getUSBHIDTransportInstance() Returns an instance of class SerialComUSBHID for HID over USB operations.
boolean	isUSBDevConnected(int vendorID, int productID, String serialNumber) Checks whether a particular USB device identified by vendor id, product id and serial number is connected to the system or not.
SerialComUSBdevice[]	listUSBdevicesWithInfo(int vendorFilter) Returns an array of SerialComUSBdevice class objects containing information about all the USB devices found by this library.
int	registerUSBHotPlugEventListener(ISerialComUSBHotPlugListener hotPlugListener, int filterVID, int filterPID, String serialNumber) This registers a listener who will be invoked whenever a USB device has been plugged or un-plugged in system.
boolean	setLatencyTimer(String comPort, byte timerValue) Sets the latency timer value for FTDI devices.
boolean	unregisterUSBHotPlugEventListener(int opaqueHandle) This unregisters listener and terminate native thread used for monitoring specified USB device insertion or removal.

Methods inherited from class java.lang.Object

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

Field Detail

V_ALL

public static final int V_ALL

Value indicating all vendors (vendor neutral operation).

See Also:

Constant Field Values

V_FTDI

public static final int V_FTDI

Value indicating vendor - Future technology devices international, Ltd. It manufactures FT232 USB-UART bridge IC.

See Also:

Constant Field Values

V_SLABS

public static final int V_SLABS

Value indicating vendor - Silicon Laboratories. It manufactures CP2102 USB-UART bridge IC.

See Also:

Constant Field Values

V_MCHIP

public static final int V_MCHIP

Value indicating vendor - Microchip technology Inc. It manufactures MCP2200 USB-UART bridge IC.

See Also:

Constant Field Values

V_PL

public static final int V_PL

Value indicating vendor - Prolific technology Inc. It manufactures PL2303 USB-UART bridge IC.

See Also:

Constant Field Values

V_EXAR

public static final int V_EXAR

Value indicating vendor - Exar corporation. It manufactures XR21V1410 USB-UART bridge IC.

See Also:

Constant Field Values

V_ATML

public static final int V_ATML

Value indicating vendor - Atmel corporation. It manufactures AT90USxxx and other processors which can be used as USB-UART bridge.

See Also:

Constant Field Values

V_MOSCHP

public static final int V_MOSCHP

Value indicating vendor - MosChip semiconductor. It manufactures MCS7810 USB-UART bridge IC.

See Also:

Constant Field Values

V_CYPRS

public static final int V_CYPRS

Value indicating vendor - Cypress semiconductor corporation. It manufactures CY7C65213 USB-UART bridge IC.

See Also:

Constant Field Values

V_TI

public static final int V_TI

Value indicating vendor - Texas instruments, Inc. It manufactures TUSB3410 USB-UART bridge IC.

See Also:

Constant Field Values

V_WCH

public static final int V_WCH

Value indicating vendor - WinChipHead. It manufactures CH340 USB-UART bridge IC.

See Also:

Constant Field Values

V_QHE

public static final int V_QHE

Value indicating vendor - QinHeng electronics. It manufactures HL-340 converter product.

See Also:

Constant Field Values

V_NXP

public static final int V_NXP

Value indicating vendor - NXP semiconductors. It manufactures LPC134x series of microcontrollers.

See Also:

Constant Field Values

V_RNSAS

public static final int V_RNSAS

Value indicating vendor - Renesas electronics (NEC electronics). It manufactures μPD78F0730 microcontroller which can be used as USB-UART converter.

See Also:

Constant Field Values

DEV_ANY

public static final int DEV_ANY

The value indicating that the USB device can have any vendor id and product id.

See Also:

Constant Field Values

DEV_ADDED

public static final int DEV_ADDED

The value indicating that a USB device has been added into system.

See Also:

Constant Field Values

DEV_REMOVED

public static final int DEV_REMOVED

The value indicating that a USB device has been removed from system.

See Also:

Constant Field Values

Constructor Detail

SerialComUSB

public SerialComUSB(String libDirectory,
            String loadedLibName)
             throws IOException

Allocates a new SerialComUSB object and load/link native libraries if required.

Parameters:

libDirectory - absolute path of directory to be used for native library extraction.

loadedLibName - library name without extension (do not append .so, .dll or .dylib etc.).

Throws:

IOException - if native libraries are not found or can not be loaded/linked. If appropriate files/directories can not be read or written, If native library can not be initialized.

Method Detail

listUSBdevicesWithInfo

public SerialComUSBdevice[] listUSBdevicesWithInfo(int vendorFilter)
                                            throws com.serialpundit.core.SerialComException

Returns an array of SerialComUSBdevice class objects containing information about all the USB devices found by this library. Application can call various methods on SerialComUSBdevice object to get specific information like vendor id and product id etc. The GUI applications may display a dialogue box asking user to connect the end product if the desired product is still not connected to system.

The USB vendor id, USB product id, serial number, product name and manufacturer information is encapsulated in the object of class SerialComUSBdevice returned.

Some USB-UART chip manufactures may give some unique USB PID(s) to end product manufactures at minimal or no cost. Applications written for these end products may be interested in finding devices only from the USB-UART chip manufacturer. For example, an application built for finger print scanner based on FT232 IC will like to list only those devices whose VID matches VID of FTDI. Then further application may verify PID by calling methods on the USBDevice object. For this purpose argument vendorFilter may be used.

Parameters:

vendorFilter - vendor whose devices should be listed (one of the constants SerialComUSB.V_xxxxx or any valid USB VID).

Returns:

list of the USB devices with information about them or empty array if no device matching given criteria found.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if vendorFilter is negative or invalid number.

registerUSBHotPlugEventListener

public int registerUSBHotPlugEventListener(ISerialComUSBHotPlugListener hotPlugListener,
                                  int filterVID,
                                  int filterPID,
                                  String serialNumber)
                                    throws com.serialpundit.core.SerialComException

This registers a listener who will be invoked whenever a USB device has been plugged or un-plugged in system. This method can be used to write auto discovery applications for example when a hardware USB device is added to system, application can automatically detect, identify it and launches an appropriate service.

This API can be used for detecting both USB-HID and USB-CDC devices. Essentially this API is USB interface agnostic; meaning it would invoke listener for matching USB device irresepective of functionality offered by the USB device.

Application must implement ISerialComUSBHotPlugListener interface and override onUSBHotPlugEvent method. The event value SerialComUSB.DEV_ADDED indicates USB device has been added to the system. The event value SerialComUSB.DEV_REMOVED indicates USB device has been removed from system.

Application can specify the usb device for which callback should be called based on USB VID and USB PID. If the value of filterVID is specified however the value of filterPID is constant SerialComUSB.DEV_ANY, then callback will be called for USB device which matches given VID and its PID can have any value. If the value of filterPID is specified however the value of filterVID is constant SerialComUSB.DEV_ANY, then callback will be called for USB device which matches given PID and its VID can have any value.

If both filterVID and filterPID are set to SerialComUSB.DEV_ANY, then callback will be called for every USB device. Further in listener, USBVID will be 0, if SerialComUSB.DEV_ANY was passed to registerUSBHotPlugEventListener for filterVID argument. USBPID will be 0, if SerialComUSB.DEV_ANY was passed to registerUSBHotPlugEventListener for filterPID and serialNumber will be empty string if null was passed to registerUSBHotPlugEventListener for serialNumber argument.

If the application do not know the USB attributes like the VID/PID/Serial of the device use listUSBdevicesWithInfo() along with hot plug listener. For example; call listUSBdevicesWithInfo(SerialComUSB.V_ALL) and create and arraylist to know what all USB devices are present in system and register this hotplug listener. Now whenever a USB device is attached to system, listener will be called. From with this listener call listUSBdevicesWithInfo(SerialComUSB.V_ALL) and create arraylist again. Compare these two list to find information about newly added device and take next appropriate step

Parameters:

hotPlugListener - object of class which implements ISerialComUSBHotPlugListener interface.

filterVID - USB vendor ID to match.

filterPID - USB product ID to match.

serialNumber - serial number of USB device (case insensitive, optional, can be null) to match.

Returns:

opaque handle on success that should be passed to unregisterUSBHotPlugEventListener method for unregistering this listener.

Throws:

com.serialpundit.core.SerialComException - if registration fails due to some reason.

IllegalArgumentException - if hotPlugListener is null or if USB VID or USB PID are invalid numbers.

unregisterUSBHotPlugEventListener

public boolean unregisterUSBHotPlugEventListener(int opaqueHandle)
                                          throws com.serialpundit.core.SerialComException

This unregisters listener and terminate native thread used for monitoring specified USB device insertion or removal.

Parameters:

opaqueHandle - handle returned by registerUSBHotPlugEventListener method for this listener.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if un-registration fails due to some reason.

IllegalArgumentException - if argument opaqueHandle is negative.

findComPortFromUSBAttributes

public String[] findComPortFromUSBAttributes(int usbVidToMatch,
                                    int usbPidToMatch,
                                    String serialNumber)
                                      throws com.serialpundit.core.SerialComException

Gives COM port (COMxx/ttySx) of a connected USB-UART device (CDC/ACM Interface) assigned by operating system.

Assume a bar code scanner using FTDI chip FT232R is to be used by application at point of sale. First we need to know whether it is connect to system or not. This can be done using listUSBdevicesWithInfo() or by using USB hot plug listener depending upon application design.

Once it is known that the device is connected to system, we application need to open it. For this, application needs to know the COM port number or device node corresponding to the scanner. It is for this purpose this method can be used.

Another use case of this API is to align application design with true spirit of USB hot plugging in operating system. When a USB-UART device is connected, OS may assign different COM port number or device node to the same device depending upon system scenario. Generally we need to write custom udev rules so that device node will be same. Using this API this limitation can be overcome.

The reason why this method returns array instead of string is that two or more USB-UART converters connected to system might have exactly same USB attributes. So this will list COM ports assigned to all of them.

Parameters:

usbVidToMatch - USB vendor id of the device to match.

usbPidToMatch - USB product id of the device to match.

serialNumber - USB serial number (case insensitive, optional) of device to match or null if not to be matched.

Returns:

list of COM port(s) (device node) for given USB device or empty array if no COM port is assigned.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if usbVidToMatch or usbPidToMatch is negative or or invalid number.

getFirmwareRevisionNumber

public String[] getFirmwareRevisionNumber(int usbvid,
                                 int usbpid,
                                 String serialNumber)
                                   throws com.serialpundit.core.SerialComException

Gets the USB device firmware revision number as reported by USB device descriptor in its device descriptor using bcdDevice field.

Application can get this firmware revision number and can self adopt to a particular hardware device. For example if a particular feature is present in firmware version 1.00 than application create a button in GUI, however for revision 1.11 it creates a different button in GUI window.

Embedded system device vendors sometimes use bcdDevice value to indicate the 'embedded bootloader' version so that the firmware image flash loader program can identify the bootloader in use and use the appropriate protocol to flash firmware in flash memory. Typically, USB Device Firmware Upgrade (DFU) which is an official USB device class specification of the USB Implementers Forum is used.

On custom hardware the RTS and DTR pins of USB-UART device can be used to control GPIO or boot mode pins to enter a particular boot mode. For example, open the host serial port, make DTR low and RTS high and then reset microcontroller board. The microcontroller will see levels at its boot pins and will enter into a particular boot mode.

Parameters:

usbvid - USB vendor ID to match.

usbpid - USB product ID to match.

serialNumber - serial number of USB device (case insensitive, optional) to match.

Returns:

firmware number revision string on success.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

getCDCUSBDevPowerInfo

public SerialComUSBPowerInfo getCDCUSBDevPowerInfo(String comPort)
                                            throws com.serialpundit.core.SerialComException

Read all the power management related information about a particular USB device. The returned instance of SerialComUSBPowerInfo class contains information about auto suspend, selective suspend, current power status etc.

Parameters:

comPort - serial port name/path (COMxx, /dev/ttyUSBx) which is associated with a particular USB CDC/ACM interface in the USB device to be analyzed for power management.

Returns:

an instance of SerialComUSBPowerInfo class containing operating system and device specific information about power management or null if given COM port does not belong to a USB device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

setLatencyTimer

public boolean setLatencyTimer(String comPort,
                      byte timerValue)
                        throws com.serialpundit.core.SerialComException

Sets the latency timer value for FTDI devices. When using FTDI USB-UART devices, optimal values of latency timer and read/write block size may be required to obtain optimal data throughput.

Note that built-in drivers in Linux kernel image may not allow changing timer values as it may have been hard-coded. Drivers supplied by FTDI at their website should be used if changing latency timer values is required by application.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

getLatencyTimer

public int getLatencyTimer(String comPort)
                    throws com.serialpundit.core.SerialComException

Gets the current latency timer value for FTDI devices.

Returns:

current latency timer value.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

isUSBDevConnected

public boolean isUSBDevConnected(int vendorID,
                        int productID,
                        String serialNumber)
                          throws com.serialpundit.core.SerialComException

Checks whether a particular USB device identified by vendor id, product id and serial number is connected to the system or not. The connection information is obtained from the operating system.

Parameters:

vendorID - USB-IF vendor ID of the USB device to match.

productID - product ID of the USB device to match.

serialNumber - USB device's serial number (case insensitive, optional). If not required it can be null.

Returns:

true is device is connected otherwise false.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if productID or vendorID is negative or invalid.

getUSBHIDTransportInstance

public SerialComUSBHID getUSBHIDTransportInstance()
                                           throws com.serialpundit.core.SerialComException

Returns an instance of class SerialComUSBHID for HID over USB operations.

Returns:

an instance of SerialComUSBHID.

Throws:

com.serialpundit.core.SerialComException - if operation can not be completed successfully.