net.springfieldusa.io.serial

Class IOStream

java.lang.Object

net.springfieldusa.io.serial.IOStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

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

This class provides an interface to a native serial IO port. You may configure the serial port with typical settings: baud rate, parity, data bits, stop bits, and flow control. This class also provides wrappers to the standard java.io.InputStream and java.io.OutputStream.

Example usage setting the serial port to 9600 baud and N81:

 
 IOStream stream = new IOStream("/dev/cu.udbserial");
 stream.setBaud(BaudRate.B9600);
 stream.setDataBits(DataBits.EIGHT);
 stream.setParity(Parity.NONE);
 stream.setStopBits(StopBits.ONE);
 stream.setUseFlowControl(FlowControl.NO);
 stream.setReadMode(1, 10);
 
 

Since:

1.0

Author:

bhunt

Constructor Summary

Constructors

Constructor and Description
IOStream(java.lang.String deviceName) Constructs a new IOStream and connects to the serial port.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the serial port.
java.io.InputStream	createInputStream() Creates a java.io.InputStream wrapper around the IOStream.
java.io.OutputStream	createOuputStream() Creates a java.io.OutputStream wrapper around the IOStream.
void	dumpConfig() Prints the serial port configuration to the console.
void	flush(FlushMode mode) Flushes the serial port based on the mode.
int	getStatus() Get the value of the serial port control lines.
int	read(byte[] buffer) Reads data from the serial port.
void	setBaud(BaudRate baudRate) Sets the baud rate on the serial port.
void	setDataBits(DataBits dataBits) Sets the number of data bits on the serial port.
void	setParity(Parity parity) Sets the parity on the serial port.
void	setReadMode(int numberBytesToWaitFor, int timeoutBetweenBytes) Sets the read mode based on the termios man page where MIN is the numberBytesToWaitFor and TIME is the timeoutBetweenBytes
void	setStopBits(StopBits stopBits) Sets the number of stop bits on the serial port.
void	setUseFlowControl(FlowControl mode) Enable or disable RTS/CTS flow control based on the mode.
int	write(byte[] buffer) Writes data to the serial port.

Methods inherited from class java.lang.Object

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

Constructor Detail

IOStream

public IOStream(java.lang.String deviceName)
         throws java.io.IOException

Constructs a new IOStream and connects to the serial port.

Parameters:

deviceName - the system device name - for example: /dev/cu.usbserial

Throws:

java.io.IOException - if there is a problem opening the device

Method Detail

createInputStream

public java.io.InputStream createInputStream()
                                      throws java.io.IOException

Creates a java.io.InputStream wrapper around the IOStream. Calling close on the input stream will NOT close the IOStream.

Returns:

the input stream wraper

Throws:

java.io.IOException - if the IOStream is closed

createOuputStream

public java.io.OutputStream createOuputStream()
                                       throws java.io.IOException

Creates a java.io.OutputStream wrapper around the IOStream. Calling close on the output stream will NOT close the IOStream.

Returns:

the output stream wrapper

Throws:

java.io.IOException - if the IOStream is closed

read

public int read(byte[] buffer)
         throws java.io.IOException

Reads data from the serial port. The size of the buffer is the number of bytes requested from the serial port.

Parameters:

buffer - the data read from the serial port

Returns:

the number of bytes actually read from the serial port

Throws:

java.io.IOException - if there was a problem reading the serial port

write

public int write(byte[] buffer)
          throws java.io.IOException

Writes data to the serial port. The size of the buffer is the number of bytes written to the serial port.

Parameters:

buffer - the data to write to the serial port

Returns:

the number of bytes actually written to the serial port

Throws:

java.io.IOException - if there was a problem writing to the serial port

flush

public void flush(FlushMode mode)
           throws java.io.IOException

Flushes the serial port based on the mode.

Parameters:

mode - the flush mode

Throws:

java.io.IOException - if there was a problem flushing the serial port

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

setBaud

public void setBaud(BaudRate baudRate)
             throws java.io.IOException

Sets the baud rate on the serial port.

Parameters:

baudRate - the baud rate to set

Throws:

java.io.IOException - if there was a problem setting the baud rate

setParity

