com.pi4j.io.serial

Interface Serial

All Superinterfaces:

AutoCloseable, SerialDataReader, SerialDataWriter

All Known Implementing Classes:

SerialImpl

public interface Serial
extends SerialDataReader, SerialDataWriter, AutoCloseable

This interface provides a set of functions for 'Serial' communication.

Before using the Pi4J library, you need to ensure that the Java VM in configured with access to the following system libraries:

• pi4j
• wiringPi

This library depends on the wiringPi native system library.
(developed by Gordon Henderson @ http://wiringpi.com/)

Author:

Robert Savage (http://www.savagehomeautomation.com)

See Also:

SerialFactory, SerialDataEvent, SerialDataEventListener, https://www.pi4j.com/

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_COM_PORT The default hardware COM port provided via the Raspberry Pi GPIO header.
static String	FIRST_USB_COM_PORT
static String	PRIMARY_COM_PORT
static String	SECOND_USB_COM_PORT
static String	SECONDARY_COM_PORT

Method Summary

Modifier and Type	Method and Description
void	addListener(SerialDataEventListener... listener) Java consumer code can call this method to register itself as a listener for serial data events.
void	close() This method is called to close a currently open open serial port.
void	discardAll() Discards any data in both the serial receive and transmit buffers.
void	discardInput() Discards any data in the serial receive (input) buffer.
void	discardOutput() Discards any data in the serial transmit (output) buffer.
void	flush() Forces the transmission of any remaining data in the serial port transmit buffer.
boolean	getCD() Get the CD (carrier-detect) pin state.
boolean	getCTS() Get the CTS (clean-to-send) pin state.
boolean	getDSR() Get the DSR (data-set-ready) pin state.
boolean	getDTR() Get the DTR (data-terminal-ready) pin state.
int	getFileDescriptor() This method returns the serial device file descriptor
InputStream	getInputStream() This method returns the input data stream for the serial port's receive buffer
OutputStream	getOutputStream() This method returns the output data stream for the serial port's transmit buffer
boolean	getRI() Get the RI (ring-indicator) pin state.
boolean	getRTS() Get the RTS (request-to-send) pin state.
boolean	isBufferingDataReceived() This method returns the buffering state for data received from the serial device/port.
boolean	isClosed() This method is called to determine if the serial port is already closed.
boolean	isOpen() This method is called to determine if the serial port is already open.
void	open(SerialConfig serialConfig) This opens and initializes the serial port/device and sets the communication parameters.
void	open(String device, Baud baud, DataBits dataBits, Parity parity, StopBits stopBits, FlowControl flowControl) This opens and initializes the serial port/device and sets the communication parameters.
void	open(String device, int baud) This opens and initializes the serial port/device and sets the communication parameters.
void	open(String device, int baud, int dataBits, int parity, int stopBits, int flowControl) This opens and initializes the serial port/device and sets the communication parameters.
void	removeListener(SerialDataEventListener... listener) Java consumer code can call this method to unregister itself as a listener for serial data events.
void	sendBreak() Send a BREAK signal to connected device for at least 0.25 seconds, and not more than 0.5 seconds
void	sendBreak(int duration) Send a BREAK signal to connected device.
void	setBreak(boolean enabled) Send a constant BREAK signal to connected device.
void	setBufferingDataReceived(boolean enabled) This method controls the buffering state for data received from the serial device/port.
void	setDTR(boolean enabled) Control the DTR (data-terminal-ready) pin state.
void	setRTS(boolean enabled) Control the RTS (request-to-send) pin state.

Methods inherited from interface com.pi4j.io.serial.SerialDataReader

available, discardData, read, read, read, read, read, read, read, read, read, read, read, read

Methods inherited from interface com.pi4j.io.serial.SerialDataWriter

write, write, write, write, write, write, write, write, write, write, write, write, write, write, writeln, writeln, writeln, writeln

Field Detail

DEFAULT_COM_PORT

static final String DEFAULT_COM_PORT

The default hardware COM port provided via the Raspberry Pi GPIO header.

See Also:

open(String, int), Constant Field Values

FIRST_USB_COM_PORT

static final String FIRST_USB_COM_PORT

See Also:

Constant Field Values

SECOND_USB_COM_PORT

static final String SECOND_USB_COM_PORT

See Also:

Constant Field Values

PRIMARY_COM_PORT

static final String PRIMARY_COM_PORT

See Also:

Constant Field Values

SECONDARY_COM_PORT

static final String SECONDARY_COM_PORT

See Also:

Constant Field Values

Method Detail

open

void open(String device,
          int baud,
          int dataBits,
          int parity,
          int stopBits,
          int flowControl)
   throws IOException

This opens and initializes the serial port/device and sets the communication parameters. It sets the port into raw mode (character at a time and no translations).

(ATTENTION: the 'device' argument can only be a maximum of 128 characters.)

Parameters:

device - The device address of the serial port to access. You can use constant 'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the GPIO header.

baud - The baud rate to use with the serial port. (Custom baud rate are not supported)

dataBits - The data bits to use for serial communication. (5,6,7,8)

parity - The parity setting to use for serial communication. (None, Event, Odd, Mark, Space)

stopBits - The stop bits to use for serial communication. (1,2)

flowControl - The flow control option to use for serial communication. (none, hardware, software)

Throws:

IOException - thrown on any error.

See Also:

DEFAULT_COM_PORT

open

void open(String device,
          int baud)
   throws IOException

This opens and initializes the serial port/device and sets the communication parameters. It sets the port into raw mode (character at a time and no translations). This method will use the following default serial configuration parameters: - DATA BITS = 8 - PARITY = NONE - STOP BITS = 1 - FLOW CONTROL = NONE

(ATTENTION: the 'device' argument can only be a maximum of 128 characters.)

Parameters:

device - The device address of the serial port to access. You can use constant 'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the GPIO header.

baud - The baud rate to use with the serial port.

Throws:

IOException - thrown on any error.

See Also:

DEFAULT_COM_PORT

open

void open(String device,
          Baud baud,
          DataBits dataBits,
          Parity parity,
          StopBits stopBits,
          FlowControl flowControl)
   throws IOException

This opens and initializes the serial port/device and sets the communication parameters. It sets the port into raw mode (character at a time and no translations).

(ATTENTION: the 'device' argument can only be a maximum of 128 characters.)

Parameters:

device - The device address of the serial port to access. You can use constant 'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the GPIO header.

baud - The baud rate to use with the serial port.

dataBits - The data bits to use for serial communication. (5,6,7,8)

parity - The parity setting to use for serial communication. (None, Event, Odd, Mark, Space)

stopBits - The stop bits to use for serial communication. (1,2)

flowControl - The flow control option to use for serial communication. (none, hardware, software)

Throws:

IOException - thrown on any error.

See Also:

DEFAULT_COM_PORT

open

void open(SerialConfig serialConfig)
   throws IOException

This opens and initializes the serial port/device and sets the communication parameters. It sets the port into raw mode (character at a time and no translations).

(ATTENTION: the 'device' argument can only be a maximum of 128 characters.)

Parameters:

serialConfig - A serial configuration object that contains the device, baud rate, data bits, parity, stop bits, and flow control settings.

Throws:

IOException - thrown on any error.

See Also:

DEFAULT_COM_PORT

close

void close()
    throws IllegalStateException,
           IOException

This method is called to close a currently open open serial port.

Specified by:

close in interface AutoCloseable

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

isOpen

boolean isOpen()

This method is called to determine if the serial port is already open.

Returns:

a value of 'true' is returned if the serial port is already open.

See Also:

open(String, int)

isClosed

boolean isClosed()

This method is called to determine if the serial port is already closed.

Returns:

a value of 'true' is returned if the serial port is already in the closed state.

See Also:

open(String, int)

flush

void flush()
    throws IllegalStateException,
           IOException

Forces the transmission of any remaining data in the serial port transmit buffer.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

discardInput

void discardInput()
           throws IllegalStateException,
                  IOException

Discards any data in the serial receive (input) buffer.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

discardOutput

void discardOutput()
            throws IllegalStateException,
                   IOException

Discards any data in the serial transmit (output) buffer.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

discardAll

void discardAll()
         throws IllegalStateException,
                IOException

Discards any data in both the serial receive and transmit buffers. Please note that this does not force the transmission of data, it discards it!

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

sendBreak

void sendBreak(int duration)
        throws IllegalStateException,
               IOException

Send a BREAK signal to connected device.

Parameters:

duration - The length of time (milliseconds) to send the BREAK signal

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

sendBreak

void sendBreak()
        throws IllegalStateException,
               IOException

Send a BREAK signal to connected device for at least 0.25 seconds, and not more than 0.5 seconds

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

setBreak

void setBreak(boolean enabled)
       throws IllegalStateException,
              IOException

Send a constant BREAK signal to connected device. (Turn break on/off) When enabled this will send a steady stream of zero bits. When enabled, no (other) data transmitting is possible.

Parameters:

enabled - The enable or disable state to control the BREAK signal

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

setRTS

void setRTS(boolean enabled)
     throws IllegalStateException,
            IOException

Control the RTS (request-to-send) pin state. When enabled this will set the RTS pin to the HIGH state.

Parameters:

enabled - The enable or disable state to control the RTS pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

setDTR

void setDTR(boolean enabled)
     throws IllegalStateException,
            IOException

Control the DTR (data-terminal-ready) pin state. When enabled this will set the DTR pin to the HIGH state.

Parameters:

enabled - The enable or disable state to control the RTS pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getRTS

boolean getRTS()
        throws IllegalStateException,
               IOException

Get the RTS (request-to-send) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getDTR

boolean getDTR()
        throws IllegalStateException,
               IOException

Get the DTR (data-terminal-ready) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getCTS

boolean getCTS()
        throws IllegalStateException,
               IOException

Get the CTS (clean-to-send) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getDSR

boolean getDSR()
        throws IllegalStateException,
               IOException

Get the DSR (data-set-ready) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getRI

boolean getRI()
       throws IllegalStateException,
              IOException

Get the RI (ring-indicator) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

getCD

boolean getCD()
       throws IllegalStateException,
              IOException

Get the CD (carrier-detect) pin state.

Throws:

IllegalStateException - thrown if the serial port is not already open.

IOException - thrown on any error.

addListener

void addListener(SerialDataEventListener... listener)

Java consumer code can call this method to register itself as a listener for serial data events.

Parameters:

listener - A class instance that implements the SerialListener interface.

See Also:

SerialDataEventListener, SerialDataEvent

removeListener

void removeListener(SerialDataEventListener... listener)

Java consumer code can call this method to unregister itself as a listener for serial data events.

Parameters:

listener - A class instance that implements the SerialListener interface.

See Also:

SerialDataEventListener, SerialDataEvent

getFileDescriptor

int getFileDescriptor()

This method returns the serial device file descriptor

Returns:

fileDescriptor file descriptor

getInputStream

InputStream getInputStream()

This method returns the input data stream for the serial port's receive buffer

Returns:

InputStream input stream

getOutputStream

OutputStream getOutputStream()

This method returns the output data stream for the serial port's transmit buffer

Returns:

OutputStream output stream

isBufferingDataReceived

boolean isBufferingDataReceived()

This method returns the buffering state for data received from the serial device/port.

Returns:

'true' if buffering is enabled; else 'false'

setBufferingDataReceived

void setBufferingDataReceived(boolean enabled)

This method controls the buffering state for data received from the serial device/port.

If the buffering state is enabled, then all data bytes received from the serial port will get copied into a data receive buffer. You can use the 'getInputStream()' or and of the 'read()' methods to access this data. The data will also be available via the 'SerialDataEvent' event. It is important to know that if you are using data buffering, the data will continue to grow in memory until your program consume it from the data reader/stream.

If the buffering state is disabled, then all data bytes received from the serial port will NOT get copied into the data receive buffer, but will be included in the 'SerialDataEvent' event's data payload. If you program does not care about or use data received from the serial port, then you should disable the data buffering state to prevent memory waste/leak.

Parameters:

enabled - Sets the buffering behavior state.