SerialDefs ( Frame4J -- the Java framework de.frame4j... )

All Known Implementing Classes:

SerNimpl
```
public interface SerialDefs
```
Definitions for the serial input and output (comm interfaces).

This interface describes the usual constants and and methods for the handling of serial computer interfaces (V.24, RS232, RS485, USB2serial; Com1, SerialA, TTY0 and so on). In this form they do appear in the so called COMM-extensions; i.e. the packages
- javax.comm (late Java comm-extensions by SUN),
- gnu.io (RXTX, open source)
- and others.
The variety of those implementations of a quite simple hardware interface / protocol standard is — in the end — SUN's/Oracle's fault, namely by the deficiencies of SUN's javax.comm, it's missing embedding in standard JDKs and JREs and, since 2002, the dropping of Windows support. The main architectural (OO) sin is the missing of a common interface definition like this one (SerialDefs) that would (at least) have made the rank growth of implementations interchangeable.

Remark: SUN's just dropping the Windows support for serial links left some people doing process control with Java (and making propaganda for doing so) high and dry. Many process control devices in use have those serial interfaces that are used (if not even for on-line process control) for maintenance, commissioning, calibration and so on. And there are a variety of Java tools for those purposes. And, of course, they have to run on the industry standard platform, like WinCC etc., for those cases. The widespread USB2serial bridges mimic normal serial links on both sides, giving a new COMxy with Windows.
In that light SUN's 2002 decision to support the serial communication for just Solaris and some Linux variants is incomprehensible. The other way round (also wrong) would have made some sense.

© Copyright 2006, 2007, 2009, 2013 Albrecht Weinert
Version:

66 (7.06.2024)

Author:

Albrecht Weinert

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class SerialDefs.Helper
Implementation of (helper) methods for serial ports.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`SerialDefs.Helper` Implementation of (helper) methods for serial ports.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BI` Event type: Break / Interrupt.
`static int`	`CD` Event type: Carrier detect.
`static int`	`CTS` Event type: Clear to send.
`static int`	`DATA_AVAILABLE` Event type: Data available.
`static int`	`DATABITS_5` Setting: 5 data bits.
`static int`	`DATABITS_6` Setting: 6 data bits.
`static int`	`DATABITS_7` Setting: 7 data bits.
`static int`	`DATABITS_8` Setting: 8 data bits.
`static int`	`DSR` Event type: Data set ready.
`static int`	`FE` Event type: Framing error.
`static int`	`FLOWCONTROL_NONE` Setting: data flow control: none.
`static int`	`FLOWCONTROL_RTSCTS` Setting: data flow control: hardware both directions.
`static int`	`FLOWCONTROL_RTSCTS_IN` Setting: data flow control: hardware on input.
`static int`	`FLOWCONTROL_RTSCTS_OUT` Setting: data flow control: hardware on output.
`static int`	`FLOWCONTROL_XONXOFF` Setting: data flow control: software both directions.
`static int`	`FLOWCONTROL_XONXOFF_IN` Setting: data flow control: software on input.
`static int`	`FLOWCONTROL_XONXOFF_OUT` Setting: data flow control: software on output.
`static int`	`OE` Event type: Overrun error.
`static int`	`OUTPUT_BUFFER_EMPTY` Event type: Output buffer empty.
`static int`	`PARITY_EVEN` Setting: even parity.
`static int`	`PARITY_MARK` Setting: parity mark.
`static int`	`PARITY_NONE` Setting: no parity.
`static int`	`PARITY_ODD` Setting: odd parity.
`static int`	`PARITY_SPACE` Setting: parity space.
`static int`	`PE` Event type: Parity error.
`static int`	`RI` Event type: Ring Indicator.
`static int`	`STOPBITS_1` Setting: 1 stop bit.
`static int`	`STOPBITS_1_5` Setting: 1.5 stop bits.
`static int`	`STOPBITS_2` Setting: 2 stop bits.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`close()` Close the serial port.
`default String`	`flowControlAsString()` Data flow control as String.
`int`	`getBaud()` The serial port's baud rate.
`int`	`getDataBits()` The serial port's data bits, size of one information piece.
`String`	`getExMsg()` The last exception's message.
`int`	`getFlowControlMode()` Data flow control.
`int`	`getParity()` The serial port's parity.
`String`	`getPortName()` The used interface's name.
`int`	`getRcvTimeout()` The serial ports's receive timeout in ms.
`int`	`getStopBits()` The serial port's stop bits.
`boolean`	`isCD()` state des modem's control input's CD (carrier detect) state.
`boolean`	`isCTS()` The modem control input's CTS (clear to send) state.
`boolean`	`isDSR()` The modem control input's DSR (data set ready) state.
`boolean`	`isDTR()` The modem control output's DTR (data terminal ready) state.
`boolean`	`isReady()` Check the serial port's usability.
`boolean`	`isRI()` The modem control input's RI (ring indicator) state.
`boolean`	`isRTS()` The modem control output's RTS (request to send) state.
`void`	`openSerial(CharSequence comPort)` Open the serial port.
`default String`	`parityAsString()` The serial port's parity as String.
`int`	`read()` Read a character from the serial port.
`int`	`read(byte[] b, int o, int l)` Read some bytes from the serial port.
`void`	`setDTR(boolean dtr)` Set the state of modem's control output DTR (data terminal ready).
`void`	`setDtrRts(boolean dtr, boolean rts)` Set the modem control outputs DTR and RTS.
`void`	`setFlowControlMode(int flowControlMode)` Set the data flow control mode.
`void`	`setRcvTimeout(int rcvTimeout)` Set the serial port's receive timeout.
`void`	`setRTS(boolean rts)` Set the state of modem's control output RTS (request to send).
`boolean`	`setSerialPortParams(int baudrate, int dataBits, int stopBits, int parity)` Set all relevant parameters of the serial port.
`String`	`toString()` Text representation.
`int`	`write(byte[] b)` Write some bytes to the serial port.
`int`	`write(byte[] b, int off, int len)` Write some bytes to the serial port.
`boolean`	`write(int b)` Write one byte to the serial port.

- Field Detail
  - DATABITS_5
```
static final int DATABITS_5
```
    Setting: 5 data bits.
    
    Hint: Five data bits are supported by most implementations as serial interface's standard.
    The old Intel IC 8251 USART (universal synchronous and asynchronous receiver and transmitter), of course, can do it, but modern PCs and chip sets may have dropped this mode, like RXTX did.
    
    Value: 5
    
    See Also:
    
    DATABITS_8, getDataBits(), setSerialPortParams(int, int, int, int), Constant Field Values
  - DATABITS_6
```
static final int DATABITS_6
```
    Setting: 6 data bits.
    
    Value: 6
    
    See Also:
    
    DATABITS_5, Constant Field Values
  - DATABITS_7
```
static final int DATABITS_7
```
    Setting: 7 data bits.
    
    Value: 7
    
    See Also:
    
    DATABITS_5, Constant Field Values
  - DATABITS_8
```
static final int DATABITS_8
```
    Setting: 8 data bits.
    
    Value: 8
    
    See Also:
    
    DATABITS_5, Constant Field Values
  - STOPBITS_1
```
static final int STOPBITS_1
```
    Setting: 1 stop bit.
    
    Value: 1
    
    See Also:
    
    STOPBITS_2, getStopBits(), setSerialPortParams(int, int, int, int), Constant Field Values
  - STOPBITS_2
```
static final int STOPBITS_2
```
    Setting: 2 stop bits.
    
    Using two stop bits in a serial link's hardware/software usually affects the transmitter only. The receiver would normally still accept one without reporting an error.
    
    Value: 2
    
    See Also:
    
    STOPBITS_1, getStopBits(), setSerialPortParams(int, int, int, int), Constant Field Values
  - STOPBITS_1_5
```
static final int STOPBITS_1_5
```
    Setting: 1.5 stop bits.
    
    Many USARTS (universal synchronous and asynchronous receiver and transmitter) or chip sets do allow 1.5 stop bits only in combination with 5 data bits (DATABITS_5).
    
    Value: 3
    
    See Also:
    
    DATABITS_5, STOPBITS_2, getStopBits(), setSerialPortParams(int, int, int, int), Constant Field Values
  - PARITY_NONE
```
static final int PARITY_NONE
```
    Setting: no parity.
    
    Value: 0
    
    See Also:
    
    PARITY_EVEN, parityAsString(), getParity(), setSerialPortParams(int, int, int, int), Constant Field Values
  - PARITY_EVEN
```
static final int PARITY_EVEN
```
    Setting: even parity.
    
    One parity bit will be appended in a way that the number of one's is even.
    
    Value: 2
    
    See Also:
    
    PARITY_ODD, parityAsString(), getParity(), setSerialPortParams(int, int, int, int), Constant Field Values
  - PARITY_ODD
```
static final int PARITY_ODD
```
    Setting: odd parity.
    
    One parity bit will be appended in a way that the number of one's is odd.
    
    Value: 1
    
    See Also:
    
    PARITY_EVEN, parityAsString(), getParity(), setSerialPortParams(int, int, int, int), Constant Field Values
  - PARITY_MARK
```
static final int PARITY_MARK
```
    Setting: parity mark.
    
    Value: 3
    
    See Also:
    
    PARITY_EVEN, parityAsString(), getParity(), setSerialPortParams(int, int, int, int), Constant Field Values
  - PARITY_SPACE
```
static final int PARITY_SPACE
```
    Setting: parity space.
    
    Value: 4
    
    See Also:
    
    PARITY_EVEN, parityAsString(), getParity(), setSerialPortParams(int, int, int, int), Constant Field Values
  - FLOWCONTROL_NONE
```
static final int FLOWCONTROL_NONE
```
    Setting: data flow control: none.
    
    Value: 0
    
    See Also:
    
    FLOWCONTROL_RTSCTS, getFlowControlMode(), setSerialPortParams(int, int, int, int), Constant Field Values
  - FLOWCONTROL_RTSCTS_IN
```
static final int FLOWCONTROL_RTSCTS_IN
```
    Setting: data flow control: hardware on input.
    
    Value: 1
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - FLOWCONTROL_RTSCTS_OUT
```
static final int FLOWCONTROL_RTSCTS_OUT
```
    Setting: data flow control: hardware on output.
    
    Value: 2
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - FLOWCONTROL_RTSCTS
```
static final int FLOWCONTROL_RTSCTS
```
    Setting: data flow control: hardware both directions.
    
    Value: 3 (FLOWCONTROL_RTSCTS_OUT | FLOWCONTROL_RTSCTS_IN)
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - FLOWCONTROL_XONXOFF_IN
```
static final int FLOWCONTROL_XONXOFF_IN
```
    Setting: data flow control: software on input.
    
    Value: 4
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - FLOWCONTROL_XONXOFF_OUT
```
static final int FLOWCONTROL_XONXOFF_OUT
```
    Setting: data flow control: software on output.
    
    Value: 8
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - FLOWCONTROL_XONXOFF
```
static final int FLOWCONTROL_XONXOFF
```
    Setting: data flow control: software both directions.
    
    Value: 12 (FLOWCONTROL_XONXOFF_OUT | FLOWCONTROL_XONXOFF_IN)
    
    See Also:
    
    Constant Field Values
  - OE
```
static final int OE
```
    Event type: Overrun error.
    
    Value: 7
    
    See Also:
    
    FLOWCONTROL_NONE, getFlowControlMode(), Constant Field Values
  - PE
```
static final int PE
```
    Event type: Parity error.
    
    Value: 8
    
    See Also:
    
    Constant Field Values
  - FE
```
static final int FE
```
    Event type: Framing error.
    
    Value: 9
    
    See Also:
    
    Constant Field Values
  - BI
```
static final int BI
```
    Event type: Break / Interrupt.
    
    Value: 10
    
    See Also:
    
    Constant Field Values
  - CD
```
static final int CD
```
    Event type: Carrier detect.
    
    Value: 6
    
    See Also:
    
    Constant Field Values
  - RI
```
static final int RI
```
    Event type: Ring Indicator.
    
    Value: 5
    
    See Also:
    
    Constant Field Values
  - DSR
```
static final int DSR
```
    Event type: Data set ready.
    
    Value: 4
    
    See Also:
    
    Constant Field Values
  - CTS
```
static final int CTS
```
    Event type: Clear to send.
    
    Value: 3
    
    See Also:
    
    Constant Field Values
  - DATA_AVAILABLE
```
static final int DATA_AVAILABLE
```
    Event type: Data available.
    
    Value: 1
    
    See Also:
    
    Constant Field Values
  - OUTPUT_BUFFER_EMPTY
```
static final int OUTPUT_BUFFER_EMPTY
```
    Event type: Output buffer empty.
    
    Value: 2
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getPortName
```
String getPortName()
```
    The used interface's name.
    
    It will be platform dependent: something like "COM1", "COM2", "serialA" etc.
    
    Returns:
    
    the port's name
  - getRcvTimeout
```
int getRcvTimeout()
```
    The serial ports's receive timeout in ms.
    
    On receive timeout's (rcvTimeout) values > 0 reading methods return after that time in ms (milliseconds) independent of having received any bytes.
    
    Returns:
    
    the current receive timeout in ms
    
    See Also:
    
    setRcvTimeout(int)
  - setRcvTimeout
```
void setRcvTimeout(int rcvTimeout)
```
    Set the serial port's receive timeout.
    
    If the driver rejects this function the internal value stays at 0.
    
    Parameters:
    
    rcvTimeout - the receive timeout in ms to be set
    
    See Also:
    
    getRcvTimeout()
  - getBaud
```
int getBaud()
```
    The serial port's baud rate.
    
    Returns:
    
    the port's actual baud rate
    
    See Also:
    
    SerialDefs.Helper.baudRate(int), setSerialPortParams(int, int, int, int)
  - getDataBits
```
int getDataBits()
```
    The serial port's data bits, size of one information piece.
    
    Returns:
    
    the port's actual item width in bits
    
    See Also:
    
    setSerialPortParams(int, int, int, int)
  - getStopBits
```
int getStopBits()
```
    The serial port's stop bits.
    
    default: 1 ()STOPBITS_1
    
    Returns:
    
    the actual number of stop bits
    
    See Also:
    
    setSerialPortParams(int, int, int, int), STOPBITS_1, STOPBITS_1_5, STOPBITS_2
  - getParity
```
int getParity()
```
    The serial port's parity.
    
    Returns:
    
    the port's actual parity setting
    
    See Also:
    
    setSerialPortParams(int, int, int, int), parityAsString(), PARITY_NONE, PARITY_EVEN
  - parityAsString
```
default String parityAsString()
```
    The serial port's parity as String.
    
    Returned will be either mark, space, odd, even or none geliefert.
    Applications might be satisfied by this default implementation using SerialDefs.Helper.parityAsString().
    
    Returns:
    
    the port's actual parity setting
    
    See Also:
    
    setSerialPortParams(int, int, int, int), getParity()
  - setSerialPortParams
```
boolean setSerialPortParams(int baudrate,
                            int dataBits,
                            int stopBits,
                            int parity)
