com.serialpundit.serial.nullmodem

Class SerialComNullModem

java.lang.Object

com.serialpundit.serial.nullmodem.SerialComNullModem

public final class SerialComNullModem
extends Object

Provides APIs to create and destroy virtual serial ports using the tty2com null modem emulation driver provided by serialpundit. It follows the protocol as defined by tty2com driver.

Author:

Rishi Gupta

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEV_ADDED The value indicating that a virtual serial device has been added into system.
static int	DEV_REMOVED The value indicating that a virtual serial device has been removed from system.
static int	ERR_FRAME Bit mask bit specifying that a framing error should be emulated.
static int	ERR_OVERRUN Bit mask bit specifying that a overrun error should be emulated.
static int	ERR_PARITY Bit mask bit specifying that a parity error should be emulated.
static int	RCV_BREAK Bit mask bit specifying that a break condition reception should be emulated.
static int	SP_CON_CTS Bit mask bit specifying that the given pin should be connected to CTS pin of other end.
static int	SP_CON_DCD Bit mask bit specifying that the given pin should be connected to DCD pin of other end.
static int	SP_CON_DSR Bit mask bit specifying that the given pin should be connected to DSR pin of other end.
static int	SP_CON_NONE Bit mask bit specifying that the given pin should be left unconnected.
static int	SP_CON_RI Bit mask bit specifying that the given pin should be connected to RI pin of other end.

Constructor Summary

Constructors

Constructor and Description
SerialComNullModem(SerialComPortJNIBridge mComPortJNIBridge) Create an instance of SerialComNullModem with given details.

Method Summary

Methods

Modifier and Type	Method and Description
String[]	createCustomLoopBackDevice(int deviceIndex, int rtsMap, int dtrMap, boolean setDTRatOpen) Creates a virtual port/device connected in standard loopback fashion.
String[]	createCustomNullModemPair(int idx1, int rtsMap1, int dtrMap1, boolean setDTRatOpen1, int idx2, int rtsMap2, int dtrMap2, boolean setDTRatOpen2) Creates two virtual ports/devices connected in null modem fashion with given signal mappings.
String[]	createStandardLoopBackDevice(int deviceIndex) Creates a virtual port/device connected in standard loopback fashion.
String[]	createStandardNullModemPair(int deviceIndex1, int deviceIndex2) Creates two virtual ports/devices connected in standard null modem fashion.
void	deinitialize() Release resources if any was acquired and perform clean up tasks as required.
boolean	destroyAllCreatedLoopbackDevices() Removes all loop back virtual serial devices created by tty2com driver.
boolean	destroyAllCreatedNullModemPairs() Removes all null modem virtual serial devices created by tty2com driver.
boolean	destroyAllCreatedVirtualDevices() Removes all virtual serial devices created by tty2com driver.
boolean	destroyGivenVirtualDevice(String device) Removes the given virtual serial device created by tty2com driver.
void	emulateFaultyCable(String deviceNode, boolean state) Set/Unset faulty cable condition.
boolean	emulateLineRingingEvent(String devNode, boolean state) Emulate line ringing event on given device node.
boolean	emulateSerialEvent(String devNode, int error) Emulates the given line error/event (frame, parity, overrun or break) on given virtual device.
String[]	getLastLoopBackDeviceNode() Returns the device node of last created loop back device.
String[]	getLastNullModemPairNodes() Returns the device nodes of last created null modem pair.
String[]	getStatsForGivenDevice(String deviceNode) Gives operating system specific device stats at the instant this method is called like number of bytes transmitted, number of bytes received etc.
void	initialize() Allocate resources and initialize as required.
String[]	listAllExistingPorts() Gives names of all existing virtual serial ports created by driver.
String[]	listAllExistingPortsWithInfo() Gives all existing virtual serial ports created by null modem driver driver.
String[]	listExistingCustomLoopbackPorts() Gives all existing virtual serial ports which are connected in standard loopback fashion.
String[]	listExistingCustomNullModemPorts() Gives all existing virtual serial ports which are connected in custom null modem fashion.
String[]	listExistingStandardLoopbackPorts() Gives all existing ports which are connected in standard loopback fashion.
String[]	listExistingStandardNullModemPorts() Gives all existing virtual serial ports which are connected in standard null modem fashion.
String[]	listNextAvailablePorts() Gives the device node names that can be used to create next virtual serial port.
int	registerTTY2COMHotPlugEventListener(Itty2comHotPlugListener hotPlugListener, String deviceNode) This registers a listener who will be invoked whenever a virtual serial device has been plugged or un-plugged in system.
boolean	unregisterTTY2COMHotPlugEventListener(int opaqueHandle) This unregisters listener and terminate native thread used for monitoring virtual serial device insertion or removal.

