serial

## Class Serial

- java.lang.Object
- - serial.Serial

All Implemented Interfaces:
  java.io.Closeable, java.lang.AutoCloseable

    public class Serial
    extends java.lang.Object
    implements java.io.Closeable

Serial Port. Created by chzhong on 1/20/16.

### Nested Class Summary

Nested Classes
`static class` `Serial.Builder` Builder for `Serial`.

### Field Summary

Fields
`static int` `BAUDRATE_110` Baudrate 110 bits/s.
`static int` `BAUDRATE_115200` Baudrate 115200 bits/s.
`static int` `BAUDRATE_1200` Baudrate 1200 bits/s.
`static int` `BAUDRATE_128000` Baudrate 128000 bits/s.
`static int` `BAUDRATE_14400` Baudrate 14400 bits/s.
`static int` `BAUDRATE_153600` Baudrate 153600 bits/s.
`static int` `BAUDRATE_230400` Baudrate 230400 bits/s.
`static int` `BAUDRATE_2400` Baudrate 2400 bits/s.
`static int` `BAUDRATE_256000` Baudrate 256000 bits/s.
`static int` `BAUDRATE_28800` Baudrate 28800 bits/s.
`static int` `BAUDRATE_300` Baudrate 300 bits/s.
`static int` `BAUDRATE_38400` Baudrate 38400 bits/s.
`static int` `BAUDRATE_460800` Baudrate 460800 bits/s.
`static int` `BAUDRATE_4800` Baudrate 4800 bits/s.
`static int` `BAUDRATE_56000` Baudrate 56000 bits/s.
`static int` `BAUDRATE_57600` Baudrate 57600 bits/s.
`static int` `BAUDRATE_600` Baudrate 600 bits/s.
`static int` `BAUDRATE_921600` Baudrate 921600 bits/s.
`static int` `BAUDRATE_9600` Baudrate 9600 bits/s.
`static java.nio.charset.Charset` `CHARSET_DEFAULT` Default charset.
`static java.nio.charset.Charset` `CHARSET_ISO_8859_1` ISO-8859-1 charset.
`static java.nio.charset.Charset` `CHARSET_US_ASCII` US-ASCII charset.
`static java.nio.charset.Charset` `CHARSET_UTF16` UTF-16 charset.
`static java.nio.charset.Charset` `CHARSET_UTF16BE` UTF-16BE charset.
`static java.nio.charset.Charset` `CHARSET_UTF16LE` UTF-16LE charset.
`static java.nio.charset.Charset` `CHARSET_UTF8` UTF-8 charset.
`static java.lang.String` `EOL_CR` End-of-line: carriage-return (\n).
`static java.lang.String` `EOL_CRLF` End-of-line: CR & LF (\r\n).
`static java.lang.String` `EOL_LF` End-of-line: line-feed (\n).

### Method Summary

