| AVR Z-LINKŪ |

# serialPortHAL.c File Reference

## Detailed Description

This defines hardware abstraction level, so that the it is invisible to the next higher layer if the USART0 or FTDI USB chip is used for serial communication.

Application note:
  AVR414: User's Guide - ATAVRRZ502 - Accessory Kit

Documentation
  For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html

Author:
  Atmel Corporation: http://www.atmel.com
  Support email: avr@atmel.com

Name

Revision
  1.2

RCSfile
  serialInterface.c,v

Date
  2006/09/15 17:02:19

Definition in file serialPortHAL.c.

`#include "serialPortHAL.h"`

Include dependency graph for serialPortHAL.c:

Go to the source code of this file.

## Functions
bool | dataAvailable (void)
| Function that is used to poll if new data is available.
static uint8_t | errToHex (uint8_t hexNibble)
| Returns the rxError_t member of the rxDataBlock_t struct.
unsigned char * | getATCommand (void)
| Returns a pointer to the read AT-Command.
rxError_t | getError (void)
| Returns the rxError_t member of the rxDataBlock_t struct.
unsigned char * | getParameterNumber (paramter_t parameterNumber)
| Returns a pointer to the specified parameter.
| ISR (USART0_RX_vect)
| Universal receive interrupt service routine for both USART0 and the FTDI USB chip.
void | rxReset (void)
| This function is used to reset the receive interrupt and associated variables.
void | sendAssociationNotification (void)
| Send notification over the serial link that an end-device has associated successfully.
void | sendDataNotification (uint8_t length, unsigned char *data)
| Send notification when new data has been received.
void | sendDisAssociationNotification (void)
| Send notification over the serial link when the the other peer has requested to leave (disassociate).
void | sendERROR (const chatError_t err)
| Send an error message over the serial link.
void | sendFlashString (const unsigned char __flash *string)
| Send a flash string over the serial link (USART or USB).
void | sendOK (void)
| Send the "OK" string over the serial link.
void | sendString (const unsigned char *string)
| Send a string over the serial link (USART or USB).
static void | sendStringWithLength (const unsigned char *string, const uint8_t strLength)
| Internal (static) method used by sendDataNotification() to send a string with a given length.
static void | sendSymbol (const unsigned char symbol)
| Send one symbol on the serial line.
void | serialInterfaceInitialization (void)
| This function handles the initialization of the serial interface.
## Variables
const unsigned char __flash | ASSOCIATION_NOTIFICATION [] = "+N"
| String sent over the serial interface to notify tha a device has successfully been associated to the coordinator.
const unsigned char __flash | CRNL [] = "\r\n"
| Carrige Return New Line.
const unsigned char __flash | DISASSOCIATION_NOTIFICATION [] = "+D"
| String sent over the serial interface to notify that the associated end-device has successfully left the network.
const unsigned char __flash | ERROR [] = "ERROR: 0x"
| String sent over the serial interface whenever an error occurs. Used by the sendERROR() function.
const uint8_t __flash | hexTable [] = "0123456789ABCDEF"
| Look-up table used by errToHex() to do hex conversions.
const unsigned char __flash | NEW_DATA_NOTIFICATION [] = "+T: "
| String sent over the serial interface to notify that new data has been received.
const unsigned char __flash | OK [] = "OK\r\n"
| String sent over the serial interface whenever an AT-Command terminates successfully.
rxDataBlock_t | rxData
rxState_t | rxState

## Function Documentation

bool dataAvailable | ( | void |  | ) |

Function that is used to poll if new data is available.

Returns:
  True if new data is available. False else.

Definition at line 161 of file serialPortHAL.c.

References rxDataBlock_t::receptionComplete, and rxData.

Referenced by main().

    00161                           {
    00162
    00163         return rxData.receptionComplete;
    00164 }

static uint8_t errToHex | ( | uint8_t | hexNibble | ) | `[static]`

Returns the rxError_t member of the rxDataBlock_t struct.

Returns:
  rxError_t associated with the last reception.

Definition at line 292 of file serialPortHAL.c.

References hexTable.

Referenced by sendERROR().

    00292                                             {
    00293
    00294         return hexTable[ hexNibble ];
    00295 }

unsigned char* getATCommand | ( | void |  | ) |

Returns a pointer to the read AT-Command.

Returns:
  pointer to AT-Command in the received string.

Definition at line 142 of file serialPortHAL.c.

References rxDataBlock_t::ATCommand, and rxData.

Referenced by handleNewCommand().

    00142                                     {
    00143
    00144         return  ( unsigned char * )rxData.ATCommand;
    00145 }

