com.rm5248.serial

Class SerialPort

java.lang.Object

com.rm5248.serial.SerialPort

All Implemented Interfaces:

AutoCloseable

public class SerialPort
extends Object
implements AutoCloseable

A SerialPort represents a serial port on the system. To open a serial port, use the appropriate constructor to open it, providing the entire path to the serial port, and optionally settings. You can define:

• The speed of the serial port
• The number of data bits
• The number of stop bits.
• The parity
• The flow control
• The control lines to monitor

The special parameter controlLineFlags to the constructor defines what control lines you want to listen for. By default, you will get notifications for ALL_CONTROL_LINES if you install a SerialChangeListener. Note that any control line changes you want to listen for require a new thread per serial port. Often you don't need to listen to any serial line changes, and in that case you can pass NO_CONTROL_LINE_CHANGE to the constructor.

Example:

 
 //Open up a serial port on Mac/Linux
 SerialPort s = new SerialPort( "/dev/ttyS0" );
 //Open up a serial port on Windows
 SerialPort s = new SerialPort( "COM1" );
 
 

Once the port has been opened, you can change any setting that you want to(baud, parity, etc).

The native code is automatically extracted from the jar file. If you need to use a special version, there are two Java properties to set.

com.rm5248.javaserial.lib.path - give the directory name that the JNI code is located in
com.rm5248.javaserial.lib.name - explicitly give the name of the library(the default is 'javaserial')

Author:

rm5248

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SerialPort.BaudRate Represents the BaudRate that the SerialPort uses.
static class	SerialPort.DataBits Represents the number of bits that the serial port uses.
static class	SerialPort.FlowControl The Flow control scheme for the data, typically None.
static class	SerialPort.Parity The parity bit for the data.
static class	SerialPort.StopBits The number of stop bits for data.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL_CONTROL_LINES All CONTROL_LINE_XXX_CHANGE values OR'd together
static int	CONTROL_LINE_CD_CHANGE Flag to set if you want to get notifications on Carrier Detect line change
static int	CONTROL_LINE_CTS_CHANGE Flag to set if you want to get notifications on Clear To Send line change
static int	CONTROL_LINE_DSR_CHANGE Flag to set if you want to get notifications on Data Set Ready line change
static int	CONTROL_LINE_DTR_CHANGE Flag to set if you want to get notifications on Data Terminal Ready line change
static int	CONTROL_LINE_RI_CHANGE Flag to set if you want to get notifications on Ring Indicagor line change
static int	CONTROL_LINE_RTS_CHANGE Flag to set if you want to get notifications on Request To Send line change
static int	NO_CONTROL_LINE_CHANGE Flag to set if you do not want to get any control line notifications

Constructor Summary

Constructors

Constructor and Description
SerialPort(SerialPortBuilder builder) Open the specified port, using parameters from the given builder.
SerialPort(String portName) Open the specified port, 9600 baud, 8 data bits, 1 stop bit, no parity, no flow control, not ignoring control lines
SerialPort(String portName, boolean keepSettings) Open up a serial port, but allow the user to keep the current settings of the serial port.
SerialPort(String portName, boolean keepSettings, int controlFlags) Open up a serial port, but allow the user to keep the current settings of the serial port.
SerialPort(String portName, int controlLineFlags) Open the specified port, 9600 baud, 8 data bits, 1 stop bit, no parity, no flow control, looking for the specified control lines
SerialPort(String portName, SerialPort.BaudRate rate) Open the specified port, no flow control, 8 data bits
SerialPort(String portName, SerialPort.BaudRate rate, int controlLines) Open the specified port, no flow control
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data) Open the specified port, no flow control
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, int controlLineFlags) Open the specified port, no flow control
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop) Open the specified port, no parity or flow control
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, int controlFlags) Open the specified port, no parity or flow control
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, SerialPort.Parity parity) Open the specified port, no flow control, with all control line flags
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, SerialPort.Parity parity, int controlLineFlags) Open the specified port, no flow control, with the specified control line flags
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, SerialPort.Parity parity, SerialPort.FlowControl flow) Open the specified port, defining all options
SerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, SerialPort.Parity parity, SerialPort.FlowControl flow, int controlFlags) Open the specified port, defining all options