Methods inherited from class java.lang.Object

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

Field Detail

SP_CON_NONE

public static final int SP_CON_NONE

Bit mask bit specifying that the given pin should be left unconnected.

Constant with value 0x0000.

See Also:

Constant Field Values

SP_CON_CTS

public static final int SP_CON_CTS

Bit mask bit specifying that the given pin should be connected to CTS pin of other end. Constant with value 0x0001.

See Also:

Constant Field Values

SP_CON_DCD

public static final int SP_CON_DCD

Bit mask bit specifying that the given pin should be connected to DCD pin of other end. Constant with value 0x0002.

See Also:

Constant Field Values

SP_CON_DSR

public static final int SP_CON_DSR

Bit mask bit specifying that the given pin should be connected to DSR pin of other end. Constant with value 0x0004.

See Also:

Constant Field Values

SP_CON_RI

public static final int SP_CON_RI

Bit mask bit specifying that the given pin should be connected to RI pin of other end. Constant with value 0x0008.

See Also:

Constant Field Values

ERR_FRAME

public static final int ERR_FRAME

Bit mask bit specifying that a framing error should be emulated.

Constant with value 0x0010.

See Also:

Constant Field Values

ERR_PARITY

public static final int ERR_PARITY

Bit mask bit specifying that a parity error should be emulated.

Constant with value 0x0020.

See Also:

Constant Field Values

ERR_OVERRUN

public static final int ERR_OVERRUN

Bit mask bit specifying that a overrun error should be emulated.

Constant with value 0x0040.

See Also:

Constant Field Values

RCV_BREAK

public static final int RCV_BREAK

Bit mask bit specifying that a break condition reception should be emulated.

Constant with value 0x0080.

See Also:

Constant Field Values

DEV_ADDED

public static final int DEV_ADDED

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

See Also:

Constant Field Values

DEV_REMOVED

public static final int DEV_REMOVED

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

See Also:

Constant Field Values

Constructor Detail

SerialComNullModem

public SerialComNullModem(SerialComPortJNIBridge mComPortJNIBridge)
                   throws com.serialpundit.core.SerialComException

Create an instance of SerialComNullModem with given details.

Parameters:

mComPortJNIBridge - native interface.

Throws:

com.serialpundit.core.SerialComException - if any exception occurs while preparing for communication using virtual device.

Method Detail

initialize

public void initialize()
                throws com.serialpundit.core.SerialComException

Allocate resources and initialize as required.

Throws:

com.serialpundit.core.SerialComException - if driver is not loaded or initialization fails.

deinitialize

public void deinitialize()
                  throws com.serialpundit.core.SerialComException

Release resources if any was acquired and perform clean up tasks as required. After calling this method if the null modem facilities is to be used again than call initialize method again.

Throws:

com.serialpundit.core.SerialComException - if the task fails.

listNextAvailablePorts

public String[] listNextAvailablePorts()
                                throws com.serialpundit.core.SerialComException

Gives the device node names that can be used to create next virtual serial port.

Returned array contains empty string if no more ports are free to be created.

Returns:

device node names (two strings) that can be used for next virtual serial port.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listExistingStandardNullModemPorts

public String[] listExistingStandardNullModemPorts()
                                            throws com.serialpundit.core.SerialComException

Gives all existing virtual serial ports which are connected in standard null modem fashion. In returned array, the port at even index is connected to the port at following odd index. For example :
String[] list = scnm.listExistingStandardNullModemPorts();
list[0] <-----> list[1]

Empty array is returned if no standard null modem pair is found.

Returns:

existing ports which are connected in standard null modem fashion.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listExistingCustomNullModemPorts

public String[] listExistingCustomNullModemPorts()
                                          throws com.serialpundit.core.SerialComException

Gives all existing virtual serial ports which are connected in custom null modem fashion. In returned array, the port at even index is connected to the port at following odd index. For example :
String[] list = scnm.listExistingCustomNullModemPorts();
list[0] <-----> list[4]

The sequence of information returned is shown below. The RTS and DTR mappings are returned in string form. The caller has to convert them into int data type and then constant bit mask SerialComNullModem.SP_CON_XXX can be used.
x + 0: 1st port's name/path
x + 1: 1st port's RTS mappings
x + 2: 1st port's DTR mappings
x + 3: 1st port's DTR state when opening port
x + 4: 2nd port's name/path
x + 5: 2nd port's RTS mappings
x + 6: 2nd port's DTR mappings
x + 7: 2nd port's DTR state when opening port

