ewe.io
Class SerialPort

java.lang.Object
  ewe.util.Errorable
      ewe.io.BasicStreamObject
          ewe.io.StreamObject
              ewe.io.SerialPort

All Implemented Interfaces:

BasicStream, OverridesClose, Stream, Streamable, StreamCanPause

public class SerialPort

extends StreamObject

implements StreamCanPause, OverridesClose

SerialPort accesses a device's or PC's serial port.

Serial port access under Java on a PC requires the Dynamic Link Library java_ewe.dll

When a serial port is created, an attempt is made to open the port. If the open attempt is successful, a call to isOpen() will return true and the port will remain open until close() is called. If close() is never called, the port will be closed when the object is garbage collected.

Use the SerialPort as you would any other Stream. It is fully asynchronous.

Field Summary

static int	EVENPARITY
static int	HARDWARE_FLOW_CONTROL
static int	MARKPARITY
static int	NO_FLOW_CONTROL
static int	NOPARITY
static int	ODDPARITY
static int	SOFTWARE_FLOW_CONTROL
static int	SPACEPARITY

Fields inherited from class ewe.io.StreamObject

napIterations, napTime, READWRITE_CLOSED, READWRITE_ERROR, READWRITE_WOULDBLOCK

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Fields inherited from interface ewe.io.StreamCanPause

PAUSE_UNTIL_CAN_READ, PAUSE_UNTIL_CAN_WRITE, PAUSE_UNTIL_CLOSED, PAUSE_UNTIL_FLUSHED

Constructor Summary

SerialPort(int number, int baudRate)
Open a serial port with settings of 8 bits, no parity and 1 stop bit.

SerialPort(int number, int baudRate, int bits, int parity, int stopBits)
Opens a serial port.

SerialPort(SerialPortSpecs options)
Create a new open SerialPort.

SerialPort(String name, int baudRate)
Open a serial port with settings of 8 bits, no parity and 1 stop bit.

SerialPort(String name, int baudRate, int bits, int parity, int stopBits)
Opens a serial port.

Method Summary

