| 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 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@