Empty array is returned if no custom null modem pair is found.

Returns:

existing ports which are connected in custom null modem fashion.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listExistingStandardLoopbackPorts

public String[] listExistingStandardLoopbackPorts()
                                           throws com.serialpundit.core.SerialComException

Gives all existing ports which are connected in standard loopback fashion.

Returns:

existing ports which are connected in standard loopback fashion.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listExistingCustomLoopbackPorts

public String[] listExistingCustomLoopbackPorts()
                                         throws com.serialpundit.core.SerialComException

Gives all existing virtual serial ports which are connected in standard loopback fashion.

The sequence of information returned is shown below. The RTS and DTR mappings are returned in string form. The caller has to convert them into int data type and then constant bit mask SerialComNullModem.SP_CON_XXX can be used.
x + 0: port's name
x + 1: port's RTS mappings
x + 2: port's DTR mappings
x + 3: port's DTR state when opening port

Empty array is returned if no custom loop back device is found.

Returns:

existing ports which are connected in custom null modem fashion.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listAllExistingPorts

public String[] listAllExistingPorts()
                              throws com.serialpundit.core.SerialComException

Gives names of all existing virtual serial ports created by driver.

Returns:

names of all existing virtual ports created by driver.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

listAllExistingPortsWithInfo

public String[] listAllExistingPortsWithInfo()
                                      throws com.serialpundit.core.SerialComException

Gives all existing virtual serial ports created by null modem driver driver.

The sequence of information returned is shown below. The RTS and DTR mappings are returned in string form. The caller has to convert them into int data type and then constant bit mask SerialComNullModem.SP_CON_XXX can be used.
x + 0: port's name
x + 1: port's RTS mappings
x + 2: port's DTR mappings
x + 3: port's DTR state when opening port

Empty array is returned if no devices are found.

Returns:

names of all existing virtual ports created by driver with their mappings.

Throws:

IOException - if the operation can not be completed for some reason.

com.serialpundit.core.SerialComException

createStandardNullModemPair

public String[] createStandardNullModemPair(int deviceIndex1,
                                   int deviceIndex2)
                                     throws com.serialpundit.core.SerialComException

Creates two virtual ports/devices connected in standard null modem fashion. If deviceIndex is -1, the next available index will be used by driver. If deviceIndex is a valid number, the given index will be used to create device nodes.

For example; createStandardNullModemPair(2, 3) will create /dev/tty2com2 and /dev/tty2com3 device nodes in Linux or will throw exception if any of the given number is already in use. Similarly the createStandardNullModemPair(-1, -1) will create /dev/tty2comXX and /dev/tty2comYY where XX/YY are the next free numbers managed by the driver internally.

Parameters:

deviceIndex1 - -1 or valid device number (0 <= deviceIndex1 =< 65535).

deviceIndex2 - -1 or valid device number (0 <= deviceIndex2 =< 65535).

Returns:

Created virtual null modem pair device's node on success.

Throws:

com.serialpundit.core.SerialComException - if virtual null modem device pair can not be created, IllegalArgumentException if deviceIndex1/2 is invalid.

createCustomNullModemPair

public String[] createCustomNullModemPair(int idx1,
                                 int rtsMap1,
                                 int dtrMap1,
                                 boolean setDTRatOpen1,
                                 int idx2,
                                 int rtsMap2,
                                 int dtrMap2,
                                 boolean setDTRatOpen2)
                                   throws com.serialpundit.core.SerialComException

Creates two virtual ports/devices connected in null modem fashion with given signal mappings. If idxYY is -1, the next available index will be used by driver. If idxYY is a valid number, the given index will be used to create device nodes.

For example; createCustomNullModemPair(2, 0, 0, 3, 0, 0) will create /dev/tty2com2 and the /dev/tty2com3 device nodes in Linux or will throw exception if any of the given number is already in use. Similarly the createCustomNullModemPair(-1, 0, 0, -1, 0, 0) will create /dev/tty2comXX and /dev/tty2comYY where XX/YY are the next free numbers managed by the driver internally.

To connect RTS pin to CTS pin use rtsMap = SerialComNullModem.SP_CON_CTS. A pin can be connected to one or more pins using bit mask. For example to connect RTS pin to CTS and DSR use rtsMap = SerialComNullModem.SP_CON_CTS | SerialComNullModem.SP_CON_DSR.

Parameters:

idx1 - -1 or valid device number (0 <= idx1 =< 65535).

rtsMap1 - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if RTS pin should be left unconnected.

