Package ej.serial

Class 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);
        }
 }

    • 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

      • 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.

      • isClosed

        public boolean isClosed()
        Returns the closed state of this connection.
        Returns:
        true if this connection has been closed.