SerialPort.SerialPort
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
SerialPort - Java and C access to local or remote serial ports.
The SerialPort package provides a Java program with access to serial ports. It allows its caller to control the port's settings (speed, parity, etc) and to transfer data to and from a remote client. One instance of the SerialPort object accesses one serial port and operates independently of any other serial ports the program may be using. This class is compatible with all releases of Java. It uses TCP/IP to connect to spd, a server that handles serial ports on its behalf. spd is written in C. It is always run on the host which has the serial ports, but a SerialPort object can communicate with spd regardless of whether it is running on the same system or on a remote host.
All SerialPort methods contain in-line code with no internal delays apart from the sleep() method, which is provided as a convenient way to wait for remote activity to occur and to allow for transmission time.
There are no internal delays in the serial port server. The intent is to allow a client program to choose when or if it needs to wait for external events. The methods do, however, contain sufficient validation to ensure that each method will complete during normal operation.
The constructor does not open any connections: it just sets the hostname and TCP/IP port to be used by the following listPort() and open() invocations. The open() method opens a connection to the server if necessary and claims the serial port.
The close() method closes the connection, leaving the object ready to be re-used by an open() invocation. It is good practise to invoke the delete() method when the object is to be disposed of because this checks that no connections have been left open. delete() fails if the connection to the serial port server is still open.
The listPorts() method establishes the connection it needs to retrieve a list of ports if one does not exist. Subsequent method invocations will re-use the connection opened by listPorts(). If a connection already exists the open() method will reuse it.
The environ jar file and the SDPMessage class must be available on the current classpath when SerialPort is used or compiled.
SerialPort - serial connections for Java Copyright (C) 2005 Martin C Gregorie This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Contact Martin Gregorie at
martin@gregorie.org.
Read the GNU General Public License.
| Constructor Summary | |
SerialPort(int debug,
java.lang.String host,
int port)
Construct the object, set the name of the host supporting the desired serial port, the TCP/IP port number and debugging level. |
|
| Method Summary | |
int |
close(boolean force)
Releases the serial port and closes the server connection. |
int |
delete()
Called when the object is no longer required. |
int |
echo(byte[] charsout,
int expected,
int adj)
A convenience method that calls put(), sleep() and get() methods. |
int |
findPortList()
Builds a list of available ports. |
int |
get(int n)
Reads up to n characters from the port and stores them internally for later retrieval by the getBytes() method. |
int |
getBufferSize()
Returns the size of the spd input and output buffers. |
byte[] |
getBytes()
Returns the bytes read by the last get() or echo() invocation. |
java.lang.String |
getError()
Returns the current error string or "OK" |
int |
getInputCount()
Returns the number of bytes in the input buffer retrieved by the preceeding invocation of query(). |
int |
getOutputCount()
Returns the number of bytes in the output buffer retrieved by the preceeding invocation of query(). |
java.lang.String |
getPortList()
Returns the ports found by the findPortList() method as a comma delimited list in a single String object. |
java.lang.String |
getPortParameters()
Returns the operating parameters for the serial port that's currently open as a comma delimited String formatted as "baudrate,databits,parity,stopbits" where parity is O,E or N for Odd, Even or None. |
int |
open(java.lang.String name)
Opens a connection to spd and claims the serial port identified by name. |
int |
put(byte[] buff)
Sends bytes in the array to the serial port. |
int |
query()
Queries the server for the numbers of bytes in the input and output buffers and the buffer size: both buffers are the same size. |
int |
reset(char line_settings,
char tx_delay,
char separator)
Resets the line settings, tx delay and record separator. |
int |
setDelay(int delay)
Sets the delay (in mS) between writing characters to the serial port. |
int |
setPortParameters(int baud,
int bits,
char parity,
int stopbits)
Sets baud rate, databits (5-8), parity (O, E, N) and stopbits (1,2) for the serial port. |
int |
setSeparator(char active,
char sep,
char external)
Sets the record separator and its application conditions. |
int |
sleep(int expected,
int adj)
Cause the calling process to sleep while the remote process generates and sends a reply. |
java.lang.String |
toString()
Diagnostic display of the constructor interface. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
public SerialPort(int debug,
java.lang.String host,
int port)
| Method Detail |
public int delete()
public java.lang.String getError()
public int findPortList()
public java.lang.String getPortList()
public int open(java.lang.String name)
public int close(boolean force)
public int setPortParameters(int baud,
int bits,
char parity,
int stopbits)
public java.lang.String getPortParameters()
public int setDelay(int delay)
public int reset(char line_settings,
char tx_delay,
char separator)
Resets the line settings, tx delay and record separator. The arguments are boolean values encoded as T/F, t/f or 1/0.
Returns -ve on error.
public int setSeparator(char active,
char sep,
char external)
Sets the record separator and its application conditions. The arguments active and external are boolean values encoded as T/F, t/f or 1/0. active determines whether the field separator character, set by sep, is in use. If it is active put() and get() operate at the field level. get() stops when the separator character is found. put() sends one field at a time. If external is true the separator character is added during a put() operation and not returned to the caller by a get() operation. If external is false the caller must ensure that each string sent by put() is terminated by the separator character and must expect the separator at the end of a string returned by a get() operation.
The default is that active and external are false and sep is 0 (zero).
Returns -ve on error.
public int put(byte[] buff)
public int get(int n)
Reads up to n characters from the port and stores them internally for later retrieval by the getBytes() method. If requested by setSeparator(), the separator character may terminate the characters read (active separator is true) and may be hidden from the caller (external separator is true).
Note: if the remote response is slower than expected an incomplete message may be returned. In this case the caller should wait for a suitable time and invoke the get() message again. See the sleep() method for suggestions on preventing this ocurrence.get() returns the number of characters read or -ve on error.
public byte[] getBytes()
public int echo(byte[] charsout,
int expected,
int adj)
A convenience method that calls put(), sleep() and get() methods. charsout is sent by put(). The expected and adj arguments are passed to sleep(). get() retrieves the available bytes and stores them locally. If a terminator is active then it will terminate the input string. echo() returns number of characters read or -ve on error.
Use the getBytes() method to retrieve the response.
public int query()
Queries the server for the numbers of bytes in the input and output buffers and the buffer size: both buffers are the same size. The response is decoded and the values stored. Returns -ve on error.
Use the getInputCount(), getOutputCount() and getBufferSize() methods to retrieve the results.
public int getInputCount()
public int getOutputCount()
public int getBufferSize()
public int sleep(int expected,
int adj)
Cause the calling process to sleep while the remote process generates and sends a reply.
First it queries the server for buffer content. Then it calculates the delay time needed for all waiting bytes to be sent and all expected incoming bytes to have been received. Finally it adds on adj, which is in mS.
sleep() waits for the calculated time.
This is repeated until the output buffer is empty and the number of bytes in the input buffer stops changing or there are enough bytes in the buffer to match the expected number.
adj is a signed integer that is added to the calculated time. It is in mS and is intended to let the caller specify additional sleep time to make allowance for a remote process that is known to have a long response time. adj can also be used to adjust the sleep time downwards but it cannot reduce the time below zero.
Returns -ve on error.
public java.lang.String toString()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||