| AVR Z-LINKŪ |

# Radio Interface

## Detailed Description

This module is the next higher layer on top of the serial streams. In the Introduction it was stated that the AVR414 is a thin textual protocol on top of the IEEE 802.15.4 library. This textual protocol defines a set of commands that the radio platform (AVR and AT86RF230) can understand, but also some commands that the radio platform will push back when certain events occur.

By using SerialStreams and by listening to the events they generate it is possible for the radio interface to send the defined set of commands, but also dispatch new events to the next higher layer. The services provided can roughly be divided in three:

- Commands: This is a set of functions that enables its caller to send one of the defined commands in the textual protocol. It is optional to wait for an acknowledge.
- Events: Whenever a new event is fired from the SerialStream module, it will be received and decoded by the radio interface and new events are fired to the next higher layer.
- Utilities: This is a set of functions used to manage and configure the radio interface, such as: enable /disable events, reset module, set timeouts etc.

The illustration below depicts how the radio interface is positioned on top of the SerialStream module. Also how it is seen by the next higher layer.

Radio Interface.

## Functions
void | radioInterface::RadioInterface.addNewAssociationIndicationListeners (NewAssociationIndicationListener naiListener)
| This function adds a new NewAssociationIndicationListener to the queue of event listeners.
void | radioInterface::RadioInterface.addNewDataIndicationListeners (NewDataIndicationListener ndiListener)
| This function adds a new NewDataIndicationListener to the queue of event listeners.
void | radioInterface::RadioInterface.addNewDisassociationIndicationListeners (NewDisassociationIndicationListener ndiListener)
| This function adds a new NewDisassociationIndicationListener to the queue of event listeners.
void | radioInterface::RadioInterface.disableIndications ()
| Disables NewAssociatioIndication, NewDataIndication and NewDisassociationIndication. Also disables SerialStreamEvents.
void | radioInterface::RadioInterface.enableIndications ()
| Enables NewAssociatioIndication, NewDataIndication and NewDisassociationIndication. Also enables SerialStreamEvents.
void | radioInterface::RadioInterface.fireNewAssociationIndicationListeners (NewAssociationIndication newDataEvent)
| When this function is called a new NewAssociationIndication is injected into the dispatcher queue to be handled by the associated NewAssociationIndicationListener.
void | radioInterface::RadioInterface.fireNewDataIndicationListeners (NewDataIndication newDataEvent)
| When this function is called a new NewDataIndication is injected into the dispatcher queue to be handled by the associated NewAssociationIndicationListener.
void | radioInterface::RadioInterface.fireNewDisassociationIndicationListeners (NewDisassociationIndication newDataEvent)
| When this function is called a new NewDisassociationIndication is injected into the dispatcher queue to be handled by the associated NewDisassociationIndicationListener.
| radioInterface::RadioInterface.RadioInterface (SerialPort portToUse) throws RadioInterfaceStartException
| Class constructor that generates a new AT-Command interface.
void | radioInterface::RadioInterface.removeNewAssociationIndicationListeners (NewAssociationIndicationListener naiListener)
| This function deletes a NewAssociationIndicationListener from the queue of event listeners.
void | radioInterface::RadioInterface.removeNewDataIndicationListeners (NewDataIndicationListener ndiListener)
| This function deletes a NewDataIndicationListener from the queue of event listeners.
void | radioInterface::RadioInterface.removeNewDisassociationIndicationListeners (NewDisassociationIndicationListener ndiListener)
| This function deletes a NewDisassociationIndicationListener from the queue of event listeners.
boolean | radioInterface::RadioInterface.sendConfigure (String channel, String panID, String deviceType)
| Sends the AT+C command and arguments to the radio hw.
boolean | radioInterface::RadioInterface.sendData (String data)
| Sends the AT+T command and arguments to the radio hw.
boolean | radioInterface::RadioInterface.sendDisAssociate ()
| Sends the AT+D command to the radio hw.
boolean | radioInterface::RadioInterface.sendReset ()
| Sends the AT+R command to the radio hw.
void | radioInterface::RadioInterface.SerialStreamEvent (SerialStreamEvent serialStreamEvent)
| This is a call-back function that SerialStreamListener must implement.
void | radioInterface::RadioInterface.setCommandTimedOut ()
| Used by the TimeOut thread to signal that the acknowledge from the radio timed out.
void | radioInterface::RadioInterface.terminateCommunication ()
| Closes the connected SerialStream.

## Function Documentation

