AVR Z-LINKŪ


Serial Interface

Detailed Description

The SerialInterface is a group of functions that enables reception and transmission of data over RS232 or USB (using Virtual COM Port) links. The goal is to hide some of the nature of a serial port to the user. And instead offer functionality to send data onto a stream and to generate indications (events) whenever new data is received.

The goal to "hide" the serial port was achieved by introducing two classes. The SerialPortUtilities is a very thin layer of static functions that makes it easy to handle and connect to serial ports. One service that this class provides is connection to serial ports by name (Like "COM1"). However, the SerialStream class is where most of the work is done. This class provides the end user with streams. Data can be pushed onto the output stream with a functionality similar to "printf", and the input strean will tell its listeners when new data is available.

SerialStream.png

SerialStream Concept.


Functions

static boolean serialInterface::SerialPortUtilities.addSerialEventListener (SerialPort portToAddListener, SerialPortEventListener listener)
 This function is used to add listeners to the chosen serial port.
void serialInterface::SerialStream.addSerialStreamEventListener (SerialStreamListener ssListener)
 This function adds a new SerialStreamEventListener to the queue of event listeners.
static SerialPort serialInterface::SerialPortUtilities.connectToSerialPort (String serialPortName)
 This function is used to open a serial port given its name.
void serialInterface::SerialStream.disableSerialStreamEvents ()
 This function disables SerialStream event generation.
void serialInterface::SerialStream.enableSerialStreamEvents ()
 This function enables SerialStream event generation.
void serialInterface::SerialStream.fireSearialStreamEvent (SerialStreamEvent SerialStreamEvent)
 When this function is called a new SerialStreamEvent is injected into the dispatcher queue to be handled by the associated SerialStreamListener.
String serialInterface::SerialStream.getData ()
 This function is used to get data from the output stream.
static Vector< String > serialInterface::SerialPortUtilities.getSerialPortNames ()
 This function returns a vector with the names of the accessible serial ports on the machine.
SerialPort serialInterface::SerialStream.getSerialPortUsed ()
 Return the SerialPort instance to which the io streams are connected.
void serialInterface::SerialStream.removeSerialStreamListener (SerialStreamListener ssListener)
 This function deletes a SerialStreamListener from the queue of event listeners.
void serialInterface::SerialStream.resetReceiver ()
 This function resets the receiver.
void serialInterface::SerialStream.sendData (String data)
 This function is used to append data to the output stream.
String serialInterface::SerialStream.sendDataBlocking (String data)
 This is the blocking version of sendData.
void serialInterface::SerialStream.serialEvent (SerialPortEvent spe)
 Function that any SerialPortEventListener must implement. It is called whenever new events are available.
 serialInterface::SerialStream.SerialStream (SerialPort portToAppendStream) throws SerialStreamException
 This is the SerialStream constructor. Creates a new serial stream if possible.
 serialInterface::SerialStreamEvent.SerialStreamEvent (String response)
 Constructor for new SerialStreamEvents.
 serialInterface::SerialStreamException.SerialStreamException (String event)
 Constructor for new SerialStreamExceptions.
static boolean serialInterface::SerialPortUtilities.setBaudRate (SerialPort portToConfigure, final int BAUD_RATE)
 This function is used to set the baud rate of the chosen serial port.

Function Documentation

static boolean serialInterface.SerialPortUtilities.addSerialEventListener ( SerialPort  portToAddListener,
SerialPortEventListener  listener 
) [static, inherited]

This function is used to add listeners to the chosen serial port.

Parameters:
portToAddListener Serial port to listen to.
listener Serial event listener instance.
Returns:
True if a SerialPortEventListener was added to the SerialPort. False if it was not possible to add listener.

Definition at line 141 of file SerialPortUtilities.java.

00141                                                                                                                       {
00142 
00143                 try{
00144                         portToAddListener.addEventListener( listener );
00145                 }catch( TooManyListenersException tmle ){
00146 
00147                         tmle.printStackTrace( );
00148                         return false;
00149                 }
00150                 
00151                 //Set the listener trig on DataAvailable events.
00152                 portToAddListener.notifyOnDataAvailable( true );
00153                 
00154                 return true;
00155         }

void serialInterface.SerialStream.addSerialStreamEventListener ( SerialStreamListener  ssListener  )  [inherited]