public void setParity(Parity parity)
               throws java.io.IOException

Sets the parity on the serial port.

Parameters:

parity - the parity to set

Throws:

java.io.IOException - if there was a problem setting the parity

setDataBits

public void setDataBits(DataBits dataBits)
                 throws java.io.IOException

Sets the number of data bits on the serial port.

Parameters:

dataBits - the number of data bits to set

Throws:

java.io.IOException - if there was a problem setting the data bits

setStopBits

public void setStopBits(StopBits stopBits)
                 throws java.io.IOException

Sets the number of stop bits on the serial port.

Parameters:

stopBits - the number of stop bits to set

Throws:

java.io.IOException - if there was a problem setting the stop bits

setUseFlowControl

public void setUseFlowControl(FlowControl mode)
                       throws java.io.IOException

Enable or disable RTS/CTS flow control based on the mode.

Parameters:

mode - the flow control mode to set

Throws:

java.io.IOException - if there was a problem setting the flow control

setReadMode

public void setReadMode(int numberBytesToWaitFor,
                        int timeoutBetweenBytes)
                 throws java.io.IOException

Sets the read mode based on the termios man page where MIN is the numberBytesToWaitFor and TIME is the timeoutBetweenBytes

From man termios:

MIN represents the minimum number of bytes that should be received when the read function successfully returns. TIME is a timer of 0.1 second granularity that is used to time out bursty and short term data transmissions. If MIN is greater than { MAX_INPUT}, the response to the request is undefined. The four possible values for MIN and TIME and their interactions are described below.

Case A: MIN > 0, TIME > 0

In this case TIME serves as an inter-byte timer and is activated after the first byte is received. Since it is an inter-byte timer, it is reset after a byte is received. The interaction between MIN and TIME is as follows: as soon as one byte is received, the inter-byte timer is started. If MIN bytes are received before the inter-byte timer expires (remember that the timer is reset upon receipt of each byte), the read is satisfied. If the timer expires before MIN bytes are received, the characters received to that point are returned to the user. Note that if TIME expires at least one byte is returned because the timer would not have been enabled unless a byte was received. In this case (MIN > 0, TIME > 0) the read blocks until the MIN and TIME mechanisms are activated by the receipt of the first byte, or a signal is received. If data is in the buffer at the time of the read(), the result is as if data had been received immediately after the read().

Case B: MIN > 0, TIME = 0

In this case, since the value of TIME is zero, the timer plays no role and only MIN is significant. A pending read is not satisfied until MIN bytes are received (i.e., the pending read blocks until MIN bytes are received), or a signal is received. A program that uses this case to read record-based terminal I/O may block indefinitely in the read operation.

Case C: MIN = 0, TIME > 0

In this case, since MIN = 0, TIME no longer represents an inter-byte timer. It now serves as a read timer that is activated as soon as the read function is processed. A read is satisfied as soon as a single byte is received or the read timer expires. Note that in this case if the timer expires, no bytes are returned. If the timer does not expire, the only way the read can be satisfied is if a byte is received. In this case the read will not block indefinitely waiting for a byte; if no byte is received within TIME*0.1 seconds after the read is initiated, the read returns a value of zero, having read no data. If data is in the buffer at the time of the read, the timer is started as if data had been received immediately after the read.

Case D: MIN = 0, TIME = 0

The minimum of either the number of bytes requested or the number of bytes currently available is returned without waiting for more bytes to be input. If no characters are available, read returns a value of zero, having read no data.

Parameters:

numberBytesToWaitFor - the number of bytes to wait for before returning from a read

timeoutBetweenBytes - the time to wait for the next byte

Throws:

java.io.IOException - if there was a problem setting the read mode

getStatus

public int getStatus()
              throws java.io.IOException

Get the value of the serial port control lines. Available mainly for debug since the value is platform specific. DSR DTR RTX Secondary TXD Secondary RXD CTS DCD RNG DSR

Returns:

the native bit encoded status

Throws:

java.io.IOException - if there was a problem reading the status

dumpConfig

public void dumpConfig()
                throws java.io.IOException

Prints the serial port configuration to the console. Available mainly for debug.

Throws:

java.io.IOException - if the stream is not open