void radioInterface.RadioInterface.addNewAssociationIndicationListeners | ( | NewAssociationIndicationListener | naiListener | ) | `[inherited]`

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

Parameters:

  | naiListener | NewAssociationIndicationListener to be added.

Definition at line 354 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00354                                                                                                         {
    00355
    00356                 NewAssociationIndicationListeners.add( NewAssociationIndicationListener.class, naiListener );
    00357         }

void radioInterface.RadioInterface.addNewDataIndicationListeners | ( | NewDataIndicationListener | ndiListener | ) | `[inherited]`

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

Parameters:

  | ndiListener | NewDataIndicationListener to be added.

Definition at line 452 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00452                                                                                           {
    00453
    00454                 NewDataIndicationListeners.add( NewDataIndicationListener.class, ndiListener );
    00455         }

void radioInterface.RadioInterface.addNewDisassociationIndicationListeners | ( | NewDisassociationIndicationListener | ndiListener | ) | `[inherited]`

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

Parameters:

  | ndiListener | NewDisassociationIndicationListener to be added.

Definition at line 403 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00403                                                                                                               {
    00404
    00405                 NewDisassociationIndicationListeners.add( NewDisassociationIndicationListener.class, ndiListener );
    00406         }

void radioInterface.RadioInterface.disableIndications | ( |  | ) | `[inherited]`

Disables NewAssociatioIndication, NewDataIndication and NewDisassociationIndication. Also disables SerialStreamEvents.

See also:
  disableSerialStreamEvents

Definition at line 187 of file RadioInterface.java.

References serialInterface.SerialStream.disableSerialStreamEvents().

Referenced by main.EventHandler.MainFrameEvent().

    00187                                          {
    00188
    00189                 io.disableSerialStreamEvents( );
    00190                 IndicationsEnabled = false;
    00191         }

Here is the call graph for this function:

void radioInterface.RadioInterface.enableIndications | ( |  | ) | `[inherited]`

Enables NewAssociatioIndication, NewDataIndication and NewDisassociationIndication. Also enables SerialStreamEvents.

See also:
  enableSerialStreamEvents

Definition at line 171 of file RadioInterface.java.

References serialInterface.SerialStream.enableSerialStreamEvents().

Referenced by main.EventHandler.MainFrameEvent().

    00171                                         {
    00172
    00173                 io.enableSerialStreamEvents( );
    00174                 IndicationsEnabled = true;
    00175         }

Here is the call graph for this function:

void radioInterface.RadioInterface.fireNewAssociationIndicationListeners | ( | NewAssociationIndication | newDataEvent | ) | `[protected, inherited]`

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

Parameters:

  | newDataEvent | Inject new NewAssociationIndication instance to the dispatcher.

Definition at line 381 of file RadioInterface.java.

Referenced by radioInterface.RadioInterface.SerialStreamEvent().

    00381                                                                                                      {
    00382
    00383                 Object[ ] listeners = NewAssociationIndicationListeners.getListenerList( );
    00384                 int numberOfListeners = listeners.length;
    00385
    00386                 for( int i = 0; i < numberOfListeners; i+=2 ){
    00387
    00388                         if( listeners[ i ] == NewAssociationIndicationListener.class ){
    00389                                 ( (NewAssociationIndicationListener)listeners[ i + 1 ] ).NewAssociationIndicationEvent( newDataEvent );
    00390                         }
    00391                 }
    00392         }

void radioInterface.RadioInterface.fireNewDataIndicationListeners | ( | NewDataIndication | newDataEvent | ) | `[protected, inherited]`

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

Parameters:

  | newDataEvent | Inject new NewDataIndication instance to the dispatcher.

Definition at line 479 of file RadioInterface.java.

Referenced by radioInterface.RadioInterface.SerialStreamEvent().

    00479                                                                                        {
    00480
    00481                 Object[ ] listeners = NewAssociationIndicationListeners.getListenerList( );
    00482                 int numberOfListeners = listeners.length;
    00483
    00484                 for( int i = 0; i < numberOfListeners; i+=2 ){
    00485
    00486                         if( listeners[ i ] == NewAssociationIndicationListener.class ){
    00487                                 ( (NewDataIndicationListener)listeners[ i + 1 ] ).NewDataIndicationEvent( newDataEvent );
    00488                         }
    00489                 }
    00490         }

void radioInterface.RadioInterface.fireNewDisassociationIndicationListeners | ( | NewDisassociationIndication | newDataEvent | ) | `[protected, inherited]`

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

Parameters:

  | newDataEvent | Inject new NewDisassociationIndication instance to the dispatcher.