Methods
`int` `available()` Return the number of characters in the buffer.
`void` `close()` Closes the serial port.
`protected void` `finalize()`
`void` `flush()` Flush the input and output buffers
`void` `flushInput()` Flush only the input buffer
`void` `flushOutput()` Flush only the output buffer
`int` `getBaudrate()` Gets the baudrate for the serial port.
`ByteSize` `getBytesize()` Gets the bytesize for the serial port.
`boolean` `getCD()` Returns the current status of the CD line.
`boolean` `getCTS()`
`boolean` `getDSR()` Returns the current status of the DSR line.
`FlowControl` `getFlowcontrol()` Gets the flow control for the serial port.
`Parity` `getParity()` Gets the parity for the serial port.
`java.lang.String` `getPort()` Gets the serial port identifier.
`boolean` `getRI()` Returns the current status of the RI line.
`Stopbits` `getStopbits()` Gets the stopbits for the serial port.
`Timeout` `getTimeout()` Gets the timeout for reads in seconds.
`boolean` `isOpen()` Gets the open status of the serial port.
`boolean` `isValid()` Determine whether this instance has a valid port.
`static PortInfo[]` `listPorts()` List available ports on this device.
`void` `open()` Opens the serial port as long as the port is set and the port isn't already open.
`byte[]` `read()` Read all data available from the serial port.
`int` `read(byte[] buffer, int offset, int size)` Read a given amount of bytes from the serial port into a given buffer.
`int` `read(java.nio.ByteBuffer buffer, int size)` Read a given amount of bytes from the serial port into a give buffer.
`java.lang.String` `read(int size, java.nio.charset.Charset charset)` Read a given amount of bytes from the serial port and return a string containing the data.
`int` `read(java.lang.StringBuilder buffer, int size, java.nio.charset.Charset charset)` Read a given amount of bytes from the serial port into a give buffer.
`java.lang.String` `readline(int size, java.lang.String eol)` Reads in a line or until a given delimiter has been processed.
`int` `readline(java.lang.StringBuilder buffer, int size, java.lang.String eol)` Reads in a line or until a given delimiter has been processed.
`java.lang.String[]` `readlines(int size, java.lang.String eol)` Reads in multiple lines until the serial port times out.
`void` `sendBreak(int duration)` Sends the RS-232 break signal.
`void` `setBaudrate(int baudrate)` Sets the baudrate for the serial port.
`void` `setBreak()` Set the break condition to true level.
`void` `setBreak(boolean level)` Set the break condition to a given level.
`void` `setBytesize(ByteSize bytesize)` Sets the bytesize for the serial port.
`void` `setDTR()` Set the DTR handshaking line to the given level.
`void` `setDTR(boolean level)` Set the DTR handshaking line to the given level.
`void` `setFlowcontrol(FlowControl flowcontrol)` Sets the flow control for the serial port.
`void` `setParity(Parity parity)` Sets the parity for the serial port.
`void` `setPort(java.lang.String port)` Sets the serial port identifier.
`void` `setRTS()` Set the RTS handshaking line to the true level.
`void` `setRTS(boolean level)` Set the RTS handshaking line to the given level.
`void` `setStopbits(Stopbits stopbits)` Sets the stopbits for the serial port.
`void` `setTimeout(int inter_byte_timeout, int read_timeout_constant, int read_timeout_multiplier, int write_timeout_constant, int write_timeout_multiplier)` Sets the timeout for reads and writes.
`void` `setTimeout(Timeout timeout)` Sets the timeout for reads and writes using the Timeout struct.
`void` `waitByteTimes(int count)` Block for a period of time corresponding to the transmission time of count characters at present serial settings.
`boolean` `waitForChange()` Blocks until CTS, DSR, RI, CD changes or something interrupts it.
`boolean` `waitReadable()` Block until there is serial data to read or read_timeout_constant number of milliseconds have elapsed.
`int` `write(byte[] data, int size)` Write a string to the serial port.
`int` `write(java.lang.String s)` Write a string to the serial port.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### BAUDRATE_110

    public static final int BAUDRATE_110

Baudrate 110 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_300

    public static final int BAUDRATE_300

Baudrate 300 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_600

    public static final int BAUDRATE_600

Baudrate 600 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_1200

    public static final int BAUDRATE_1200

Baudrate 1200 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_2400

    public static final int BAUDRATE_2400

Baudrate 2400 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_4800

    public static final int BAUDRATE_4800

Baudrate 4800 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_9600

    public static final int BAUDRATE_9600

Baudrate 9600 bits/s. This is the default.

See Also:
  Constant Field Values

#### BAUDRATE_14400

    public static final int BAUDRATE_14400

Baudrate 14400 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_28800

    public static final int BAUDRATE_28800

Baudrate 28800 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_38400

    public static final int BAUDRATE_38400

Baudrate 38400 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_56000

    public static final int BAUDRATE_56000

Baudrate 56000 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_57600

    public static final int BAUDRATE_57600

Baudrate 57600 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_115200

    public static final int BAUDRATE_115200

Baudrate 115200 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_128000

    public static final int BAUDRATE_128000

Baudrate 128000 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_153600

    public static final int BAUDRATE_153600

Baudrate 153600 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_230400

    public static final int BAUDRATE_230400

Baudrate 230400 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_256000

    public static final int BAUDRATE_256000

Baudrate 256000 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_460800

    public static final int BAUDRATE_460800

Baudrate 460800 bits/s.

See Also:
  Constant Field Values

#### BAUDRATE_921600

    public static final int BAUDRATE_921600

Baudrate 921600 bits/s.

See Also:
  Constant Field Values

#### EOL_LF

    public static final java.lang.String EOL_LF

End-of-line: line-feed (\n). This is the default.

See Also:
  Constant Field Values

#### EOL_CR

    public static final java.lang.String EOL_CR

End-of-line: carriage-return (\n).

See Also:
  Constant Field Values

#### EOL_CRLF

    public static final java.lang.String EOL_CRLF

End-of-line: CR & LF (\r\n).

See Also:
  Constant Field Values

#### CHARSET_DEFAULT

    public static final java.nio.charset.Charset CHARSET_DEFAULT

Default charset.

#### CHARSET_UTF8

    public static final java.nio.charset.Charset CHARSET_UTF8

UTF-8 charset.

