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
ALL_CONTROL_LINESif you install aSerialChangeListener. 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 passNO_CONTROL_LINE_CHANGEto the constructor.Example:
Once the port has been opened, you can change any setting that you want to(baud, parity, etc).//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" );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 Description static classSerialPort.BaudRateRepresents the BaudRate that the SerialPort uses.static classSerialPort.DataBitsRepresents the number of bits that the serial port uses.static classSerialPort.FlowControlThe Flow control scheme for the data, typically None.static classSerialPort.ParityThe parity bit for the data.static classSerialPort.StopBitsThe number of stop bits for data.
-
Field Summary
Fields Modifier and Type Field Description static intALL_CONTROL_LINESAll CONTROL_LINE_XXX_CHANGE values OR'd togetherstatic intCONTROL_LINE_CD_CHANGEFlag to set if you want to get notifications on Carrier Detect line changestatic intCONTROL_LINE_CTS_CHANGEFlag to set if you want to get notifications on Clear To Send line changestatic intCONTROL_LINE_DSR_CHANGEFlag to set if you want to get notifications on Data Set Ready line changestatic intCONTROL_LINE_DTR_CHANGEFlag to set if you want to get notifications on Data Terminal Ready line changestatic intCONTROL_LINE_RI_CHANGEFlag to set if you want to get notifications on Ring Indicagor line changestatic intCONTROL_LINE_RTS_CHANGEFlag to set if you want to get notifications on Request To Send line changestatic intNO_CONTROL_LINE_CHANGEFlag to set if you do not want to get any control line notifications
-
Constructor Summary
Constructors Constructor 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 linesSerialPort(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 linesSerialPort(String portName, SerialPort.BaudRate rate)Open the specified port, no flow control, 8 data bitsSerialPort(String portName, SerialPort.BaudRate rate, int controlLines)Open the specified port, no flow controlSerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data)Open the specified port, no flow controlSerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, int controlLineFlags)Open the specified port, no flow controlSerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop)Open the specified port, no parity or flow controlSerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, int controlFlags)Open the specified port, no parity or flow controlSerialPort(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 flagsSerialPort(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 flagsSerialPort(String portName, SerialPort.BaudRate rate, SerialPort.DataBits data, SerialPort.StopBits stop, SerialPort.Parity parity, SerialPort.FlowControl flow)Open the specified port, defining all optionsSerialPort(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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidclose()voidfinalize()SerialPort.BaudRategetBaudRate()Get the baud rate of the serial port.SerialPort.DataBitsgetDataBits()Get the number of data bits.SerialPort.FlowControlgetFlowControl()Get the flow control for the serial port.InputStreamgetInputStream()Get the input stream used to talk to this device.static intgetMajorNativeVersion()Get the major version of the native code.static intgetMajorVersion()Get the major version of this library.static intgetMinorNativeVersion()Get the minor version of the native code.static intgetMinorVersion()Get the minor version of this library.OutputStreamgetOutputStream()Get the OutputStream used to talk to this device.SerialPort.ParitygetParity()Get the parity of the serial port.StringgetPortName()Get the name of the serial port that this object represents.SerialLineStategetSerialLineState()Get the serial line state for the specified serial port.protected intgetSerialLineStateInternalNonblocking()Get the serial line state, but don't block when getting itstatic String[]getSerialPorts()Get an array of all the serial ports on the system.SerialPort.StopBitsgetStopBits()Get the number of stop bits.booleanisClosed()voidsetBaudRate(SerialPort.BaudRate rate)Set the Baud Rate for this port.voidsetDataSize(SerialPort.DataBits data)Set the data bits size, after the port has been opened.voidsetFlowControl(SerialPort.FlowControl flow)Set the flow control for the serial portvoidsetInterruptCausesIOException(boolean interruptCausesIOException)Set if using Thread.interrupt() will throw an IO exception.voidsetParity(SerialPort.Parity parity)Set the parity of the serial port, after the port has been opened.voidsetSerialChangeListener(SerialChangeListener listen)Set the listener which will get events when there is activity on the serial port.voidsetSerialLineState(SerialLineState state)Set the serial line state to the parameters given.voidsetStopBits(SerialPort.StopBits stop)Set the stop bits of the serial port, after the port has been opened.
-
-
-
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 existNotASerialPortException- If the specified port is not a serial portIOException- 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 existNotASerialPortException- If the specified port is not a serial portIOException- 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 opencontrolLineFlags- The control lines to get a notification for when they change.- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openkeepSettings- If true, will simply open the serial port without setting anything. If false, this method acts the same asSerialPort( String portName )- Throws:
NoSuchPortException- If the port does not existNotASerialPortException- If the port is not in fact a serial portIOException- 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 openkeepSettings- If true, will simply open the serial port without setting anything. If false, this method acts the same asSerialPort( 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 existNotASerialPortException- If the port is not in fact a serial portIOException- 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 openrate- The Baud Rate to open this port at- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atcontrolLines- The control lines to be notifie don a change in.- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bits- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bits- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bits- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bits- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bitsparity- The parity of the line- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bitsparity- The parity of the linecontrolLineFlags- A bitwise OR of any the CONTORL_LINE_XXX_CHANGE flags, or NO_CONTROL_LINE_CHANGE- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bitsparity- The parity of the lineflow- The flow control of the line- Throws:
NoSuchPortException- If this port does not existNotASerialPortException- If the specified port is not a serial portIOException- 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 openrate- The Baud Rate to open this port atdata- The number of data bitsstop- The number of stop bitsparity- The parity of the lineflow- The flow control of the linecontrolFlags- 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 existNotASerialPortException- If the specified port is not a serial portIOException- 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()
-
close
public void close()
- Specified by:
closein interfaceAutoCloseable
-
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 IOExceptionGet 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 withgetMajorVersion(), 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 withgetMinorVersion(), 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/symlinkto/dev/ttyUSB0, they will both show up.NOTE: this will only return ports that you have permissions to open.
- Returns:
- Throws:
IOException
-
-