static boolean	canOpen(String name) Checks if a port with the specified name (e.g.
boolean	close() Closes the port.
static String[]	enumerateAvailablePorts() Enumerate all available Comm ports.
void	finalize() Writes to the port.
boolean	flushStream() This is non-blocking.
boolean	isOpen() Returns true if the port is open and false otherwise.
void	kill() This forceably closes the serial port, even if there is data pending to be sent.
int	nonBlockingRead(byte[] buf, int start, int count) This is the non-blocking read operation.
int	nonBlockingWrite(byte[] buf, int start, int count) This is the non-blocking write operation.
int	pauseUntilReady(int type, int time)
boolean	setFlowControl(int type) Selects different flow control - hardware, software (XON/XOFF) or none.

Methods inherited from class ewe.io.StreamObject

closeStream, doRead, doWrite, flush, nap, nap, read, readAByte, readBytes, readBytes, write, writeAByte, writeBytes, writeBytes

Methods inherited from class ewe.io.BasicStreamObject

getException, getName, read, read, throwIOException, toInputStream, toOutputStream, toStream, write, write

Methods inherited from class ewe.util.Errorable

returnError, returnError, returnError

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, toString

Field Detail

NOPARITY

public static final int NOPARITY

See Also:

Constant Field Values

ODDPARITY

public static final int ODDPARITY

See Also:

Constant Field Values

EVENPARITY

public static final int EVENPARITY

See Also:

Constant Field Values

MARKPARITY

public static final int MARKPARITY

See Also:

Constant Field Values

SPACEPARITY

public static final int SPACEPARITY

See Also:

Constant Field Values

SOFTWARE_FLOW_CONTROL

public static final int SOFTWARE_FLOW_CONTROL

See Also:

Constant Field Values

HARDWARE_FLOW_CONTROL

public static final int HARDWARE_FLOW_CONTROL

See Also:

Constant Field Values

NO_FLOW_CONTROL

public static final int NO_FLOW_CONTROL

See Also:

Constant Field Values

Constructor Detail

SerialPort

public SerialPort(SerialPortSpecs options)
           throws IOException

Create a new open SerialPort.

Parameters:

options - The options for the opening the Serial Port.

Throws:

IOException - if the Serial Port could not be opened successfully.

SerialPort

public SerialPort(int number,
                  int baudRate,
                  int bits,
                  int parity,
                  int stopBits)

Opens a serial port. The number passed is the number of the serial port for devices with multiple serial ports.

On Windows devices, port numbers map to COM port numbers. For example, serial port 2 maps to "COM2:".

Here is an example of opening serial port COM2: on a Windows device:

 SerialPort port = new SerialPort(2, 57600, 8, SerialPort.NOPARITY, 1);
 

No serial XON/XOFF flow control (commonly called software flow control) is used and RTS/CTS flow control (commonly called hardware flow control) is turn on by default on all platforms but Windows CE.

Parameters:

number - port number

baudRate - baud rate

bits - bits per char [5 to 8]

parity - NOPARITY, EVENPARITY, ODDPARITY, MARKPARITY, SPACEPARITY

stopBits - number of stop bits

See Also:

setFlowControl(int)

SerialPort

public SerialPort(String name,
                  int baudRate,
                  int bits,
                  int parity,
                  int stopBits)

Opens a serial port.

Here is an example of opening serial port COM2: on a Windows device:

 SerialPort port = new SerialPort("COM2:", 57600, 8, SerialPort.NOPARITY, 1);
 

No serial XON/XOFF flow control (commonly called software flow control) is used and RTS/CTS flow control (commonly called hardware flow control) is turn on by default on all platforms but Windows CE.

Parameters:

name - port name - e.g. "COM1:" on Win32/WinCE systems.

baudRate - baud rate

bits - bits per char [5 to 8]

parity - NOPARITY, EVENPARITY, ODDPARITY, MARKPARITY, SPACEPARITY

stopBits - number of stop bits

See Also:

setFlowControl(int)

SerialPort

public SerialPort(int number,
                  int baudRate)

Open a serial port with settings of 8 bits, no parity and 1 stop bit. These are the most commonly used serial port settings.

SerialPort

public SerialPort(String name,
                  int baudRate)

Open a serial port with settings of 8 bits, no parity and 1 stop bit. These are the most commonly used serial port settings.

Method Detail

close

public boolean close()

Closes the port. Returns true if the operation is successful and false otherwise.

Specified by:

close in interface BasicStream

Overrides:

close in class StreamObject

isOpen

public boolean isOpen()

Returns true if the port is open and false otherwise. This can be used to check if opening the serial port was successful.

Specified by:

isOpen in interface BasicStream

Overrides:

isOpen in class StreamObject

setFlowControl

public boolean setFlowControl(int type)

Selects different flow control - hardware, software (XON/XOFF) or none. Use combinations of HARDWARE_FLOW_CONTROL and SOFTWARE_FLOW_CONTROL or NO_FLOW_CONTROL.

Parameters:

type - HARDWARE_FLOW_CONTROL or SOFTWARE_FLOW_CONTROL or both or NO_FLOW_CONTROL.

enumerateAvailablePorts

public static String[] enumerateAvailablePorts()

Enumerate all available Comm ports.

canOpen

public static boolean canOpen(String name)

Checks if a port with the specified name (e.g. "COM1:") can be opened. It does this by opening and closing the port immediately and without setting up any parameters.

Parameters:

name - The name of the serial port.

Returns:

true if the port was opened successfully.

nonBlockingRead

public int nonBlockingRead(byte[] buf,
                           int start,
                           int count)

Description copied from class: StreamObject

This is the non-blocking read operation. It should never attempt to wait() or sleep() in a Coroutine. It should return as quickly as possible. This makes it safe to be called from within a native method. Note that this should NEVER be called with a count of zero.

The default StreamObject implementation of this uses the single byte read() method.

Specified by:

nonBlockingRead in interface BasicStream

Overrides:

nonBlockingRead in class StreamObject

Parameters:

buf - Destination byte array to hold incoming data.

start - Starting index in buff for incoming data.

count - Maximum number of bytes to read - should never be zero.

Returns:

greater than 0 = Number of bytes read.
0 = No bytes available to read at this time.
-1 = Stream end reached no further bytes to read.
-2 = IO Error.
Note that these values are different to the Stream.readBytes method.

nonBlockingWrite

public int nonBlockingWrite(byte[] buf,
                            int start,
                            int count)

Description copied from class: StreamObject

This is the non-blocking write operation. It should never attempt to wait() or sleep() in a Coroutine. It should return as quickly as possible. This makes it safe to be called from within a native method.

The default StreamObject implementation of this uses the single byte write() method.

Specified by:

nonBlockingWrite in interface BasicStream

Overrides:

nonBlockingWrite in class StreamObject

Parameters:

buf - Source byte array holding data to be written.

start - Starting index in buff for data to be written.

count - Number of bytes to write - should never be zero.

Returns:

greater than 0 = Number of bytes actually written.
0 = No bytes could be written yet - but the stream is still open.
-1 = Stream has been closed - no further writes are possible.
-2 = IO error - something went wrong.
Note that these values are different to the Stream.writeBytes method.

pauseUntilReady

public int pauseUntilReady(int type,
                           int time)

Specified by:

pauseUntilReady in interface StreamCanPause

flushStream

public boolean flushStream()
                    throws IOException

Description copied from interface: BasicStream

This is non-blocking. It returns true if the flush completed, false if it did not, or throws an exception on error.

Specified by:

flushStream in interface BasicStream

Throws:

IOException

finalize

public void finalize()

Writes to the port. Returns the number of bytes written or -1 if an error prevented the write operation from occurring. If data can't be written to the port and flow control is on, the write operation will time out and fail after approximately 2 seconds.

Overrides:

finalize in class Object

kill

public void kill()
          throws IOException

This forceably closes the serial port, even if there is data pending to be sent. This may be necessary under some circumstances if you need to change the port configuration or reset the port by creating a new SerialPort object.

Throws:

IOException