Method Summary

Modifier and Type	Method and Description
void	close()
void	finalize()
SerialPort.BaudRate	getBaudRate() Get the baud rate of the serial port.
SerialPort.DataBits	getDataBits() Get the number of data bits.
SerialPort.FlowControl	getFlowControl() Get the flow control for the serial port.
InputStream	getInputStream() Get the input stream used to talk to this device.
static int	getMajorNativeVersion() Get the major version of the native code.
static int	getMajorVersion() Get the major version of this library.
static int	getMinorNativeVersion() Get the minor version of the native code.
static int	getMinorVersion() Get the minor version of this library.
OutputStream	getOutputStream() Get the OutputStream used to talk to this device.
SerialPort.Parity	getParity() Get the parity of the serial port.
String	getPortName() Get the name of the serial port that this object represents.
SerialLineState	getSerialLineState() Get the serial line state for the specified serial port.
protected int	getSerialLineStateInternalNonblocking() Get the serial line state, but don't block when getting it
static String[]	getSerialPorts() Get an array of all the serial ports on the system.
SerialPort.StopBits	getStopBits() Get the number of stop bits.
boolean	isClosed()
void	setBaudRate(SerialPort.BaudRate rate) Set the Baud Rate for this port.
void	setDataSize(SerialPort.DataBits data) Set the data bits size, after the port has been opened.
void	setFlowControl(SerialPort.FlowControl flow) Set the flow control for the serial port
void	setInterruptCausesIOException(boolean interruptCausesIOException) Set if using Thread.interrupt() will throw an IO exception.
void	setParity(SerialPort.Parity parity) Set the parity of the serial port, after the port has been opened.
void	setSerialChangeListener(SerialChangeListener listen) Set the listener which will get events when there is activity on the serial port.
void	setSerialLineState(SerialLineState state) Set the serial line state to the parameters given.
void	setStopBits(SerialPort.StopBits stop) Set the stop bits of the serial port, after the port has been opened.

Methods inherited from class java.lang.Object

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

Field Detail

NO_CONTROL_LINE_CHANGE

public static final int NO_CONTROL_LINE_CHANGE

Flag to set if you do not want to get any control line notifications

See Also:

Constant Field Values

CONTROL_LINE_DTR_CHANGE

public static final int CONTROL_LINE_DTR_CHANGE

Flag to set if you want to get notifications on Data Terminal Ready line change

See Also:

Constant Field Values

CONTROL_LINE_RTS_CHANGE

public static final int CONTROL_LINE_RTS_CHANGE

Flag to set if you want to get notifications on Request To Send line change

See Also:

Constant Field Values

CONTROL_LINE_CD_CHANGE

public static final int CONTROL_LINE_CD_CHANGE

Flag to set if you want to get notifications on Carrier Detect line change

See Also:

Constant Field Values

CONTROL_LINE_CTS_CHANGE

public static final int CONTROL_LINE_CTS_CHANGE

Flag to set if you want to get notifications on Clear To Send line change

See Also:

Constant Field Values

CONTROL_LINE_DSR_CHANGE

public static final int CONTROL_LINE_DSR_CHANGE

Flag to set if you want to get notifications on Data Set Ready line change

See Also:

Constant Field Values

CONTROL_LINE_RI_CHANGE

public static final int CONTROL_LINE_RI_CHANGE

Flag to set if you want to get notifications on Ring Indicagor line change

See Also:

Constant Field Values

ALL_CONTROL_LINES

public static final int ALL_CONTROL_LINES

All CONTROL_LINE_XXX_CHANGE values OR'd together

See Also:

Constant Field Values

Constructor Detail

SerialPort