```
    Set all relevant parameters of the serial port.
    
    This method sets (almost) all parameters relevant for the port's communication protocol in one step. The set of parameters is that the station at the other and of the line must have set the same way to enable any communication.
    
    A value -1 means no change of the setting in each case.
    
    baud rate:
    Sensible values are only the usual rates, i.e. 9600 (usual default), 19200, 38400 and so on.
    
    Implementations should evaluate the values 0..12 as index to the usual baud rates:
    110, 150, 300, 600, 1200, 2400, 4800, 9600, 19200, [0 .. 8]
    28800, 38400, 57600 and 115200 [9 .. 12].
    
    parity:
    Here only the relevant PARITY_x (x= NONE, ODD, EVEN, MARK and SPACE), like PARITY_NONE (default), make sense.
    
    dataBits:
    Here only the relevant constant values DATABITS_x (x=5..8), like DATABITS_8 (default), make sense. They are the values 5..8.
    
    stopBits:
    Here only the relevant constant values STOPBITS_x (x=1, 2 or 1_5), like STOPBITS_1 (default), make sense.
    sinnvoll.
    
    Hint 1:
    Implementations are free (and often recommended), to let all other setters delegate to this method and to let only this method really talk to the underlying hardware / platform.
    
    Hint 2:
    In the case of successfully calling the the hardware / driver / platform, implementations may re-read the actual setting and signal discrepancies (by returning false) as error. This proceeding is strongly recommended as some drivers silently accept standard baud rates or data widths they can't handle and replace them (silently) by some default or previous value.
    
    Parameters:
    
    baudrate - the baudrate to be set
    
    dataBits - the data item width to be set
    
    stopBits - the number of stop bits to beset
    
    parity - the parity to be set
    
    Returns:
    
    true on successful change or if already set so; false on any error or rejection. In the case of false, nevertheless, changes may have taken place.
    
    See Also:
    
    getParity(), getBaud(), getDataBits(), getStopBits(), STOPBITS_1, STOPBITS_1_5, STOPBITS_2, PARITY_NONE, PARITY_EVEN, PARITY_ODD, PARITY_MARK, PARITY_SPACE
  - getFlowControlMode
```
int getFlowControlMode()
```
    Data flow control.
    
    The value may be any (bitwise) combination of the following values:
    Returns:
    
    the actual flow control setting
    
    See Also:
    
    setFlowControlMode(int)
  - flowControlAsString
```
default String flowControlAsString()
```
    Data flow control as String.
    
    The flowControlMode's value is returned as character sequence.
    
    Applications might be satisfied by this default implementation using SerialDefs.Helper.flowControlAsText(null, getFlowControlMode()).
    
    Returns:
    
    the actual flow control setting
  - setFlowControlMode
```
void setFlowControlMode(int flowControlMode)
```
    Set the data flow control mode.
    
    Parameters:
    
    flowControlMode - the flow control mode to be set
    
    See Also:
    
    getFlowControlMode()
  - isRTS
```
boolean isRTS()
```
    The modem control output's RTS (request to send) state.
    
    Implementations may return the last value set by setRTS(boolean) respectively setDtrRts(boolean, boolean) instead of the interface's re-read value. If doing so false will be returned prior to any first setting.
    
    Returns:
    
    the state of the RTS signal
  - setRTS
```
void setRTS(boolean rts)
```
    Set the state of modem's control output RTS (request to send).
    
    Parameters:
    
    rts - the state of the RTS signal
  - isDTR
```
boolean isDTR()
```
    The modem control output's DTR (data terminal ready) state.
    
    Implementations may return the last value set by setDTR(boolean) respectively setDtrRts(boolean, boolean) instead of the interface's re-read value. If doing so false will be returned prior to any first setting.
    
    Returns:
    
    the state of the DTR signal
  - setDTR
```
void setDTR(boolean dtr)
```
    Set the state of modem's control output DTR (data terminal ready).
    
    Parameters:
    
    dtr - the state of the DTR signal
  - setDtrRts
```
void setDtrRts(boolean dtr,
               boolean rts)