This function adds a new SerialStreamEventListener to the queue of event listeners.

Parameters:
ssListener SerialStreamListener to be added.

Definition at line 262 of file SerialStream.java.

Referenced by radioInterface.RadioInterface.RadioInterface().

00262                                                                                    {
00263                 SerialStreamListeners.add( SerialStreamListener.class, ssListener );
00264         }

static SerialPort serialInterface.SerialPortUtilities.connectToSerialPort ( String  serialPortName  )  [static, inherited]

This function is used to open a serial port given its name.

Parameters:
serialPortName Name of the serial port to connect with (COMx).
Returns:
Object of type SerialPort. Tries to connect to the serial port and returns the SerialPort object if successful. Null is returned if the connection failed.

Definition at line 76 of file SerialPortUtilities.java.

00076                                                                              {
00077                 
00078                 //Get identifiers.
00079                 Enumeration availablePorts = CommPortIdentifier.getPortIdentifiers( );
00080                 SerialPort ret = null;
00081                 
00082                 //Loop through the list of CommPortIdentifiers.
00083                 for( ; availablePorts.hasMoreElements( ); ){
00084                         
00085                         CommPortIdentifier currentPort = ( CommPortIdentifier )availablePorts.nextElement ( );
00086                         
00087                         String currentPortName = ( String )currentPort.getName( );
00088                         
00089                         //Found a match; try to open and if possible return.
00090                         if( currentPortName.equals( serialPortName ) ){
00091                                 
00092                                 try{
00093                                         ret = ( SerialPort )currentPort.open( "AVR SerialPortLibrary" , 200 );
00094                                 }catch( PortInUseException piue ){
00095                                         
00096                                         piue.printStackTrace( );
00097                                         ret = null;
00098                                 }
00099                                 
00100                                 break;
00101                         }
00102                 }
00103                 
00104                 return ret;
00105         }

void serialInterface.SerialStream.disableSerialStreamEvents (  )  [inherited]

This function disables SerialStream event generation.

Definition at line 167 of file SerialStream.java.

Referenced by radioInterface.RadioInterface.disableIndications().

00167                                                 {
00168                 streamEventEnabled = false;
00169         }

void serialInterface.SerialStream.enableSerialStreamEvents (  )  [inherited]

This function enables SerialStream event generation.

Definition at line 157 of file SerialStream.java.

Referenced by radioInterface.RadioInterface.enableIndications().

00157                                                {
00158                 streamEventEnabled = true;
00159         }

void serialInterface.SerialStream.fireSearialStreamEvent ( SerialStreamEvent  SerialStreamEvent  )  [protected, inherited]

When this function is called a new SerialStreamEvent is injected into the dispatcher queue to be handled by the associated SerialStreamListener.

Parameters:
SerialStreamEvent Inject new SerialStreamEvent instance to the dispatcher.

Definition at line 286 of file SerialStream.java.

Referenced by serialInterface.SerialStream.serialEvent().

00286                                                                                     {
00287                 
00288                 Object[ ] listeners = SerialStreamListeners.getListenerList( );
00289                 int numberOfListeners = listeners.length;
00290                 
00291                 for( int i = 0; i < numberOfListeners; i+=2 ){
00292                         
00293                         if( listeners[ i ] == SerialStreamListener.class ){
00294                                 ( (SerialStreamListener)listeners[ i + 1 ] ).SerialStreamEvent( SerialStreamEvent );
00295                         }
00296                 }
00297         }

String serialInterface.SerialStream.getData (  )  [inherited]

This function is used to get data from the output stream.

Returns:
String with new data, or null if nothing is received yet
(Still waiting for the response).

Definition at line 98 of file SerialStream.java.

00098                                 {
00099                 
00100                 if( receptionDone ){
00101                         
00102                         return receivedOnStream;
00103                 }
00104                 
00105                 //Reception is not finished.
00106                 else{
00107                         return null;
00108                 }
00109         }

static Vector<String> serialInterface.SerialPortUtilities.getSerialPortNames (  )  [static, inherited]

This function returns a vector with the names of the accessible serial ports on the machine.

Returns:
Vector with names of the available serial ports. If no ports are found the vector will have length 0.

Definition at line 45 of file SerialPortUtilities.java.