Definition at line 430 of file RadioInterface.java.

Referenced by radioInterface.RadioInterface.SerialStreamEvent().

    00430                                                                                                            {
    00431
    00432                 Object[ ] listeners = NewAssociationIndicationListeners.getListenerList( );
    00433                 int numberOfListeners = listeners.length;
    00434
    00435                 for( int i = 0; i < numberOfListeners; i+=2 ){
    00436
    00437                         if( listeners[ i ] == NewAssociationIndicationListener.class ){
    00438                                 ( (NewDisassociationIndicationListener)listeners[ i + 1 ] ).NewDisassociationIndicationEvent( newDataEvent );
    00439                         }
    00440                 }
    00441         }

radioInterface.RadioInterface.RadioInterface | ( | SerialPort | portToUse | ) | throws RadioInterfaceStartException`[inherited]`

Class constructor that generates a new AT-Command interface.

Note:
  Remember to configure the SerialPort in advance of starting a new radio interface.

Parameters:

  | portToUse | SerialPort instance to where the radio hw is connected.

Exceptions:

  | RadioInterfaceStartException | If it was impossible to append a serial stream to the desired SerialPort.

Definition at line 63 of file RadioInterface.java.

References serialInterface.SerialStream.addSerialStreamEventListener().

    00063                                                                                          {
    00064
    00065                 try{
    00066                         this.io = new SerialStream( portToUse );
    00067                 }catch( SerialStreamException sse ){
    00068
    00069                         sse.printStackTrace( );
    00070                         throw new RadioInterfaceStartException( "ERROR: Could not start the Radio Interface." );
    00071                 }
    00072
    00073                 this.openPort = portToUse;
    00074                 io.addSerialStreamEventListener( this );
    00075                 IndicationsEnabled = false;
    00076                 CommandTimedOut = false;
    00077         }

Here is the call graph for this function:

void radioInterface.RadioInterface.removeNewAssociationIndicationListeners | ( | NewAssociationIndicationListener | naiListener | ) | `[inherited]`

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

Parameters:

  | naiListener | NewAssociationIndicationListener to remove.

Definition at line 368 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00368                                                                                                            {
    00369                 NewAssociationIndicationListeners.remove( NewAssociationIndicationListener.class, naiListener );
    00370         }

void radioInterface.RadioInterface.removeNewDataIndicationListeners | ( | NewDataIndicationListener | ndiListener | ) | `[inherited]`

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

Parameters:

  | ndiListener | NewDataIndicationListener to remove.

Definition at line 466 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00466                                                                                              {
    00467                 NewDataIndicationListeners.remove( NewDataIndicationListener.class, ndiListener );
    00468         }

void radioInterface.RadioInterface.removeNewDisassociationIndicationListeners | ( | NewDisassociationIndicationListener | ndiListener | ) | `[inherited]`

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

Parameters:

  | ndiListener | NewDisassociationIndicationListener to remove.

Definition at line 417 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00417                                                                                                                  {
    00418                 NewDisassociationIndicationListeners.remove( NewDisassociationIndicationListener.class, ndiListener );
    00419         }

boolean radioInterface.RadioInterface.sendConfigure | ( | String | channel,
|  | String | panID,
|  | String | deviceType |
| ) |  |  | `[inherited]`

Sends the AT+C command and arguments to the radio hw.

Returns:
  True if the AT+C command was acknowledged with the correct response and within time. False will be returned in every other case.

Definition at line 115 of file RadioInterface.java.

    00115                                                                                         {
    00116
    00117                 //Coordinator
    00118                 if( deviceType.equals( "Coordinator" ) ){
    00119
    00120                         return sendCommandToRadio( "AT+C: " + channel + "," + panID + "," + 'C', "OK" );
    00121                 }
    00122                 //End Device
    00123                 else{
    00124
    00125                         return sendCommandToRadio( "AT+C: " + channel + "," + panID + "," + 'E'
    00126                                          , "OK" );
    00127                 }
    00128         }

boolean radioInterface.RadioInterface.sendData | ( | String | data | ) | `[inherited]`

Sends the AT+T command and arguments to the radio hw.

Returns:
  True if the AT+T command was acknowledged with the correct response and within time. False will be returned in every other case.

Definition at line 140 of file RadioInterface.java.

    00140                                               {
    00141
    00142                 return sendCommandToRadio( "AT+T: " + Integer.toHexString( data.length( ) ).toUpperCase( ) + ',' +
    00143                                 data, "OK" );
    00144         }