```
    Set the modem control outputs DTR and RTS.
    
    In time critical cases calling this method should be preferred over the single settings by setDTR() and setRTS().
    
    For example, time critical cases are those, where only one of the control signals really is used for control, while in co-operation the other one it powers the external hardware (via a bridge rectifier). There are HART modems working just that way.
    
    Parameters:
    
    dtr - the state of the DTR signal
    
    rts - the state of the RTS signal
  - isDSR
```
boolean isDSR()
```
    The modem control input's DSR (data set ready) state.
  - isCTS
```
boolean isCTS()
```
    The modem control input's CTS (clear to send) state.
  - isCD
```
boolean isCD()
```
    state des modem's control input's CD (carrier detect) state.
  - isRI
```
boolean isRI()
```
    The modem control input's RI (ring indicator) state.
  - isReady
```
boolean isReady()
```
    Check the serial port's usability.
    
    See Also:
    
    close()
  - close
```
void close()
```
    Close the serial port.
    
    Closing a closed port will have no effect at all.
    
    This method will close the port and hence its input and output, sitting it into a "not ready" state.
    
    See Also:
    
    isReady()
  - openSerial
```
void openSerial(CharSequence comPort)
         throws IllegalArgumentException,
                IOException
```
    Open the serial port.
    
    The named interface will be opened. If this SerialDefs object already represents an open (ready) serial port of the same name the call just does nothing.
    
    If this SerialDefs object already represents an open (ready) serial port of another name it will be tried to close that as first step.
    
    Failure will be signalled by Exceptions.
    
    Hint: On Windows the interfaces names are usually "COM1", "COM2" and so on.
    
    Parameters:
    
    comPort - Portname
    
    Throws:
    
    IllegalArgumentException - wrong parameter values
    
    IOException - file or stream problem
  - read
```
int read()
```
    Read a character from the serial port.
    
    This method reads just one character from the serial port. If called without rcvTimeout it will wait / block for unlimited time.
    
    On not ready, errors or timeout -1 will be returned.
    
    Returns:
    
    The byte read (0..255) or -1
  - read
```
int read(byte[] b,
         int o,
         int l)