00045                                                           {
00046                 
00047                 Vector<String> serialPortNames = new Vector<String>( ); 
00048                 Enumeration availablePorts = CommPortIdentifier.getPortIdentifiers( );
00049                 
00050                 //Run through list of available ports
00051                 for( ; availablePorts.hasMoreElements( ); ){
00052                         
00053                         CommPortIdentifier currentPort = (CommPortIdentifier)availablePorts.nextElement ( );
00054                         
00055                         //Only add ports that is of type serial port and those not already in use.
00056                         if( ( currentPort.getPortType( ) == CommPortIdentifier.PORT_SERIAL ) &&
00057                                         ( currentPort.isCurrentlyOwned( ) == false ) ){
00058                                 
00059                                 serialPortNames.add( currentPort.getName( ) );
00060                         }
00061                 }
00062                 
00063                 return serialPortNames;
00064         }

SerialPort serialInterface.SerialStream.getSerialPortUsed (  )  [inherited]

Return the SerialPort instance to which the io streams are connected.

Returns:
SerialPort that is associated with this IO stream.

Definition at line 147 of file SerialStream.java.

00147                                               {
00148                 return serialPort;
00149         }

void serialInterface.SerialStream.removeSerialStreamListener ( SerialStreamListener  ssListener  )  [inherited]

This function deletes a SerialStreamListener from the queue of event listeners.

Parameters:
ssListener SerialStreamListener to remove.

Definition at line 274 of file SerialStream.java.

00274                                                                                  {
00275                 SerialStreamListeners.remove( SerialStreamListener.class, ssListener );
00276         }

void serialInterface.SerialStream.resetReceiver (  )  [inherited]

This function resets the receiver.

Definition at line 177 of file SerialStream.java.

00177                                     {
00178                 
00179                 receptionDone = false;
00180         }

void serialInterface.SerialStream.sendData ( String  data  )  [inherited]

This function is used to append data to the output stream.

Parameters:
data Data to send on the output stream.

Definition at line 84 of file SerialStream.java.

00084                                            {
00085                 
00086                 receptionDone = false;
00087                 outputStream.println( data );
00088         }

String serialInterface.SerialStream.sendDataBlocking ( String  data  )  [inherited]

This is the blocking version of sendData.

Data is sent in the same manner as for sendData, however this function blocks until a response is received. Any response must be terminated "\r\n". Can only handle one send-receive cycle at the time. This implementation does not support that multiple messages are send and that the responses are distributed correct.

Parameters:
data Data to send on the output stream.
Returns:
Response received on the input stream after the message was sent. If an error occured, an error message is returned.

Definition at line 128 of file SerialStream.java.

00128                                                      {
00129                 
00130                 this.sendData( data );
00131                 
00132 //              Wait until the response is termianted or an error occurs reading.
00133                 while( !receptionDone );
00134                 
00135                 return receivedOnStream;
00136         }

void serialInterface.SerialStream.serialEvent ( SerialPortEvent  spe  )  [inherited]

Function that any SerialPortEventListener must implement. It is called whenever new events are available.

This data will then be read out and copied to the response string. If an error occurs during read, the response string will be set to some error message. The serialStreamEventEnabled flag turns generation of SerialStreamEvents on or off.

Parameters:
spe SerialPortEvent generated by the event source.

Definition at line 195 of file SerialStream.java.

References serialInterface.SerialStream.fireSearialStreamEvent().

