com.pi4j.io.serial.impl

Class SerialImpl

java.lang.Object

com.pi4j.io.serial.impl.AbstractSerialDataWriter

com.pi4j.io.serial.impl.AbstractSerialDataReaderWriter

com.pi4j.io.serial.impl.SerialImpl

All Implemented Interfaces:

Serial, SerialDataReader, SerialDataWriter, AutoCloseable

public class SerialImpl
extends AbstractSerialDataReaderWriter
implements Serial

This implementation class implements the 'Serial' interface using the WiringPi Serial library.

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:

Serial, SerialDataEvent, SerialDataEventListener, SerialFactory, http://www.pi4j.com/

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	bufferingDataReceived
protected ExecutorService	executor
protected int	fileDescriptor
protected CopyOnWriteArrayList<SerialDataEventListener>	listeners
protected SerialByteBuffer	receiveBuffer

Fields inherited from interface com.pi4j.io.serial.Serial

DEFAULT_COM_PORT, FIRST_USB_COM_PORT, SECOND_USB_COM_PORT

Constructor Summary

Constructors

Constructor and Description
SerialImpl() default constructor

Method Summary

Modifier and Type	Method and Description
void	addListener(SerialDataEventListener... listener) Add Serial Event Listener
int	available() Gets the number of bytes available for reading, or -1 for any error condition.
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.
byte[]	read() Reads all available bytes from the serial port/device.
byte[]	read(int length) Reads a length of bytes from the port/serial device.
void	removeListener(SerialDataEventListener... listener) Remove Serial Event Listener
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.
void	write(byte[] data, int offset, int length) Sends an array of bytes to the serial port/device identified by the given file descriptor.

Methods inherited from class com.pi4j.io.serial.impl.AbstractSerialDataReaderWriter

discardData, read, read, read, read, read, read, read, read, read, read

Methods inherited from class com.pi4j.io.serial.impl.AbstractSerialDataWriter

appendNewLine, write, write, write, write, write, write, write, write, write, write, write, write, write, writeln, writeln, writeln, writeln

Methods inherited from class java.lang.Object

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

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

discardData, 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, writeln, writeln, writeln, writeln

Field Detail

fileDescriptor

protected int fileDescriptor

listeners

protected final CopyOnWriteArrayList<SerialDataEventListener> listeners

executor

protected final ExecutorService executor

receiveBuffer

protected final SerialByteBuffer receiveBuffer

bufferingDataReceived

protected boolean bufferingDataReceived

Constructor Detail

SerialImpl

public SerialImpl()

default constructor

Method Detail

open

public 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.)

Specified by:

open in interface Serial

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:

Serial.DEFAULT_COM_PORT

open

public 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.)

Specified by:

open in interface Serial

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:

Serial.DEFAULT_COM_PORT

open

public 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.)

Specified by:

open in interface Serial

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:

Serial.DEFAULT_COM_PORT

open

public 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.)

Specified by:

open in interface Serial

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:

Serial.DEFAULT_COM_PORT

isOpen

public boolean isOpen()

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

Specified by:

isOpen in interface Serial

Returns:

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

See Also:

open(String, int)

isClosed

public boolean isClosed()

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

Specified by:

isClosed in interface Serial

Returns:

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

See Also:

open(String, int)

close

public void close()
           throws IllegalStateException,
                  IOException

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

Specified by:

close in interface Serial

Specified by:

close in interface AutoCloseable

Throws:

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

IOException - thrown on any error.

flush

public void flush()
           throws IllegalStateException,
                  IOException

Forces the transmission of any remaining data in the serial port transmit buffer. Please note that this does not force the transmission of data, it discards it!

Specified by:

flush in interface Serial

Throws:

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

IOException - thrown on any error.

discardInput

public void discardInput()
                  throws IllegalStateException,
                         IOException

Discards any data in the serial receive (input) buffer. Please note that this does not force the transmission of data, it discards it!

Specified by:

discardInput in interface Serial

Throws:

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

IOException - thrown on any error.

discardOutput

public void discardOutput()
                   throws IllegalStateException,
                          IOException

Discards any data in the serial transmit (output) buffer. Please note that this does not force the transmission of data, it discards it!

Specified by:

discardOutput in interface Serial

Throws:

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

IOException - thrown on any error.

discardAll

public 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!

Specified by:

discardAll in interface Serial

Throws:

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

IOException - thrown on any error.

sendBreak

public void sendBreak(int duration)
               throws IllegalStateException,
                      IOException