#### CHARSET_ISO_8859_1

    public static final java.nio.charset.Charset CHARSET_ISO_8859_1

ISO-8859-1 charset.

#### CHARSET_US_ASCII

    public static final java.nio.charset.Charset CHARSET_US_ASCII

US-ASCII charset.

#### CHARSET_UTF16

    public static final java.nio.charset.Charset CHARSET_UTF16

UTF-16 charset.

#### CHARSET_UTF16LE

    public static final java.nio.charset.Charset CHARSET_UTF16LE

UTF-16LE charset.

#### CHARSET_UTF16BE

    public static final java.nio.charset.Charset CHARSET_UTF16BE

UTF-16BE charset.

### Method Detail

#### listPorts

    public static PortInfo[] listPorts()

List available ports on this device.

Returns:
  an array of available ports.

#### finalize

    protected void finalize()
                     throws java.lang.Throwable

Overrides:
  `finalize` in class `java.lang.Object`
Throws:
  `java.lang.Throwable`

#### isValid

    public boolean isValid()

Determine whether this instance has a valid port.

Returns:
  true if native port is valid, false otherwise.

#### open

    public void open()
              throws SerialIOException

Opens the serial port as long as the port is set and the port isn't already open. If the port is provided to the constructor then an explicit call to open is not needed.

Throws:
  `SerialException` - Generic serial error.
  `SerialIOException` - I/O error.
  `java.lang.IllegalArgumentException` - Invalid arguments are given.
See Also:
  `Serial(String, int, Timeout, ByteSize, Parity, Stopbits, FlowControl)`

#### isOpen

    public boolean isOpen()

Gets the open status of the serial port.

Returns:
  Returns true if the port is open, false otherwise.

#### close

    public void close()
               throws java.io.IOException

Closes the serial port.

Specified by:
  `close` in interface `java.io.Closeable`
Specified by:
  `close` in interface `java.lang.AutoCloseable`
Throws:
  `java.io.IOException` - I/O error.

#### available

    public int available()
                  throws SerialIOException

Return the number of characters in the buffer.

Throws:
  `SerialIOException` - I/O Error.

#### waitReadable

    public boolean waitReadable()
                         throws SerialIOException

Block until there is serial data to read or read_timeout_constant number of milliseconds have elapsed. The return value is true when the function exits with the port in a readable state, false otherwise (due to timeout or select interruption).

Throws:
  `SerialIOException` - I/O Error.

#### waitByteTimes

    public void waitByteTimes(int count)

Block for a period of time corresponding to the transmission time of count characters at present serial settings. This may be used in con- junction with waitReadable to read larger blocks of data from the port.

#### read

    public int read(byte[] buffer,
           int offset,
           int size)
             throws SerialIOException

Read a given amount of bytes from the serial port into a given buffer. The read function will return in one of three cases: * The number of requested bytes was read. * In this case the number of bytes requested will match the size_t returned by read. * A timeout occurred, in this case the number of bytes read will not match the amount requested, but no exception will be thrown. One of two possible timeouts occurred: * The inter byte timeout expired, this means that number of milliseconds elapsed between receiving bytes from the serial port exceeded the inter byte timeout. * The total timeout expired, which is calculated by multiplying the read timeout multiplier by the number of requested bytes and then added to the read timeout constant. If that total number of milliseconds elapses after the initial call to read a timeout will occur. * An exception occurred, in this case an actual exception will be thrown.

Parameters:
  `buffer` - An array of at least the requested size.
  `offset` - the offset of the buffer to receive data.
  `size` - how many bytes to be read.
Returns:
  A size_t representing the number of bytes read as a result of the call to read.
Throws:
  `SerialIOException` - I/O Error.

#### read

    public byte[] read()
                throws SerialIOException

Read all data available from the serial port.

Returns:
  A buffer that contains all available data.
Throws:
  `SerialIOException` - I/O Error.

#### read

    public int read(java.nio.ByteBuffer buffer,
           int size)
             throws SerialIOException

Read a given amount of bytes from the serial port into a give buffer.

Parameters:
  `buffer` - A reference to a std::vector of uint8_t.
  `size` - A size_t defining how many bytes to be read.
Returns:
  A size_t representing the number of bytes read as a result of the call to read.
Throws:
  `SerialIOException` - I/O Error.

#### read

    public int read(java.lang.StringBuilder buffer,
           int size,
           java.nio.charset.Charset charset)
             throws SerialIOException

Read a given amount of bytes from the serial port into a give buffer.

Parameters:
  `buffer` - A reference to a std::string.
  `size` - A size_t defining how many bytes to be read.
  `charset` - The charset of the data.
