Package org.openhab.core.io.transport.serial

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, Vita Tucek - added further methods

  • Field Details

  • Method Details

    • close

      void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • 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

    • getBaudRate

      int getBaudRate()
      Gets port baud rate.
      Returns:
      baud rate

    • getDataBits

      int getDataBits()
      Gets number of port data bits.
      Returns:
      data bits

    • getStopBits

      int getStopBits()
      Gets number of port stop bits.
      Returns:
      stop bits count

    • getParity

      int getParity()
      Gets port parity.
      Returns:
      parity

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

      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

    • notifyOnOutputEmpty

      void notifyOnOutputEmpty(boolean enable)
      Enable / disable the notification on output buffer empty.
      Parameters:
      enable - true if the notification should be enabled

    • notifyOnCTS

      void notifyOnCTS(boolean enable)
      Enable / disable the notification on CTS.
      Parameters:
      enable - true if the notification should be enabled

    • notifyOnDSR

      void notifyOnDSR(boolean enable)
      Enable / disable the notification on DSR.
      Parameters:
      enable - true if the notification should be enabled

    • notifyOnRingIndicator

      void notifyOnRingIndicator(boolean enable)
      Enable / disable the notification on ring indicator.
      Parameters:
      enable - true if the notification should be enabled

    • notifyOnCarrierDetect

      void notifyOnCarrierDetect(boolean enable)
      Enable / disable the notification on carrier detect.
      Parameters:
      enable - true if the notification should be enabled

    • enableReceiveTimeout

      void enableReceiveTimeout(int timeout) throws UnsupportedCommOperationException, IllegalArgumentException
      Enables the receive timeout.

      When the receive timeout condition becomes true, a read from the input stream for this port will return immediately.

      Parameters:
      timeout - the timeout (milliseconds), must be greater or equal to zero
      Throws:
      UnsupportedCommOperationException - if the operation is not supported
      IllegalArgumentException - on a negative timeout value

    • disableReceiveTimeout

      void disableReceiveTimeout()
      Disable receive timeout.

    • setFlowControlMode

      void setFlowControlMode(int flowcontrolRtsctsOut) throws UnsupportedCommOperationException
      Sets the flow control mode value.
      Parameters:
      flowcontrolRtsctsOut - The flowcontrol (int) parameter.
      Throws:
      UnsupportedCommOperationException - Unsupported Comm Operation Exception.

    • getFlowControlMode

      int getFlowControlMode()
      Gets the flow control mode value.
      Returns:
      flowcontrol value.

    • enableReceiveThreshold

      void enableReceiveThreshold(int i) throws UnsupportedCommOperationException
      Enable receive threshold with the specified thresh parameter.
      Parameters:
      i - The thresh (int) parameter.
      Throws:
      UnsupportedCommOperationException - Unsupported Comm Operation Exception.

    • 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

    • isRTS

      boolean isRTS()
      Check current state of RTS (Request To Send).
      Returns:
      true if RTS is set, otherwise false

    • setDTR

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

    • isDTR

      boolean isDTR()
      Check current state of DTR (Data Terminal Ready).
      Returns:
      true if DTR is set, otherwise false

    • isCTS

      boolean isCTS()
      Check current state of CTS (Clear To Send).
      Returns:
      true if CTS is set, otherwise false

    • isDSR

      boolean isDSR()
      Check current state of DSR (Request To Send).
      Returns:
      true if DSR is set, otherwise false

    • isCD

      boolean isCD()
      Check current state of CD (Carrier Detect).
      Returns:
      true if CD is set, otherwise false

    • isRI

      boolean isRI()
      Check current state of RI (Ring Indicator).
      Returns:
      true if RI is set, otherwise false

    • sendBreak

      void sendBreak(int duration)
      Send break.
      Parameters:
      duration - Break duration parameter