Interface SerialPort

  • All Superinterfaces:
    AutoCloseable, Closeable
    All Known Implementing Classes:
    RxTxSerialPort

    @NonNullByDefault
    public interface SerialPort
    extends Closeable
    Interface for a serial port.

    This interface is similar to the serial port of the 'Java Communications API'.

    Author:
    Markus Rathgeb - Initial contribution, Kai Kreuzer - added further methods
    • Method Detail

      • setSerialPortParams

        void setSerialPortParams​(int baudrate,
                                 int dataBits,
                                 int stopBits,
                                 int parity)
                          throws UnsupportedCommOperationException
        Sets serial port parameters.
        Parameters:
        baudrate - the baud rate
        dataBits - the number of data bits
        stopBits - the number of stop bits
        parity - the parity
        Throws:
        UnsupportedCommOperationException - if the operation is not supported
      • getInputStream

        @Nullable InputStream getInputStream()
                                      throws IOException
        Returns an input stream.

        This is the only way to receive data from the communications port. If the port is unidirectional and doesn't support receiving data, then getInputStream returns null.

        The read behaviour of the input stream returned by getInputStream depends on combination of the threshold and timeout values. The possible behaviours are described in the table below: | Threshold .........| Timeout ........ | Read Buffer Size | Read Behaviour | | State ...| Value ..| State ...| Value | | disabled | - ......| disabled | - ....| n bytes .........| block until any data is available | enabled .| m bytes | disabled | - ....| n bytes .........| block until min(m,n) bytes are available | disabled | - ......| enabled .| x ms .| n bytes .........| block for x ms or until any data is available | enabled .| m bytes | enabled .| x ms .| n bytes .........| block for x ms or until min(m,n) bytes are available

        Note, however, that framing errors may cause the Timeout and Threshold values to complete prematurely without raising an exception.

        Enabling the Timeout OR Threshold with a value a zero is a special case. This causes the underlying driver to poll for incoming data instead being event driven. Otherwise, the behaviour is identical to having both the Timeout and Threshold disabled. *

        Returns:
        the input stream or null
        Throws:
        IOException - on I/O error
      • getOutputStream

        @Nullable OutputStream getOutputStream()
                                        throws IOException
        Returns an output stream.

        This is the only way to send data to the communications port. If the port is unidirectional and doesn't support sending data, then getOutputStream returns null.

        Returns:
        the output stream or null
        Throws:
        IOException - on I/O error
      • getName

        String getName()
        Retrieves the name of the serial port.
        Returns:
        the name of the serial port
      • addEventListener

        void addEventListener​(SerialPortEventListener listener)
                       throws TooManyListenersException
        Registers a SerialPortEventListener object to listen for SerialEvents.

        Interest in specific events may be expressed using the notifyOnXXX calls. The serialEvent method of SerialPortEventListener will be called with a SerialEvent object describing the event. Only one listener per SerialPort is allowed. Once a listener is registered, subsequent call attempts to addEventListener will throw a TooManyListenersException without effecting the listener already registered.

        All the events received by this listener are generated by one dedicated thread that belongs to the SerialPort object. After the port is closed, no more event will be generated.

        Parameters:
        listener - the listener
        Throws:
        TooManyListenersException - if too many listeners has been added
      • removeEventListener

        void removeEventListener()
        Remove the event listener.
      • notifyOnDataAvailable

        void notifyOnDataAvailable​(boolean enable)
        Enable / disable the notification for 'data available'.
        Parameters:
        enable - true if the notification should be enabled
      • notifyOnBreakInterrupt

        void notifyOnBreakInterrupt​(boolean enable)
        Enable / disable the notification on break interrupt.
        Parameters:
        enable - true if the notification should be enabled
      • notifyOnFramingError

        void notifyOnFramingError​(boolean enable)
        Enable / disable the notification on framing error.
        Parameters:
        enable - true if the notification should be enabled
      • notifyOnOverrunError

        void notifyOnOverrunError​(boolean enable)
        Enable / disable the notification on overrun error.
        Parameters:
        enable - true if the notification should be enabled
      • notifyOnParityError

        void notifyOnParityError​(boolean enable)
        Enable / disable the notification on parity error.
        Parameters:
        enable - true if the notification should be enabled
      • disableReceiveTimeout

        void disableReceiveTimeout()
        Disable receive timeout.
      • setRTS

        void setRTS​(boolean rts)
        Sets or clears the RTS (Request To Send) bit in the UART, if supported by the underlying implementation.
        Parameters:
        rts - true rts is set, false if rts cleared