Returns:
  A size_t representing the number of bytes read as a result of the call to read.
Throws:
  `SerialIOException` - I/O Error.

#### read

    public java.lang.String read(int size,
                        java.nio.charset.Charset charset)
                          throws SerialIOException

Read a given amount of bytes from the serial port and return a string containing the data.

Parameters:
  `size` - A size_t defining how many bytes to be read.
Returns:
  A std::string containing the data read from the port.
Throws:
  `SerialIOException` - I/O Error.

#### readline

    public int readline(java.lang.StringBuilder buffer,
               int size,
               java.lang.String eol)
                 throws SerialIOException

Reads in a line or until a given delimiter has been processed. Reads from the serial port until a single line has been read.

Parameters:
  `buffer` - A std::string reference used to store the data.
  `size` - A maximum length of a line, defaults to 65536 (2^16)
  `eol` - A string to match against for the EOL.
Returns:
  A size_t representing the number of bytes read.
Throws:
  `SerialIOException` - I/O Error.

#### readline

    public java.lang.String readline(int size,
                            java.lang.String eol)
                              throws SerialIOException

Reads in a line or until a given delimiter has been processed. Reads from the serial port until a single line has been read.

Parameters:
  `size` - A maximum length of a line, defaults to 65536 (2^16)
  `eol` - A string to match against for the EOL.
Returns:
  A std::string containing the line.
Throws:
  `SerialIOException` - I/O Error.

#### readlines

    public java.lang.String[] readlines(int size,
                               java.lang.String eol)
                                 throws SerialIOException

Reads in multiple lines until the serial port times out. This requires a timeout > 0 before it can be run. It will read until a timeout occurs and return a list of strings.

Parameters:
  `size` - A maximum length of combined lines, defaults to 65536 (2^16)
  `eol` - A string to match against for the EOL.
Returns:
  A array containing the lines.
Throws:
  `SerialIOException` - I/O Error.

#### write

    public int write(byte[] data,
            int size)
              throws SerialIOException

Write a string to the serial port.

Parameters:
  `data` - A const reference containing the data to be written to the serial port.
  `size` - A size_t that indicates how many bytes should be written from the given data buffer.
Returns:
  A size_t representing the number of bytes actually written to the serial port.
Throws:
  `SerialIOException` - I/O Error.

#### write

    public int write(java.lang.String s)
              throws SerialIOException

Write a string to the serial port.

Parameters:
  `s` - A const reference containing the data to be written to the serial port.
Returns:
  A size_t representing the number of bytes actually written to the serial port.
Throws:
  `SerialIOException` - I/O Error.

#### setPort

    public void setPort(java.lang.String port)

Sets the serial port identifier.

Parameters:
  `port` - A const std::string reference containing the address of the serial port, which would be something like 'COM1' on Windows and '/dev/ttyS0' on Linux.
Throws:
  `java.lang.IllegalArgumentException`

#### getPort

    public java.lang.String getPort()

Gets the serial port identifier.

See Also:
  `setPort(String)`

#### setTimeout

    public void setTimeout(Timeout timeout)

Sets the timeout for reads and writes using the Timeout struct. There are two timeout conditions described here: * The inter byte timeout: * The inter_byte_timeout component of serial::Timeout defines the maximum amount of time, in milliseconds, between receiving bytes on the serial port that can pass before a timeout occurs. Setting this to zero will prevent inter byte timeouts from occurring. * Total time timeout: * The constant and multiplier component of this timeout condition, for both read and write, are defined in serial::Timeout. This timeout occurs if the total time since the read or write call was made exceeds the specified time in milliseconds. * The limit is defined by multiplying the multiplier component by the number of requested bytes and adding that product to the constant component. In this way if you want a read call, for example, to timeout after exactly one second regardless of the number of bytes you asked for then set the read_timeout_constant component of serial::Timeout to 1000 and the read_timeout_multiplier to zero. This timeout condition can be used in conjunction with the inter byte timeout condition with out any problems, timeout will simply occur when one of the two timeout conditions is met. This allows users to have maximum control over the trade-off between responsiveness and efficiency. Read and write functions will return in one of three cases. When the reading or writing is complete, when a timeout occurs, or when an exception occurs.

Parameters:
  `timeout` - A serial::Timeout struct containing the inter byte timeout, and the read and write timeout constants and multipliers.
See Also:
  `Timeout`

#### setTimeout

    public void setTimeout(int inter_byte_timeout,
                  int read_timeout_constant,
                  int read_timeout_multiplier,
                  int write_timeout_constant,
                  int write_timeout_multiplier)

