waba.io
Class SerialPort

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--waba.io.SerialPort

public class SerialPort

extends Stream

SerialPort accesses a device's serial port.

This works under the devices and under JDK (in this case, it uses javax.comm)

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.

Here is an example showing data being written and read from a serial port:

 SerialPort port = new SerialPort(0, 9600);
 if (!port.isOpen())
   return;
 byte buf[] = new byte[10];
 buf[0] = 3;
 buf[1] = 7;
 port.writeBytes(buf, 0, 2);
 int count = port.readBytes(buf, 0, 10);
 if (count == 10)
   ...
 port.close();
 

Note on HandSpring users: the Keyboard thread is disabled after open and enabled again after close.

Field Summary

static int	BLUETOOTH Bluetooth: open the built-in Bluetooth discovery dialog, then establish a Serial Port Profile (just serial emulation across Bluetooth, using the RFComm BT layer) virtual serial port connection.
static int	DEFAULT Default Port (cradle)
static int	IRCOMM IrCOMM Port (Serial Connection on top of IrDA Stack)
int	lastError Returns the last error when calling a method.
java.lang.String	lastErrorStr
static int	PARITY_EVEN Used in the constructor to define the parity
static int	PARITY_NONE Used in the constructor to define the parity
static int	PARITY_ODD Used in the constructor to define the parity
static int	SIR SIR Port (Physical Layer of IrDA Stack).
boolean	stopWriteCheckOnTimeout Set to false to not let the timeout error stop the write check loop.
static int	USB USB Endpoint 2 Port
int	writeTimeout Defines the write timeout, in milliseconds.

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, boolean parity, int stopBits)
Opens a serial port.

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

Method Summary

boolean	close() Closes the port.
void	finalize() Used by Jump.
java.lang.String	getStatus() Returns the status of this serial port connection according to the last error occurred.
boolean	isOpen() Returns true if the port is open and false otherwise.
int	readBytes(byte[] buf, int start, int count) Reads bytes from the port into a byte array.
int	readCheck() Returns the number of bytes currently available to be read from the serial port's queue.
boolean	setFlowControl(boolean on) Turns RTS/CTS flow control (hardware flow control) on or off.
boolean	setReadTimeout(int millis) Sets the timeout value for read operations.
int	writeBytes(byte[] buf, int start, int count) Writes to the port.

Methods inherited from class java.lang.Object

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

Field Detail

lastError

public int lastError

Returns the last error when calling a method. Below you can see a list of error codes from SerialMgr.h.

SW Custom codes (See nmpalm_c.c for details):
65525 (-11): NO_SERIAL_LIBRARY_AVAILABLE
65522 (-14): ARRAY_RANGE_CHECK

BlackBerry error codes:
-10000: DEFAULT_ERROR - @see #lastErrorStr

WindowsCE error codes: see winerror.h in the Windows SDK.

Linux error codes: see the errno.h file in your system include files. Palm OS error codes.

serErrBadParam	769
BadPort	770
NoMem	771
BadConnID	772
TimeOut	773
LineErr	774
AlreadyOpen	775
StillOpen	776
NotOpen	777
NotSupported	778
NoDevicesAvail	779
USBConfigurationFailed	780

lastErrorStr

public java.lang.String lastErrorStr

stopWriteCheckOnTimeout

public boolean stopWriteCheckOnTimeout

Set to false to not let the timeout error stop the write check loop.

writeTimeout

public int writeTimeout

Defines the write timeout, in milliseconds. Currently works only on Palm OS. The default is 6 seconds.

DEFAULT

public static final int DEFAULT

Default Port (cradle)

IRCOMM

public static final int IRCOMM

IrCOMM Port (Serial Connection on top of IrDA Stack)

SIR

public static final int SIR

SIR Port (Physical Layer of IrDA Stack). Important! In order to access the SIR port on the Pocket PCs the following has to be UNCHECKED: Settings/Connections/Beam/Receive all incoming beams and select discoverable mode. Note that Palm OS OMAP-based devices does NOT support SIR (aka raw IR); see this: http://www.alanjmcf.me.uk/comms/infrared/IrDA%20FAQ.html and http://news.palmos.com/read/messages?id=146145#146145. Note also that there's no handshaking support on SIR, and that not all devices work with it. Use IRCOMM instead when possible.

USB

public static final int USB

USB Endpoint 2 Port