boolean radioInterface.RadioInterface.sendDisAssociate | ( |  | ) | `[inherited]`

Sends the AT+D command to the radio hw.

Returns:
  True if the AT+D command was acknowledged with the correct response and within time. False will be returned in every other case.

Definition at line 156 of file RadioInterface.java.

    00156                                           {
    00157
    00158                 return sendCommandToRadio( "AT+D", "OK" );
    00159         }

boolean radioInterface.RadioInterface.sendReset | ( |  | ) | `[inherited]`

Sends the AT+R command to the radio hw.

Returns:
  True if the AT+R command was acknowledged with the correct response and within time. False will be returned in every other case.

Definition at line 100 of file RadioInterface.java.

    00100                                    {
    00101
    00102                 return sendCommandToRadio( "AT+R", "OK" );
    00103         }

void radioInterface.RadioInterface.SerialStreamEvent | ( | SerialStreamEvent | serialStreamEvent | ) | `[inherited]`

This is a call-back function that SerialStreamListener must implement.

This function is called whenever a new SerialStreamEvent has been fired. The function will check the event to see if it is a candidate for a NewAssociationIndication, NewDataIndication or NewDisassociationIndication.

See also:
  SerialStreamEvent, NewAssociationIndication, NewDataIndication, NewDisassociation.

Parameters:

  | serialStreamEvent | SerialStreamEvent fired by the SerialStream.

TODO Add feedback to the debug window.

Implements serialInterface.SerialStreamListener.

Definition at line 284 of file RadioInterface.java.

References radioInterface.RadioInterface.fireNewAssociationIndicationListeners(), radioInterface.RadioInterface.fireNewDataIndicationListeners(), radioInterface.RadioInterface.fireNewDisassociationIndicationListeners(), and serialInterface.SerialStreamEvent.getResponse().

    00284                                                                             {
    00285
    00286                 int i, ii;
    00287                 String response = serialStreamEvent.getResponse(  );
    00288                 String dataLength;
    00289
    00290                 //Events enabled.
    00291                 if( IndicationsEnabled ){
    00292
    00293                         //The received string has the correct preamble.
    00294                         if( response.charAt( 0 ) == '+' ){
    00295
    00296                                 //Read next character to find what type
    00297                                 //of indication this is.
    00298                                 switch( response.charAt( 1 ) ){
    00299
    00300                                         //New Association Indication.
    00301                                         case 'N':
    00302
    00303                                                 fireNewAssociationIndicationListeners( new NewAssociationIndication( ) );
    00304                                                 break;
    00305
    00306                                         //New Disassociation Indication.
    00307                                         case 'D':
    00308
    00309                                                 fireNewDisassociationIndicationListeners( new NewDisassociationIndication( ) );
    00310                                                 break;
    00311
    00312                                         //New Data Indication.
    00313                                         case 'T':
    00314
    00315                                                 //Loop through char 4 to 6 (length is worst case 3 chars).
    00316                                                 for( ii = 4; ( ii <= 6 );ii++ ){
    00317
    00318                                                         //Break as soon as the argument ends.
    00319                                                         if( response.charAt( ii ) == ',' ){
    00320
    00321                                                                 break;
    00322                                                         }
    00323                                                 }
    00324
    00325                                                 dataLength = response.substring( 4, ii );
    00326
    00327                                                 //Convert to integer representation
    00328                                                 i = Integer.parseInt( dataLength );
    00329
    00330                                                 //Extract "real" data
    00331                                                 ii++;
    00332                                                 String subMsg = response.substring( ii, ii+i );
    00333
    00334                                                 fireNewDataIndicationListeners( new NewDataIndication( subMsg, i ) );
    00335                                                 break;
    00336
    00337                                         default:
    00339                                                 break;
    00340                                 }
    00341                         }
    00342                 }
    00343         }

Here is the call graph for this function:

void radioInterface.RadioInterface.setCommandTimedOut | ( |  | ) | `[inherited]`

Used by the TimeOut thread to signal that the acknowledge from the radio timed out.

See also:
  TimeOut

Definition at line 263 of file RadioInterface.java.

Referenced by radioInterface.TimeOut.run().

    00263                                          {
    00264                 CommandTimedOut = true;
    00265         }

void radioInterface.RadioInterface.terminateCommunication | ( |  | ) | `[inherited]`

Closes the connected SerialStream.

Definition at line 85 of file RadioInterface.java.

Referenced by main.EventHandler.MainFrameEvent().

    00085                                              {
    00086
    00087                 this.openPort.close( );
    00088         }

@DOC_TITLE@