Sets the timeout for reads and writes.

#### getTimeout

    public Timeout getTimeout()

Gets the timeout for reads in seconds.

Returns:
  A Timeout struct containing the inter_byte_timeout, and read and write timeout constants and multipliers.
See Also:
  `setTimeout(Timeout)`

#### setBaudrate

    public void setBaudrate(int baudrate)
                     throws SerialIOException

Sets the baudrate for the serial port. Possible baudrates depends on the system but some safe baudrates include: 110, 300, 600, 1200, 2400, 4800, 9600 (default), 14400, 19200, 28800, 38400, 56000, 57600, 115200 Some other baudrates that are supported by some comports: 128000, 153600, 230400, 256000, 460800, 921600

Parameters:
  `baudrate` - An integer that sets the baud rate for the serial port.
Throws:
  `SerialIOException` - I/O Error.

#### getBaudrate

    public int getBaudrate()

Gets the baudrate for the serial port.

Returns:
  An integer that sets the baud rate for the serial port.
See Also:
  `setBaudrate(int)`

#### setBytesize

    public void setBytesize(ByteSize bytesize)
                     throws SerialIOException

Sets the bytesize for the serial port.

Parameters:
  `bytesize` - Size of each byte in the serial transmission of data, default is eightbits, possible values are: fivebits, sixbits, sevenbits, eightbits
Throws:
  `SerialIOException` - I/O Error.

#### getBytesize

    public ByteSize getBytesize()

Gets the bytesize for the serial port.

See Also:
  `setBytesize(ByteSize)`

#### setParity

    public void setParity(Parity parity)
                   throws SerialIOException

Sets the parity for the serial port.

Parameters:
  `parity` - Method of parity, default is parity_none, possible values are: parity_none, parity_odd, parity_even
Throws:
  `SerialIOException` - I/O Error.

#### getParity

    public Parity getParity()

Gets the parity for the serial port.

See Also:
  `setParity(Parity)`

#### setStopbits

    public void setStopbits(Stopbits stopbits)
                     throws SerialIOException

Sets the stopbits for the serial port.

Parameters:
  `stopbits` - Number of stop bits used, default is stopbits_one, possible values are: stopbits_one, stopbits_one_point_five, stopbits_two
Throws:
  `SerialIOException` - I/O Error.

#### getStopbits

    public Stopbits getStopbits()

Gets the stopbits for the serial port.

See Also:
  `setStopbits(Stopbits)`

#### setFlowcontrol

    public void setFlowcontrol(FlowControl flowcontrol)
                        throws SerialIOException

Sets the flow control for the serial port.

Parameters:
  `flowcontrol` - Type of flowcontrol used, default is flowcontrol_none, possible values are: flowcontrol_none, flowcontrol_software, flowcontrol_hardware
Throws:
  `SerialIOException` - I/O Error.

#### getFlowcontrol

    public FlowControl getFlowcontrol()

Gets the flow control for the serial port.

See Also:
  `setFlowcontrol(FlowControl)`

#### flush

    public void flush()

Flush the input and output buffers

#### flushInput

    public void flushInput()

Flush only the input buffer

#### flushOutput

    public void flushOutput()

Flush only the output buffer

#### sendBreak

    public void sendBreak(int duration)

Sends the RS-232 break signal. See tcsendbreak(3).

#### setBreak

    public void setBreak(boolean level)

Set the break condition to a given level.

#### setBreak

    public void setBreak()

Set the break condition to true level.

#### setRTS

    public void setRTS(boolean level)

Set the RTS handshaking line to the given level.

#### setRTS

    public void setRTS()

Set the RTS handshaking line to the true level.

#### setDTR

    public void setDTR(boolean level)

Set the DTR handshaking line to the given level.

#### setDTR

    public void setDTR()

Set the DTR handshaking line to the given level.

#### waitForChange

    public boolean waitForChange()

Blocks until CTS, DSR, RI, CD changes or something interrupts it. Can throw an exception if an error occurs while waiting. You can check the status of CTS, DSR, RI, and CD once this returns. Uses TIOCMIWAIT via ioctl if available (mostly only on Linux) with a resolution of less than +-1ms and as good as +-0.2ms. Otherwise a polling method is used which can give +-2ms.

Returns:
  Returns true if one of the lines changed, false if something else occurred.
Throws:
  `SerialException`

#### getCTS

    public boolean getCTS()

#### getDSR

    public boolean getDSR()

Returns the current status of the DSR line.

#### getRI

    public boolean getRI()

Returns the current status of the RI line.

#### getCD

    public boolean getCD()

Returns the current status of the CD line.