```
    Read some bytes from the serial port.
    
    This method reads a number of bytes from the serial port.
    
    The return behaviour depends from timeout and other settings. Under certain circumstances this method will wait for input / block indefinitely.
    
    On not ready, errors or timeout -1 will be returned.
    
    Parameters:
    
    b - the buffer to read into
    
    o - the index where to put the first byte read
    
    l - the maximum number of bytes to be read / put into b
    
    Returns:
    
    The number of bytes read or -1
  - write
```
int write(byte[] b,
          int off,
          int len)
```
    Write some bytes to the serial port.
    
    If not ready or if b is null nothing happens at all.
    
    Returns:
    
    -1 on failure or not ready, otherwise the number of bytes written; that will be = len on total success
  - write
```
int write(byte[] b)
```
    Write some bytes to the serial port.
    
    If not ready or if b is null nothing happens at all.
    
    Implementations shall delegate (in case of b not null} to write(b, 0, b.length).
    
    Returns:
    
    -1 on failure or not ready, otherwise the number of bytes written; that will be = b.length on total success
  - write
```
boolean write(int b)
```
    Write one byte to the serial port.
    
    If not ready nothing happens at all.
    
    Returns:
    
    true on success
  - getExMsg
```
String getExMsg()
```
    The last exception's message.
    
    If an operation failed by an exception, this method will deliver the explaining error text.
    
    The same event shall be "explained" only once. Implementations shall clear that text after the first delivery.
    
    Hint: Concurrent (multi-thread) use of serial ports is strongly discouraged anyway.
    
    Returns:
    
    explaining error text or null
  - toString
```
String toString()
```
    Text representation.
    
    The interface's state will be given as a (may be multi-line) text.
    
    If an error is pending according to the method's getExMsg() criteria, its explanation will be part of the status text returned.
    
    Overrides:
    
    toString in class Object

Interface SerialDefs

Nested Class Summary

Field Summary

Method Summary

Field Detail

DATABITS_5

DATABITS_6

DATABITS_7

DATABITS_8

STOPBITS_1

STOPBITS_2

STOPBITS_1_5

PARITY_NONE

PARITY_EVEN

PARITY_ODD

PARITY_MARK

PARITY_SPACE

FLOWCONTROL_NONE

FLOWCONTROL_RTSCTS_IN

FLOWCONTROL_RTSCTS_OUT

FLOWCONTROL_RTSCTS

FLOWCONTROL_XONXOFF_IN

FLOWCONTROL_XONXOFF_OUT

FLOWCONTROL_XONXOFF

OE

PE

FE

BI

CD

RI

DSR

CTS

DATA_AVAILABLE

OUTPUT_BUFFER_EMPTY

Method Detail

getPortName

getRcvTimeout

setRcvTimeout

getBaud

getDataBits

getStopBits

getParity

parityAsString

setSerialPortParams

getFlowControlMode

flowControlAsString

setFlowControlMode

isRTS

setRTS

isDTR

setDTR

setDtrRts

isDSR

isCTS

isCD

isRI

isReady

close

openSerial

read

read

write

write

write

getExMsg

toString