00195                                                        {
00196                 
00197                 switch( spe.getEventType( ) ){
00198                 
00199                 //HW handshake not used.
00200             case SerialPortEvent.BI:
00201             case SerialPortEvent.OE:
00202             case SerialPortEvent.FE:
00203             case SerialPortEvent.PE:
00204             case SerialPortEvent.CD:
00205             case SerialPortEvent.CTS:
00206             case SerialPortEvent.DSR:
00207             case SerialPortEvent.RI:
00208             case SerialPortEvent.OUTPUT_BUFFER_EMPTY:
00209                 break;
00210             
00211             //Only react on new data available.
00212             case SerialPortEvent.DATA_AVAILABLE:
00213                 
00214                 StringBuffer readBuffer = new StringBuffer( );
00215                 int c;
00216                     
00217                 try{
00218                         
00219                         for( ; ( c = inputStream.read( ) ) != '\n'; ){
00220                                 if( c!= '\r' )  readBuffer.append( ( char ) c);
00221                                 }
00222                         
00223                         //Close stream.
00224                         inputStream.close( );
00225                         receptionDone = true;
00226                         }catch( IOException ie ){
00227                                 
00228                                 //Handle if we could not read from the serial port.
00229                                 ie.printStackTrace( );
00230                                 receptionDone = true;
00231                                 receivedOnStream = "ERROR: Could not read from stream.";
00232                                 
00233 //                              Send a serial stream event to possible listeners if enabled.
00234                                 if( streamEventEnabled ){
00235                                         
00236                                         fireSearialStreamEvent( new SerialStreamEvent( receivedOnStream ) );
00237                                 }
00238                                 
00239                                 return;
00240                         }
00241                 
00242                         //Add response to the receivedOnStream string.
00243                         receivedOnStream = readBuffer.toString( );
00244                         
00245                         //Send a serial stream event to possible listeners if enabled.
00246                         if( streamEventEnabled ){
00247                                 fireSearialStreamEvent( new SerialStreamEvent( receivedOnStream ) );
00248                         }
00249          
00250                 break;
00251                 }
00252         }

Here is the call graph for this function:

serialInterface.SerialStream.SerialStream ( SerialPort  portToAppendStream  )  throws SerialStreamException [inherited]

This is the SerialStream constructor. Creates a new serial stream if possible.

Parameters:
portToAppendStream SerialPort that the SerialStream will be connected to.
Exceptions:
SerialStreamException If it was not possible to attach IO streams to serial port an exception is thrown. An exceptions is also thrown if it is impossible to listen to events from the serial port.

Definition at line 53 of file SerialStream.java.

00053                                                                                          {
00054                 
00055                 //Open IO streams.
00056                 try{
00057                         
00058                         inputStream = new DataInputStream( portToAppendStream.getInputStream( ) );
00059                         outputStream = new PrintStream( portToAppendStream.getOutputStream( ), true );
00060                 }catch( IOException ioe ){
00061 
00062                         ioe.printStackTrace( );
00063                         
00064                         throw new SerialStreamException( "Not possible to open IO Streams." );
00065                 }
00066                 
00067                 //Add this object instance as SerialPortEventListener.
00068                 if( !SerialPortUtilities.addSerialEventListener( portToAppendStream, this) ){
00069                         throw new SerialStreamException( "Not possible to listen to chosen serial port." );
00070                 }
00071                 
00072                 //Ready to receive new responses and disable serial stream event generation.
00073                 receptionDone = false;
00074                 streamEventEnabled = false;
00075         }

serialInterface.SerialStreamEvent.SerialStreamEvent ( String  response  )  [inherited]

Constructor for new SerialStreamEvents.

Parameters:
response String that was received on the input stream.

Definition at line 35 of file SerialStreamEvent.java.

00035                                                     {
00036                 
00037                 this.receivedOnInpuStream = response;
00038         }

serialInterface.SerialStreamException.SerialStreamException ( String  event  )  [inherited]

Constructor for new SerialStreamExceptions.

Parameters:
event String that describes the new SerialStreamException.

Definition at line 34 of file SerialStreamException.java.

00034                                                     {
00035                 super( event );
00036         }

static boolean serialInterface.SerialPortUtilities.setBaudRate ( SerialPort  portToConfigure,
final int  BAUD_RATE 
) [static, inherited]

This function is used to set the baud rate of the chosen serial port.

Parameters:
portToConfigure Serial port to change baud rate on.
BAUD_RATE Communication speed to be used.
Returns:
True if the baud rate was changed successfully. False if it was not possible to change the baud rate of the serial port.

Definition at line 117 of file SerialPortUtilities.java.

00117                                                                                             {
00118                 
00119                 try{
00120                         portToConfigure.setSerialPortParams( BAUD_RATE, SerialPort.DATABITS_8, SerialPort.STOPBITS_1,
00121                                                                                                   SerialPort.PARITY_NONE );
00122                 }catch( UnsupportedCommOperationException ucoe ){
00123                         
00124                         ucoe.printStackTrace( );
00125                         return false;
00126                 }
00127                 
00128                 return true;
00129         }

@DOC_TITLE@
Generated on Sat Dec 2 16:14:07 2006 for AVR414 User's Guide - ATAVRRZ502 - Accessory Kit by doxygen 1.4.7