rxError_t getError | ( | void |  | ) |

Returns the rxError_t member of the rxDataBlock_t struct.

Returns:
  Error associated with the last reception.

Definition at line 151 of file serialPortHAL.c.

References rxDataBlock_t::error, and rxData.

    00151                           {
    00152
    00153         return rxData.error;
    00154 }

unsigned char* getParameterNumber | ( | paramter_t | parameterNumber | ) |

Returns a pointer to the specified parameter.

Parameters:

  | parameterNumber | What parameter to be returned.

Returns:
  Pointer into the receive buffer to the start of the parameter. Or a null pointer if the requested parameter is out of bounds.

Definition at line 173 of file serialPortHAL.c.

References NULL_PARAMETER, NUMBER_OF_PARAMETERS, rxDataBlock_t::parameter, and rxData.

Referenced by handleNewCommand().

    00173                                                                 {
    00174
    00175         if( parameterNumber < NUMBER_OF_PARAMETERS ){
    00176
    00177                 return rxData.parameter[ parameterNumber ];
    00178         }
    00179
    00180
    00181         else{
    00182
    00183                 return NULL_PARAMETER;
    00184         }
    00185 }

ISR | ( | USART0_RX_vect |  | ) |

Universal receive interrupt service routine for both USART0 and the FTDI USB chip.

This routine is called whenever a new byte is available to be read. This service routine does also implement a sort of pre parsing since the received stream of bytes comes in a known pattern (AT-Commands). Where data is read from is controlled through the UART or FTDI flag. So the only difference is the interrupt vector and where to read data from.

Definition at line 397 of file serialPortHAL.c.

References rxDataBlock_t::ATCommand, BUFFER_OVERFLOW, COLLECT_PARAMETERS, EOC, EOC_DELIMITER, rxDataBlock_t::error, FTDI_Fifo, ISR(), LENGTH_OF_COMMAND, LENGTH_OF_PARAMETER_BUFFER, NUMBER_OF_PARAMETERS, rxDataBlock_t::numberOfReceivedParameters, PARAM_PREAMBLE, rxDataBlock_t::parameter, PARAMETER_DELIMITER, PARAMETER_PREAMBLE_A, PARAMETER_PREAMBLE_B, rxDataBlock_t::parameters, RECEIVER_OFF, rxDataBlock_t::receptionComplete, rxDataBlock_t::rx_i, rxData, rxState, SOC, UNKNOWN_EOC_SEQUENCE, UNKNOWN_RX_STATE, and UNKNOWN_SEQUENCE.