dtrMap1 - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if DTR pin should be left unconnected.

setDTRatOpen1 - if true DTR will be asserted when serial port is opened otherwise it will not be raised.

idx2 - -1 or valid device number (0 <= idx2 =< 65535).

rtsMap2 - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if RTS pin should be left unconnected.

dtrMap2 - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if DTR pin should be left unconnected.

setDTRatOpen2 - if true DTR will be asserted when serial port is opened otherwise it will not be raised.

Returns:

Created virtual null modem pair device's node on success.

Throws:

com.serialpundit.core.SerialComException - if virtual null modem device pair can not be created, IllegalArgumentException if idx1/2 is invalid.

createStandardLoopBackDevice

public String[] createStandardLoopBackDevice(int deviceIndex)
                                      throws com.serialpundit.core.SerialComException

Creates a virtual port/device connected in standard loopback fashion. If deviceIndex is -1, the next available index will be used by driver. If deviceIndex is a valid number, the given index will be used to create device nodes.

For example; createStandardLoopBackDevice(2) will create /dev/tty2com2 device node in Linux or will throw exception if that number is already in use. Similarly createStandardLoopBackDevice(-1) will create /dev/tty2comXX where XX is the next free number managed by the driver internally.

Typically loopback mode is used to detect communication link failures.

Parameters:

deviceIndex - -1 or valid device number (0 <= deviceIndex =< 65535).

Returns:

Created virtual loop back device's node on success.

Throws:

com.serialpundit.core.SerialComException - if virtual loop back device can not be created, IllegalArgumentException if deviceIndex is invalid.

createCustomLoopBackDevice

public String[] createCustomLoopBackDevice(int deviceIndex,
                                  int rtsMap,
                                  int dtrMap,
                                  boolean setDTRatOpen)
                                    throws com.serialpundit.core.SerialComException

Creates a virtual port/device connected in standard loopback fashion. If deviceIndex is -1, the next available index will be used by driver. If deviceIndex is a valid number, the given index will be used to create device nodes.

For example; createCustomLoopBackDevice(2, SerialComNullModem.SP_CON_CTS, SerialComNullModem.SP_CON_DTR) will create /dev/tty2com2 device node in Linux or will throw exception if that number is already in use. Similarly createCustomLoopBackDevice(-1, SerialComNullModem.SP_CON_CTS, SerialComNullModem.SP_CON_DTR) will create /dev/tty2comXX where XX is the next free number managed by the driver internally.

To connect RTS pin to CTS pin use rtsMap = SerialComNullModem.SP_CON_CTS. A pin can be connected to one or more pins using bit mask. For example to connect RTS pin to CTS and DSR use rtsMap = SerialComNullModem.SP_CON_CTS | SerialComNullModem.SP_CON_DSR.

Parameters:

deviceIndex - -1 or valid device number (0 <= deviceIndex =< 65535).

rtsMap - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if RTS pin should be left unconnected.

dtrMap - Bit mask of SerialComNullModem.SCM_CON_XXX constants as per the desired pin mappings or 0 if DTR pin should be left unconnected.

setDTRatOpen - if true DTR will be asserted when serial port is opened otherwise it will not be raised.

Returns:

Created virtual loop back device's node on success.

Throws:

com.serialpundit.core.SerialComException - if virtual loop back device can not be created, IllegalArgumentException if deviceIndex is invalid.

destroyAllCreatedVirtualDevices

public boolean destroyAllCreatedVirtualDevices()
                                        throws com.serialpundit.core.SerialComException

Removes all virtual serial devices created by tty2com driver.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed due to some reason.

destroyAllCreatedNullModemPairs

public boolean destroyAllCreatedNullModemPairs()
                                        throws com.serialpundit.core.SerialComException

Removes all null modem virtual serial devices created by tty2com driver.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed due to some reason.

destroyAllCreatedLoopbackDevices

public boolean destroyAllCreatedLoopbackDevices()
                                         throws com.serialpundit.core.SerialComException

Removes all loop back virtual serial devices created by tty2com driver.

Returns:

true if device gets deleted.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed due to some reason.

destroyGivenVirtualDevice

public boolean destroyGivenVirtualDevice(String device)
                                  throws com.serialpundit.core.SerialComException

Removes the given virtual serial device created by tty2com driver. If the given device is one of the device in a null modem pair, the other paired device will be automatically removed.

Returns:

true if device gets deleted.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed due to some reason, device is null or invalid string.

getLastLoopBackDeviceNode

public String[] getLastLoopBackDeviceNode()
                                   throws com.serialpundit.core.SerialComException