public SerialPort(SerialPortBuilder builder)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, using parameters from the given builder.

Parameters:

builder - The builder to construct the SerialPort from.

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, 9600 baud, 8 data bits, 1 stop bit, no parity, no flow control, not ignoring control lines

Parameters:

portName - The name of the port to open

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  int controlLineFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, 9600 baud, 8 data bits, 1 stop bit, no parity, no flow control, looking for the specified control lines

Parameters:

portName - The name of the port to open

controlLineFlags - The control lines to get a notification for when they change.

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  boolean keepSettings)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open up a serial port, but allow the user to keep the current settings of the serial port. Will notify on all control line changes.

Parameters:

portName - The port to open

keepSettings - If true, will simply open the serial port without setting anything. If false, this method acts the same as SerialPort( String portName )

Throws:

NoSuchPortException - If the port does not exist

NotASerialPortException - If the port is not in fact a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  boolean keepSettings,
                  int controlFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open up a serial port, but allow the user to keep the current settings of the serial port.

Parameters:

portName - The port to open

keepSettings - If true, will simply open the serial port without setting anything. If false, this method acts the same as SerialPort( String portName )

controlFlags - The control flags to listen for changes for. This is a bitwise-OR of CONTROL_LINE_XXX_CHANGE, or NO_CONTROL_LINE_CHANGE if you don't care about getting notified about the control line changes.

Throws:

NoSuchPortException - If the port does not exist

NotASerialPortException - If the port is not in fact a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control, 8 data bits

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  int controlLines)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

controlLines - The control lines to be notifie don a change in.

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  int controlLineFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no parity or flow control

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop,
                  int controlFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no parity or flow control

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop,
                  SerialPort.Parity parity)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control, with all control line flags

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

parity - The parity of the line

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop,
                  SerialPort.Parity parity,
                  int controlLineFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, no flow control, with the specified control line flags

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

parity - The parity of the line

controlLineFlags - A bitwise OR of any the CONTORL_LINE_XXX_CHANGE flags, or NO_CONTROL_LINE_CHANGE

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop,
                  SerialPort.Parity parity,
                  SerialPort.FlowControl flow)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, defining all options

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

parity - The parity of the line

flow - The flow control of the line

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

SerialPort

public SerialPort(String portName,
                  SerialPort.BaudRate rate,
                  SerialPort.DataBits data,
                  SerialPort.StopBits stop,
                  SerialPort.Parity parity,
                  SerialPort.FlowControl flow,
                  int controlFlags)
           throws NoSuchPortException,
                  NotASerialPortException,
                  IOException

Open the specified port, defining all options

Parameters:

portName - The name of the port to open

rate - The Baud Rate to open this port at

data - The number of data bits

stop - The number of stop bits

parity - The parity of the line

flow - The flow control of the line

controlFlags - The control flags to listen for changes for. This is a bitwise-OR of CONTROL_LINE_XXX_CHANGE, or NO_CONTROL_LINE_CHANGE if you don't care about getting notified about the control line changes.

Throws:

NoSuchPortException - If this port does not exist

NotASerialPortException - If the specified port is not a serial port

IOException - if a low-level error occurs

Method Detail

setBaudRate

public void setBaudRate(SerialPort.BaudRate rate)
                 throws IOException

Set the Baud Rate for this port.

Parameters:

rate -

Throws:

IOException

isClosed

public boolean isClosed()

finalize

public void finalize()

Overrides:

finalize in class Object

close

public void close()

Specified by:

close in interface AutoCloseable

getInputStream

public InputStream getInputStream()

Get the input stream used to talk to this device.

setInterruptCausesIOException

public void setInterruptCausesIOException(boolean interruptCausesIOException)

Set if using Thread.interrupt() will throw an IO exception. Note: This is OS and implementation-specific. Depending on how the serial port is opened, this value may have no effect. This will work in the following situations:

• Opening a serial port, monitoring the serial lines(e.g. NO_SERIAL_LINE_CHANGE was not passed to the constructor)