Send a BREAK signal to connected device.

Specified by:

sendBreak in interface Serial

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

public 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

Specified by:

sendBreak in interface Serial

Throws:

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

IOException - thrown on any error.

setBreak

public 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.

Specified by:

setBreak in interface Serial

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

public 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.

Specified by:

setRTS in interface Serial

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

public 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.

Specified by:

setDTR in interface Serial

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

public boolean getRTS()
               throws IllegalStateException,
                      IOException

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

Specified by:

getRTS in interface Serial

Throws:

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

IOException - thrown on any error.

getDTR

public boolean getDTR()
               throws IllegalStateException,
                      IOException

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

Specified by:

getDTR in interface Serial

Throws:

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

IOException - thrown on any error.

getCTS

public boolean getCTS()
               throws IllegalStateException,
                      IOException

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

Specified by:

getCTS in interface Serial

Throws:

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

IOException - thrown on any error.

getDSR

public boolean getDSR()
               throws IllegalStateException,
                      IOException

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

Specified by:

getDSR in interface Serial

Throws:

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

IOException - thrown on any error.

getRI

public boolean getRI()
              throws IllegalStateException,
                     IOException

Get the RI (ring-indicator) pin state.

Specified by:

getRI in interface Serial

Throws:

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

IOException - thrown on any error.

getCD

public boolean getCD()
              throws IllegalStateException,
                     IOException

Get the CD (carrier-detect) pin state.

Specified by:

getCD in interface Serial

Throws:

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

IOException - thrown on any error.

available

public int available()
              throws IllegalStateException,
                     IOException

Gets the number of bytes available for reading, or -1 for any error condition.

Specified by:

available in interface SerialDataReader

Specified by:

available in class AbstractSerialDataReaderWriter

Returns:

Returns the number of bytes available for reading, or -1 for any error

Throws:

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

IOException - thrown on any error.

read

public byte[] read()
            throws IllegalStateException,
                   IOException

Reads all available bytes from the serial port/device.

Specified by:

read in interface SerialDataReader

Specified by:

read in class AbstractSerialDataReaderWriter

Returns:

Returns a byte array with the data read from the serial port.

Throws:

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

IOException - thrown on any error.

read

public byte[] read(int length)
            throws IllegalStateException,
                   IOException

Reads a length of bytes from the port/serial device.

Specified by:

read in interface SerialDataReader

Specified by:

read in class AbstractSerialDataReaderWriter

Parameters:

length - The number of bytes to get from the serial port/device. This number must not be higher than the number of available bytes.

Returns:

Returns a byte array with the data read from the serial port.

Throws:

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

IOException - thrown on any error.

write

public void write(byte[] data,
                  int offset,
                  int length)
           throws IllegalStateException,
                  IOException

Sends an array of bytes to the serial port/device identified by the given file descriptor.

Specified by:

write in interface SerialDataWriter

Specified by:

write in class AbstractSerialDataWriter

Parameters:

data - A ByteBuffer of data to be transmitted.

offset - The starting index (inclusive) in the array to send from.

length - The number of bytes from the byte array to transmit to the serial port.

Throws:

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

IOException - thrown on any error.

addListener

public void addListener(SerialDataEventListener... listener)

Add Serial Event Listener

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

Specified by:

addListener in interface Serial

Parameters:

listener - A class instance that implements the SerialListener interface.

See Also:

SerialDataEventListener, SerialDataEvent

removeListener

public void removeListener(SerialDataEventListener... listener)

Remove Serial Event Listener

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

Specified by:

removeListener in interface Serial

Parameters:

listener - A class instance that implements the SerialListener interface.

See Also:

SerialDataEventListener, SerialDataEvent

getFileDescriptor

public int getFileDescriptor()

This method returns the serial device file descriptor

Specified by:

getFileDescriptor in interface Serial

Returns:

fileDescriptor file descriptor

getInputStream

public InputStream getInputStream()

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

Specified by:

getInputStream in interface Serial

Returns:

InputStream input stream

getOutputStream

public OutputStream getOutputStream()

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

Specified by:

getOutputStream in interface Serial

Returns:

OutputStream output stream

isBufferingDataReceived

public boolean isBufferingDataReceived()

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

Specified by:

isBufferingDataReceived in interface Serial

Returns:

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

setBufferingDataReceived

public 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.

Specified by:

setBufferingDataReceived in interface Serial

Parameters:

enabled - sets the buffering behavior state