Returns the device node of last created loop back device.

The sequence of information returned is shown below. The RTS and DTR mappings are returned in string form. The caller has to convert them into int data type and then constant bit mask SerialComNullModem.SP_CON_XXX can be used. The x is 0 or multiple of 3.
x + 0: port's name/path
x + 1: port's RTS mappings
x + 2: port's DTR mappings

Returns:

Device node on success otherwise null.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed for some reason.

getLastNullModemPairNodes

public String[] getLastNullModemPairNodes()
                                   throws com.serialpundit.core.SerialComException

Returns the device nodes of last created null modem pair.

The sequence of information returned is shown below. The RTS and DTR mappings are returned in string form. The caller has to convert them into int data type and then constant bit mask SerialComNullModem.SP_CON_XXX can be used. The x is 0 or multiple of 6.
x + 0: 1st port's name/path
x + 1: 1st port's RTS mappings
x + 2: 1st port's DTR mappings
x + 3: 2nd port's name/path
x + 4: 2nd port's RTS mappings
x + 5: 2nd port's DTR mappings

Returns:

Device nodes of null modem pair on success otherwise null.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed for some reason.

emulateSerialEvent

public boolean emulateSerialEvent(String devNode,
                         int error)
                           throws com.serialpundit.core.SerialComException

Emulates the given line error/event (frame, parity, overrun or break) on given virtual device.

Parameters:

devNode - virtual serial port which will receive this error event.

error - one of the constants SerialComNullModem.ERR_XXX or SerialComNullModem.RCV_BREAK.

Returns:

true if the given error has been emulated on given virtual serial port otherwise false.

Throws:

com.serialpundit.core.SerialComException - if the operating system specific file is not found, writing to it fails or operation can not be completed due to some reason for example if driver is not loaded, port has not been opened.

emulateLineRingingEvent

public boolean emulateLineRingingEvent(String devNode,
                              boolean state)
                                throws com.serialpundit.core.SerialComException

Emulate line ringing event on given device node.

Parameters:

devNode - device node which will observe ringing conditions.

state - true if ringing event should be asserted or false for de-assertion.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if the operating system specific file is not found, writing to it fails or operation can not be completed due to some reason for example if driver is not loaded, port has not been opened.

registerTTY2COMHotPlugEventListener

public int registerTTY2COMHotPlugEventListener(Itty2comHotPlugListener hotPlugListener,
                                      String deviceNode)
                                        throws com.serialpundit.core.SerialComException

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

Application must implement Itty2comHotPlugListener interface and override onTTY2COMHotPlugEvent method. The event value SerialComNullModem.DEV_ADDED indicates virtual serial device has been added to the system. The event value SerialComNullModem.DEV_REMOVED indicates virtual serial device has been removed from system.

This can also be used to detect situations like broken serial cable.

Parameters:

hotPlugListener - object of class which implements Itty2comHotPlugListener interface.

deviceNode - serial port name or null.

Returns:

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

Throws:

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

IllegalArgumentException - if hotPlugListener is null.

unregisterTTY2COMHotPlugEventListener

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

This unregisters listener and terminate native thread used for monitoring virtual serial device insertion or removal.

Parameters:

opaqueHandle - handle returned by registerTTY2COMHotPlugEventListener 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.

getStatsForGivenDevice

public String[] getStatsForGivenDevice(String deviceNode)
                                throws com.serialpundit.core.SerialComException

Gives operating system specific device stats at the instant this method is called like number of bytes transmitted, number of bytes received etc.

For Linux the following information is returned in the given order starting at index 0 in returned string array: number of bytes transmitted, number if bytes received, number of times CTS was raised, number of times DCD was raised, number of times DSR was raised, number of times BREAK signal was received, number of times RING signal was detected, number of times framing error has occurred, number of times parity error has occurred, number of times overrun error has occurred and number of times buffer overrun error has occurred.

Parameters:

deviceNode - name of the virtual serial port whose stats are to be fetched from driver.

Returns:

operating system specific device stats for given serial port.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed for some reason.

emulateFaultyCable

public void emulateFaultyCable(String deviceNode,
                      boolean state)
                        throws com.serialpundit.core.SerialComException

Set/Unset faulty cable condition. If the state is true, faulty cable condition is emulated by driver i.e. the data will be sent from sender end but receiver will not receive it. If the state is false, driver will emulate a good cable condition i.e. all data integrity will be maintained and data will be sent to intended receiver.

Parameters:

deviceNode - name of the virtual serial port (virtual cable is attached to this port).

state - true for faulty cable otherwise false.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed for some reason.