BLUETOOTH

public static final int BLUETOOTH

Bluetooth: open the built-in Bluetooth discovery dialog, then establish a Serial Port Profile (just serial emulation across Bluetooth, using the RFComm BT layer) virtual serial port connection. Note: in WinCE, this maps to the Serial (port 0). You must explicitly map your BlueTooth outside SW.

PARITY_NONE

public static final int PARITY_NONE

Used in the constructor to define the parity

PARITY_EVEN

public static final int PARITY_EVEN

Used in the constructor to define the parity

PARITY_ODD

public static final int PARITY_ODD

Used in the constructor to define the parity

Constructor Detail

SerialPort

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

Opens a serial port. The number passed is the number of the serial port for devices with multiple serial ports. Port number 0 defines the "default port" of a given type. For Windows CE and PalmPilot devices, you should pass 0 as the port number to access the device's single serial port.

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

Here is an example showing how to open the serial port of a PalmPilot device at 9600 baud with settings of 8 bits, no partity and one stop bit (8/N/1):

 SerialPort port = new SerialPort(0, 9600, 8, false, 1);
 

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

 SerialPort port = new SerialPort(2, 57600, 8, false, 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. The parity setting is a boolean. If false, no parity is used. If true, "even" parity is used.

Parameters:

number - port number. In Windows, this is the number of the COM port.

baudRate - baud rate

bits - bits per char [5 to 8]

parity - true for even parity, false for no parity

stopBits - number of stop bits

See Also:

setFlowControl(boolean)

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. Port number 0 defines the "default port" of a given type. For Windows CE and PalmPilot devices, you should pass 0 as the port number to access the device's single serial port.

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

Here is an example showing how to open the serial port of a PalmPilot device at 9600 baud with settings of 8 bits, no partity and one stop bit (8/N/1):

 SerialPort port = new SerialPort(0, 9600, 8, false, 1);
 

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

 SerialPort port = new SerialPort(2, 57600, 8, false, 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. The parity setting must be one of the constants PARITY_NONE, PARITY_EVEN, PARITY_ODD. For Palm OS, PARITY_ODD turns on XonXoff mode.

Parameters:

number - port number. In Windows, this is the number of the COM port.

baudRate - baud rate

bits - bits per char [5 to 8]

parity - of the constants PARITY_NONE, PARITY_EVEN, PARITY_ODD. For Palm OS, PARITY_ODD turns on XonXoff mode.

stopBits - number of stop bits

Since:

SuperWaba 4.5

See Also:

setFlowControl(boolean)

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.

Parameters:

number - port number. In Windows, this is the number of the COM port.

baudRate - baud rate

Method Detail

getStatus

public java.lang.String getStatus()

Returns the status of this serial port connection according to the last error occurred. If it was a BlackBerry error (-10000), the exception message is returned. Otherwise, the last error code (as a hex string) is returned.

Returns:

the status of this serial port connection.

close

public boolean close()

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

Overrides:

close in class Stream

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. This method does not clear the lastError flag.

Overrides:

isOpen in class Stream

setFlowControl

public boolean setFlowControl(boolean on)

Turns RTS/CTS flow control (hardware flow control) on or off.

Parameters:

on - pass true to set flow control on and false to set it off

setReadTimeout

public boolean setReadTimeout(int millis)

Sets the timeout value for read operations. The value specifies the number of milliseconds to wait from the time of last activity before timing out a read operation. Passing a value of 0 sets no timeout causing any read operation to return immediately with or without data. The default timeout is 100 milliseconds. This method returns true if successful and false if the value passed is negative or the port is not open.

Parameters:

millis - timeout in milliseconds

readBytes

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

Reads bytes from the port into a byte array. Returns the number of bytes actually read or -1 if an error prevented the read operation from occurring. The read will timeout if no activity takes place within the timeout value for the port.

Overrides:

readBytes in class Stream

Parameters:

buf - the byte array to read data into

start - the start position in the byte array

count - the number of bytes to read

See Also:

setReadTimeout(int)

readCheck

public int readCheck()

Returns the number of bytes currently available to be read from the serial port's queue.

writeBytes

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

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:

writeBytes in class Stream

Parameters:

buf - the byte array to write data from

start - the start position in the byte array

count - the number of bytes to write

finalize

public void finalize()

Used by Jump. Does nothing in the SW VM

Overrides:

finalize in class java.lang.Object