Referenced by ISR().

    00397                              {
    00398
    00399         uint8_t receivedData;
    00400
    00401         receivedData = ( uint8_t )UDR0; //Collect data.
    00402 #else
    00403         ISR( INT7_vect ){
    00404
    00405         unsigned char receivedData;
    00406
    00407         receivedData = ( uint8_t )*FTDI_Fifo;   //Collect data.
    00408 #endif
    00409
    00410         switch( rxState ){
    00411
    00412                 case SOC:
    00413
    00414                   if( rxData.rx_i <= LENGTH_OF_COMMAND ){
    00415
    00416                         if( receivedData == PARAMETER_PREAMBLE_A ){
    00417
    00418                                 rxData.ATCommand[ rxData.rx_i ] = '\0';
    00419                                 rxState = PARAM_PREAMBLE;
    00420                         }
    00421
    00422                         else if( receivedData == EOC_DELIMITER ){
    00423
    00424                                 rxData.ATCommand[ rxData.rx_i ] = '\0';
    00425                                 rxState = EOC;
    00426                         }
    00427
    00428                         else{
    00429
    00430                                 rxData.ATCommand[ rxData.rx_i++ ] = receivedData;
    00431                         }
    00432                   }
    00433
    00434                   else{
    00435
    00436                         RECEIVER_OFF;
    00437                         rxData.error = BUFFER_OVERFLOW;
    00438                         rxData.receptionComplete = true;
    00439                   }
    00440
    00441                 break;
    00442
    00443                 case PARAM_PREAMBLE:
    00444
    00445                   if( receivedData == PARAMETER_PREAMBLE_B ){
    00446
    00447                         rxData.rx_i = 0;
    00448                         rxData.parameter[ rxData.numberOfReceivedParameters++ ] = \
    00449                                           &rxData.parameters[ rxData.rx_i ];
    00450                         rxState = COLLECT_PARAMETERS;
    00451                   }
    00452
    00453                   else{
    00454
    00455                         RECEIVER_OFF;
    00456                         rxData.error = UNKNOWN_SEQUENCE;
    00457                         rxData.receptionComplete = true;
    00458                   }
    00459
    00460                 break;
    00461
    00462                 case COLLECT_PARAMETERS:
    00463
    00464
    00465                         if( ( rxData.rx_i < LENGTH_OF_PARAMETER_BUFFER )&&
    00466                                 ( rxData.numberOfReceivedParameters < NUMBER_OF_PARAMETERS ) )
    00467                         {
    00468
    00469                                 if( receivedData == PARAMETER_DELIMITER ){
    00470
    00471                                         rxData.parameters[ rxData.rx_i++ ] = '\0';
    00472                                         rxData.parameter[ rxData.numberOfReceivedParameters++ ] = \
    00473                                           &rxData.parameters[ rxData.rx_i ];
    00474                                 }
    00475
    00476
    00477                                 else if( receivedData == EOC_DELIMITER ){
    00478
    00479                                         rxData.parameters[ rxData.rx_i ] = '\0';
    00480                                         rxState = EOC;
    00481                                 }
    00482
    00483                                 else{
    00484
    00485                                         rxData.parameters[ rxData.rx_i++ ] = receivedData;
    00486                                 }
    00487                   }
    00488
    00489                   else{
    00490
    00491                         RECEIVER_OFF;
    00492                         rxData.error = BUFFER_OVERFLOW;
    00493                         rxData.receptionComplete = true;
    00494                   }
    00495                 break;
    00496
    00497                 case EOC:
    00498
    00499                         RECEIVER_OFF;
    00500
    00501                         if( receivedData != '\n' ){
    00502
    00503                                 rxData.error = UNKNOWN_EOC_SEQUENCE;
    00504                         }
    00505
    00506                         rxData.receptionComplete = true;
    00507                 break;
    00508
    00509                 default:
    00510
    00511                         RECEIVER_OFF;
    00512                         rxData.error = UNKNOWN_RX_STATE;
    00513                         rxData.receptionComplete = true;
    00514                 break;
    00515         }
    00516 }

Here is the call graph for this function:

void rxReset | ( | void |  | ) |

This function is used to reset the receive interrupt and associated variables.

Definition at line 111 of file serialPortHAL.c.

References rxDataBlock_t::ATCommand, rxDataBlock_t::error, NO_ERROR, rxDataBlock_t::numberOfReceivedParameters, rxDataBlock_t::parameters, RECEIVER_OFF, RECEIVER_ON, rxDataBlock_t::receptionComplete, rxDataBlock_t::rx_i, rxData, rxState, and SOC.

Referenced by main().

    00111                     {
    00112
    00113         unsigned char dummy = 0x00;
    00114
    00115         RECEIVER_OFF;
    00116
    00117         rxState = SOC;
    00118
    00119         rxData.rx_i = dummy;
    00120         rxData.ATCommand[ rxData.rx_i ] = dummy;
    00121         rxData.parameters[ rxData.rx_i ] = dummy;
    00122         rxData.numberOfReceivedParameters = dummy;
    00123         rxData.receptionComplete = false;
    00124         rxData.error = NO_ERROR;
    00125
    00126 #ifdef UART
    00127         //Following loop is used to ensure that the rx FIFO is flushed.
    00128         //Sometimes it gets cloged up with old data.
    00129         for( ;  UCSR0A & ( 1 << RXC0 ); ){
    00130
    00131                 dummy = UDR0;
    00132         }
    00133 #endif
    00134
    00135         RECEIVER_ON;
    00136 }

void sendAssociationNotification | ( | void |  | ) |

Send notification over the serial link that an end-device has associated successfully.

Message format: <+N
>

Definition at line 303 of file serialPortHAL.c.

References ASSOCIATION_NOTIFICATION, CRNL, and sendFlashString().

Referenced by usr_mlme_comm_status_ind().

    00303                                         {
    00304
    00305         sendFlashString( ASSOCIATION_NOTIFICATION );
    00306         sendFlashString( CRNL );
    00307
    00308         return;
    00309 }

Here is the call graph for this function:

void sendDataNotification | ( | uint8_t | length,
|  | unsigned char * | data |
| ) |  |  |

Send notification when new data has been received.

Message format: <+T: [length],[data payload]
>

Parameters:

  | length | Length of data in bytes.
  | data | Pointer to data.

Definition at line 333 of file serialPortHAL.c.

References CRNL, NEW_DATA_NOTIFICATION, sendFlashString(), sendString(), sendStringWithLength(), and sendSymbol().

Referenced by usr_mcps_data_ind().

    00333                                                                 {
    00334
    00335         uint8_t i, ii, dataLength;
    00336         unsigned char valueReversed[ 3 ];
    00337         unsigned char asciiValue[ 4 ];
    00338
    00339         dataLength = length;
    00340
    00341         //Make sure that only 3 iterations are made.
    00342         for( i = ii = 0; (ii < 3) && ( dataLength != 0 ) ; ii++ ){
    00343
    00344                 i = dataLength % 10;
    00345                 dataLength = dataLength / 10;
    00346
    00347                 valueReversed[ ii ] = i + '0';
    00348         }
    00349
    00350         asciiValue[ ii ] = '\0';        //Terminate string
    00351
    00352         //Reverse the order of digits.
    00353         for( i = 0, ii; ii > 0 ; ii--, i++ ){
    00354
    00355                 asciiValue[ i ] = valueReversed[ ii - 1 ];
    00356         }
    00357
    00358
    00359         sendFlashString( NEW_DATA_NOTIFICATION );
    00360         sendString( asciiValue );
    00361         //sendStringWithLength( asciiValue, length );   //Dummy...hardcoded.
    00362         sendSymbol( ',' );
    00363         sendStringWithLength( data, length );
    00364         sendFlashString( CRNL );
    00365
    00366         return;
    00367 }

Here is the call graph for this function:

void sendDisAssociationNotification | ( | void |  | ) |

Send notification over the serial link when the the other peer has requested to leave (disassociate).

Message format: <+D
>

Definition at line 316 of file serialPortHAL.c.

References CRNL, DISASSOCIATION_NOTIFICATION, and sendFlashString().

    00316                                            {
    00317
    00318         sendFlashString( DISASSOCIATION_NOTIFICATION );
    00319         sendFlashString( CRNL );
    00320
    00321         return;
    00322 }

Here is the call graph for this function:

void sendERROR | ( | const chatError_t | err | ) |

Send an error message over the serial link.

The sent string will be "ERROR: " and then one of the follwing hex values:

- 0x80UNKNOWN_AT_COMMAND
- 0x81EVENT_BUFFER_FULL
- 0x82INVALID_REQUEST
- 0x83RESET_FAILED
- 0x84UNKNOWN_DEVICE_TYPE
- 0x85INCONSISTENT_STATE
- 0x86ACTIVE_SCAN_FAILED
- 0x87SET_MAC_ADDRESS_FAILED
- 0x88START_FAILED
- 0x89START_NETWORK_FAILED
- 0x8AASSOCIATION_FAILED
- 0x8BDATA_TRANSMISSION_FAILED
- 0x80DATA_CONVERSION_FAILED

Parameters:

  | err | Error type to return with. Must be a valid number for the chatError_t type.

Definition at line 274 of file serialPortHAL.c.

References CRNL, ERROR, errToHex(), sendFlashString(), and sendSymbol().

Referenced by handleNewCommand(), sendMsg(), usr_mcps_data_conf(), usr_mlme_associate_conf(), usr_mlme_reset_conf(), usr_mlme_scan_conf(), usr_mlme_set_conf(), and usr_mlme_start_conf().

    00274                                        {
    00275
    00276         sendFlashString( ERROR );
    00277
    00278         //Convert from err to ascii hex:
    00279         sendSymbol( errToHex( (err & 0xF0) >> 4 ) );    //MSB
    00280         sendSymbol( errToHex( err & 0x0F ) );   //LSB
    00281
    00282         sendFlashString( CRNL );
    00283
    00284         return;
    00285 }

Here is the call graph for this function:

void sendFlashString | ( | const unsigned char __flash * | string | ) |

Send a flash string over the serial link (USART or USB).

Parameters:

  | string | string to be sent.

Definition at line 228 of file serialPortHAL.c.

References sendSymbol().

Referenced by sendAssociationNotification(), sendDataNotification(), sendDisAssociationNotification(), sendERROR(), and sendOK().

    00228                                                            {
    00229
    00230   for( ; *string != '\0'; ){
    00231
    00232     sendSymbol( *string++ );
    00233   }
    00234
    00235   return;
    00236 }

Here is the call graph for this function:

void sendOK | ( | void |  | ) |

Send the "OK" string over the serial link.

Definition at line 242 of file serialPortHAL.c.

References OK, and sendFlashString().

Referenced by usr_mcps_data_conf(), usr_mlme_associate_conf(), usr_mlme_reset_conf(), and usr_mlme_set_conf().

    00242                    {
    00243
    00244   sendFlashString( OK );
    00245
    00246   return;
    00247 }

Here is the call graph for this function:

void sendString | ( | const unsigned char * | string | ) |

Send a string over the serial link (USART or USB).

Parameters:

  | string | string to be sent.

Definition at line 213 of file serialPortHAL.c.

References sendSymbol().

Referenced by sendDataNotification().

    00213                                               {
    00214
    00215   for( ; *string != '\0'; ){
    00216
    00217         sendSymbol( *string++ );
    00218         }
    00219
    00220         return;
    00221 }

Here is the call graph for this function:

static void sendStringWithLength | ( | const unsigned char * | string,
|  | const uint8_t | strLength |
| ) |  |  | `[static]`

Internal (static) method used by sendDataNotification() to send a string with a given length.

Parameters:

  | string | String to send bytes from.
  | strLength | Number of bytes to send.

Definition at line 376 of file serialPortHAL.c.

References sendSymbol().

Referenced by sendDataNotification().

    00376                                                                                         {
    00377
    00378   uint8_t i;
    00379
    00380   for( i = 0; i < strLength; i++ ){
    00381
    00382     sendSymbol( *string++ );
    00383   }
    00384
    00385   return;
    00386 }

Here is the call graph for this function:

static void sendSymbol | ( | const unsigned char | symbol | ) | `[static]`

Send one symbol on the serial line.

This function passes one symbol (8 bits) to the USART module on the AVR or the FTDI USB chip.

Note:
  serialInterfaceInitialization must be called first.

Parameters:

  | symbol | Symbol to be sent.

Definition at line 197 of file serialPortHAL.c.

References ftdiSendSymbol(), and uartSendSymbol().

Referenced by sendDataNotification(), sendERROR(), sendFlashString(), sendString(), and sendStringWithLength().

    00197                                                     {
    00198
    00199 #ifdef UART
    00200
    00201         uartSendSymbol( symbol );
    00202 #else
    00203         ftdiSendSymbol( symbol );
    00204 #endif
    00205 }

Here is the call graph for this function:

void serialInterfaceInitialization | ( | void |  | ) |

This function handles the initialization of the serial interface.

What serial interface that actually will be initialized is controlled by the UART or FTDI flag. If the UART flag is defined USART0 is defined with a sybol size of 8 bits, no parity and one stop bit. If FTDI is defined the FTDI USB chip will be setup the same way.

Note:
  The serial interface has only been verified to work with the
  baud rates as defined in the baudRate_t enumeration.

Definition at line 97 of file serialPortHAL.c.

References BR_38400, ftdiInitialization(), and uartInitialization().

Referenced by applicationInit().

    00097                                           {
    00098
    00099 #ifdef UART
    00100
    00101         uartInitialization( BR_38400 );
    00102 #else
    00103         ftdiInitialization( );
    00104 #endif
    00105 }

Here is the call graph for this function:

## Variable Documentation

const unsigned char __flash ASSOCIATION_NOTIFICATION[] = "+N"

String sent over the serial interface to notify tha a device has successfully been associated to the coordinator.

Definition at line 52 of file serialPortHAL.c.

Referenced by sendAssociationNotification().

const unsigned char __flash CRNL[] = "\r\n"

Carrige Return New Line.

Definition at line 72 of file serialPortHAL.c.

Referenced by sendAssociationNotification(), sendDataNotification(), sendDisAssociationNotification(), and sendERROR().

const unsigned char __flash DISASSOCIATION_NOTIFICATION[] = "+D"

String sent over the serial interface to notify that the associated end-device has successfully left the network.

Definition at line 59 of file serialPortHAL.c.

Referenced by sendDisAssociationNotification().

const unsigned char __flash ERROR[] = "ERROR: 0x"

String sent over the serial interface whenever an error occurs. Used by the sendERROR() function.

Definition at line 45 of file serialPortHAL.c.

Referenced by sendERROR().

const uint8_t __flash hexTable[] = "0123456789ABCDEF"

Look-up table used by errToHex() to do hex conversions.

Definition at line 78 of file serialPortHAL.c.

Referenced by errToHex().

const unsigned char __flash NEW_DATA_NOTIFICATION[] = "+T: "

String sent over the serial interface to notify that new data has been received.

Definition at line 66 of file serialPortHAL.c.

Referenced by sendDataNotification().

const unsigned char __flash OK[] = "OK\r\n"

String sent over the serial interface whenever an AT-Command terminates successfully.

Definition at line 38 of file serialPortHAL.c.

Referenced by sendOK().

rxDataBlock_t rxData

Definition at line 30 of file serialPortHAL.c.

Referenced by dataAvailable(), getATCommand(), getError(), getParameterNumber(), ISR(), and rxReset().

rxState_t rxState

Definition at line 31 of file serialPortHAL.c.

Referenced by ISR(), and rxReset().

@DOC_TITLE@