Parameters:

interruptCausesIOException -

getOutputStream

public OutputStream getOutputStream()

Get the OutputStream used to talk to this device.

setStopBits

public void setStopBits(SerialPort.StopBits stop)
                 throws IOException

Set the stop bits of the serial port, after the port has been opened.

Parameters:

stop -

Throws:

IOException

setDataSize

public void setDataSize(SerialPort.DataBits data)
                 throws IOException

Set the data bits size, after the port has been opened.

Parameters:

data -

Throws:

IOException

setParity

public void setParity(SerialPort.Parity parity)
               throws IOException

Set the parity of the serial port, after the port has been opened.

Parameters:

parity -

Throws:

IOException

getSerialLineState

public SerialLineState getSerialLineState()
                                   throws IOException

Get the serial line state for the specified serial port.

Returns:

Throws:

IOException

setSerialLineState

public void setSerialLineState(SerialLineState state)
                        throws IOException

Set the serial line state to the parameters given.

Parameters:

state -

Throws:

IOException

getBaudRate

public SerialPort.BaudRate getBaudRate()
                                throws IOException

Get the baud rate of the serial port.

Returns:

Throws:

IOException - if a low-level error occurs

getDataBits

public SerialPort.DataBits getDataBits()
                                throws IOException

Get the number of data bits.

Returns:

Throws:

IOException - if a low-level error occurs

getStopBits

public SerialPort.StopBits getStopBits()
                                throws IOException

Get the number of stop bits.

Returns:

Throws:

IOException - if a low-level error occurs

getParity

public SerialPort.Parity getParity()
                            throws IOException

Get the parity of the serial port.

Returns:

Throws:

IOException - if a low-level error occurs

getFlowControl

public SerialPort.FlowControl getFlowControl()
                                      throws IOException

Get the flow control for the serial port.

Returns:

Throws:

IOException - if a low-level error occurs

setFlowControl

public void setFlowControl(SerialPort.FlowControl flow)
                    throws IOException

Set the flow control for the serial port

Parameters:

flow -

Throws:

IOException - if a low-level error occurs

setSerialChangeListener

public void setSerialChangeListener(SerialChangeListener listen)

Set the listener which will get events when there is activity on the serial port. Note that this activity does NOT include receive and transmit events - this is changes on the lines of the serial port, such as RI, DSR, and DTR. If listen is null, will remove the listener.

Parameters:

listen - The listener which gets events

getPortName

public String getPortName()

Get the name of the serial port that this object represents.

Returns:

getSerialLineStateInternalNonblocking

protected int getSerialLineStateInternalNonblocking()
                                             throws IOException

Get the serial line state, but don't block when getting it

Returns:

Throws:

IOException

getMajorVersion

public static int getMajorVersion()

Get the major version of this library. For example, if this is version 0.2, this returns 0

getMinorVersion

public static int getMinorVersion()

Get the minor version of this library. For example, if this is version 0.2, this returns 2.

getMajorNativeVersion

public static int getMajorNativeVersion()

Get the major version of the native code. This should match up with getMajorVersion(), although this is not guaranteed. For example, if this is version 0.2, this returns 0

getMinorNativeVersion

public static int getMinorNativeVersion()

Get the minor version of the native code. This should match up with getMinorVersion(), although this is not guaranteed. For example, if this is version 0.2, this returns 2.

getSerialPorts

public static String[] getSerialPorts()
                               throws IOException

Get an array of all the serial ports on the system. For example, on Windows this will return { "COM1", "COM3", .... } depending on how many serial devices you have plugged in. On Linux, this returns { "/dev/ttyS0", "/dev/ttyUSB0", "/dev/symlink", ... } It will not resolve symlinks, such that if there is a symlink from /dev/symlink to /dev/ttyUSB0 , they will both show up.

NOTE: this will only return ports that you have permissions to open.

Returns:

Throws:

IOException