ej.serial

Class SerialConnection

java.lang.Object

ej.serial.SerialConnection

All Implemented Interfaces:

AutoCloseable

public class SerialConnection
extends Object
implements AutoCloseable

This class defines a connection to a serial port.

A serial port offers a (bi-directional) communication channel connecting two devices (or more in the case of a bus topology such as RS-485): each device can send/receive a stream of characters to/from the other device.
A serial port can represent different serial communication interfaces: a UART, a Virtual Serial Port (e.g. over USB), a loopback interface, …

A SerialConnection is opened by providing a port name. For the list of supported ports, please refer to your VEE Port documentation. The serial line parameters can be configured with configure(int, int, int, int). Whether calling configure(int, int, int, int) is required depends on the VEE Port implementation — if the port is already configured at open time (e.g. a virtual USB-CDC port or a platform-configured UART), the connection is ready to use immediately without calling configure().

A SerialConnection can be configured with the following parameters:

• the baudrate: the rate at which information is transferred in a communication channel.
  In the serial port context, "9600 baud" means that the serial port is capable of transferring a maximum of 9600 bits per second (including the start bit, the stop bit(s) and the parity bit if present).
• the data bits: the number of data bits in each character.
• the stop bits: the duration of the stop mark (in number of bits) sent at the end of each character allow the receiving signal hardware to detect the end of a character and re-synchronize with the character stream.
• the parity mode: the parity bit in each character is a method of detecting transmission errors.

A SerialConnection provides exactly one InputStream and one OutputStream. Repeated calls to getInputStream() or getOutputStream() return the same already-instantiated stream object.

SerialConnection implements AutoCloseable, which means it works best with the try-with-resources statement. If not, method close() must be explicitly called to free the physical port. The InputStream and OutputStream share the connection's lifecycle: closing any one of them closes the underlying connection.

Example:

 try (SerialConnection connection = new SerialConnection("COM6")) {
        connection.configure(115_200, SerialConnection.DATABITS_8,
                        SerialConnection.PARITY_NONE, SerialConnection.STOPBITS_1);
        InputStream is = connection.getInputStream();
        OutputStream os = connection.getOutputStream();
        int read;
        while ((read = is.read(buffer)) != -1) {
                os.write(buffer, 0, read);
        }
 }
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	DATABITS_5 Data bits: 5.
static int	DATABITS_6 Data bits: 6.
static int	DATABITS_7 Data bits: 7.
static int	DATABITS_8 Data bits: 8.
static int	DATABITS_9 Data bits: 9.
static int	PARITY_EVEN Parity mode: even.
static int	PARITY_NONE Parity mode: none.
static int	PARITY_ODD Parity mode: odd.
static int	STOPBITS_1 Stop bits: 1.
static int	STOPBITS_1_5 Stop bits: 1.5.
static int	STOPBITS_2 Stop bits: 2.

Constructor Summary

Constructors

Constructor and Description
SerialConnection(String portName) Opens a connection to the serial port with no explicit line configuration.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this connection.
void	configure(int baudrate, int databits, int parity, int stopbits) Sets the serial line parameters for this connection.
InputStream	getInputStream() Returns the InputStream for this connection.
OutputStream	getOutputStream() Returns the OutputStream for this connection.
boolean	isClosed() Returns the closed state of this connection.

Methods inherited from class java.lang.Object

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

Field Detail

DATABITS_5

public static final int DATABITS_5

Data bits: 5.

See Also:

Constant Field Values

DATABITS_6

public static final int DATABITS_6

Data bits: 6.

See Also:

Constant Field Values

DATABITS_7

public static final int DATABITS_7

Data bits: 7.

See Also:

Constant Field Values

DATABITS_8

public static final int DATABITS_8

Data bits: 8.

See Also:

Constant Field Values

DATABITS_9

public static final int DATABITS_9

Data bits: 9.

See Also:

Constant Field Values

PARITY_EVEN

public static final int PARITY_EVEN

Parity mode: even.

See Also:

Constant Field Values

PARITY_NONE

public static final int PARITY_NONE

Parity mode: none.

See Also:

Constant Field Values

PARITY_ODD

public static final int PARITY_ODD

Parity mode: odd.

See Also:

Constant Field Values

STOPBITS_1

public static final int STOPBITS_1

Stop bits: 1.

See Also:

Constant Field Values

STOPBITS_1_5

public static final int STOPBITS_1_5

Stop bits: 1.5.

See Also:

Constant Field Values

STOPBITS_2

public static final int STOPBITS_2

Stop bits: 2.

See Also:

Constant Field Values

Constructor Detail

SerialConnection

public SerialConnection(String portName)
                 throws IOException

Opens a connection to the serial port with no explicit line configuration.

Whether configure(int, int, int, int) must subsequently be called depends on the VEE Port implementation — if the underlying LLAPI open() already configures the port (e.g. from a platform default or from a virtual port that ignores line parameters), the connection is ready to use immediately.

Parameters:

portName - the serial port name (specific to the platform used).

Throws:

IOException - if an I/O error occurs. For example, portName does not exist or is already in use.

SecurityException - if a security manager exists and does not allow the caller to access the serial port.

Method Detail

close

public void close()
           throws IOException

Closes this connection.

If this SerialConnection is already closed, this method does nothing.

Closing this SerialConnection will also close its InputStream and OutputStream.

Specified by:

close in interface AutoCloseable

Throws:

IOException - if an I/O error occurs while closing the serial port.

configure

public void configure(int baudrate,
                      int databits,
                      int parity,
                      int stopbits)
               throws IOException

Sets the serial line parameters for this connection.

This method is optional. Whether it needs to be called depends on the VEE Port implementation. If the port is configured at open time by the LLAPI (e.g. a virtual USB-CDC port or a UART whose defaults are set by the platform), calling configure() may not be necessary. For ports where the application controls the line parameters, configure() must be called before communication.

The provided parameters are used to configure the physical interface. If the configuration arguments are not applicable to the target port (for example USB-CDC virtual port), the configuration is ignored. If the requested configuration is invalid, an IllegalArgumentException is thrown. If an unsupported configuration is requested, a SerialConfigurationException is thrown.

Parameters:

baudrate - the serial port baudrate (e.g. 9_600, 115_200, …)

databits - the serial port data bits, one of DATABITS_5, DATABITS_6, DATABITS_7, DATABITS_8, DATABITS_9.

parity - the serial port parity mode, one of PARITY_NONE, PARITY_ODD, PARITY_EVEN.

stopbits - the serial port stop bits, one of STOPBITS_1, STOPBITS_1_5, STOPBITS_2.

Throws:

IOException - if an I/O error occurs (e.g. the port was disconnected).

IllegalArgumentException - if a configuration argument is illegal

SerialConfigurationException - if the hardware does not support the requested parameter combination. The parameters are the cause; retrying with the same values will always fail.

getInputStream

public InputStream getInputStream()
                           throws IOException

Returns the InputStream for this connection.

Subsequent calls to this method return the same InputStream instance.

Closing the InputStream of a SerialConnection closes the underlying SerialConnection.

Returns:

the InputStream for reading bytes from this SerialConnection.

Throws:

IOException - if this connection is closed.

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Returns the OutputStream for this connection.

Subsequent calls to this method return the same OutputStream instance.

Closing the OutputStream of a SerialConnection closes the underlying SerialConnection.

Returns:

the OutputStream for writing bytes to this SerialConnection.

Throws:

IOException - if this connection is closed.

isClosed

public boolean isClosed()

Returns the closed state of this connection.

Returns:

true if this connection has been closed.