AVR Z-LINK®

serialPortHAL.h File Reference

---

Detailed Description

This file defines the serial interface. Either USART or USB. Controlled by the UART/FTDI flags on line 28/29.

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.h,v

Date

2006/09/15 17:02:44

Definition in file serialPortHAL.h.

#include <stdbool.h>
#include <stdint.h>
#include "compiler.h"
#include "chat.h"
#include "usart.h"

Include dependency graph for serialPortHAL.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	rxDataBlock_t
	Buffer struct used by the receiver. More...
Defines
#define	EOC_DELIMITER   '\r'
#define	LENGTH_OF_COMMAND   4
#define	LENGTH_OF_PARAMETER_BUFFER   64
#define	NULL_PARAMETER   ((unsigned char *)0)
#define	NUMBER_OF_PARAMETERS   4
#define	PARAMETER_DELIMITER   ','
#define	PARAMETER_PREAMBLE_A   ':'
#define	PARAMETER_PREAMBLE_B   ' '
#define	RECEIVE_BUFFER_SIZE   64
#define	RECEIVER_OFF   DISABLE_RECEIVE_COMPLETE_INTERRUPT
#define	RECEIVER_ON   ENABLE_RECEIVE_COMPLETE_INTERRUPT
#define	UART
Enumerations
enum	paramter_t { PARAMETER_1 = 0x00, PARAMETER_2 = 0x01, PARAMETER_3 = 0x02 }
	Enumeration that defines possible parameters to extract from a command. More...
enum	rxError_t {   NO_ERROR = 0x00, BUFFER_OVERFLOW, UNKNOWN_RX_STATE, UNKNOWN_SEQUENCE,   UNKNOWN_EOC_SEQUENCE }
	Possible receiver errors. More...
enum	rxState_t { SOC = 0x00, PARAM_PREAMBLE, COLLECT_PARAMETERS, EOC }
	Enumeration that defines possible error states that the serial interface might stumble into. More...
Functions
bool	dataAvailable (void)
	Function that is used to poll if new data is available.
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).
void	serialInterfaceInitialization (void)
	This function handles the initialization of the serial interface.

---

Define Documentation

#define EOC_DELIMITER   '\r'

Definition at line 63 of file serialPortHAL.h.

Referenced by ISR().

#define LENGTH_OF_COMMAND   4

Definition at line 94 of file serialPortHAL.h.

Referenced by ISR().

#define LENGTH_OF_PARAMETER_BUFFER   64

Definition at line 98 of file serialPortHAL.h.

Referenced by ISR().

#define NULL_PARAMETER   ((unsigned char *)0)

Definition at line 65 of file serialPortHAL.h.

Referenced by getParameterNumber().

#define NUMBER_OF_PARAMETERS   4

Definition at line 99 of file serialPortHAL.h.

Referenced by getParameterNumber(), and ISR().

#define PARAMETER_DELIMITER   ','

Definition at line 60 of file serialPortHAL.h.

Referenced by ISR().

#define PARAMETER_PREAMBLE_A   ':'

Definition at line 61 of file serialPortHAL.h.

Referenced by ISR().

#define PARAMETER_PREAMBLE_B   ' '

Definition at line 62 of file serialPortHAL.h.

Referenced by ISR().

#define RECEIVE_BUFFER_SIZE   64

Definition at line 48 of file serialPortHAL.h.

#define RECEIVER_OFF   DISABLE_RECEIVE_COMPLETE_INTERRUPT

Definition at line 53 of file serialPortHAL.h.

Referenced by ISR(), and rxReset().

#define RECEIVER_ON   ENABLE_RECEIVE_COMPLETE_INTERRUPT

Definition at line 52 of file serialPortHAL.h.

Referenced by rxReset().

#define UART

Definition at line 27 of file serialPortHAL.h.

---

Enumeration Type Documentation

enum paramter_t

Enumeration that defines possible parameters to extract from a command.

Enumerator:

PARAMETER_1
PARAMETER_2
PARAMETER_3

Definition at line 110 of file serialPortHAL.h.

            {
        PARAMETER_1     = 0x00,
        PARAMETER_2     = 0x01,
        PARAMETER_3     = 0x02
}paramter_t;

enum rxError_t

Possible receiver errors.

Enumerator:

NO_ERROR
BUFFER_OVERFLOW
UNKNOWN_RX_STATE
UNKNOWN_SEQUENCE
UNKNOWN_EOC_SEQUENCE

Definition at line 81 of file serialPortHAL.h.

            {
        
        NO_ERROR = 0x00,
        BUFFER_OVERFLOW,
        UNKNOWN_RX_STATE,
        UNKNOWN_SEQUENCE,
        UNKNOWN_EOC_SEQUENCE
}rxError_t;

enum rxState_t

Enumeration that defines possible error states that the serial
interface might stumble into.

Enumerator:

SOC
PARAM_PREAMBLE
COLLECT_PARAMETERS
EOC

Definition at line 71 of file serialPortHAL.h.

            {
        
        SOC = 0x00,     //StartOfCommand.
        PARAM_PREAMBLE,         //": "
        COLLECT_PARAMETERS,
        EOC     //EndOfCommand.
}rxState_t;

---

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().

                          {

        return rxData.receptionComplete;
}

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().

                                    {

        return  ( unsigned char * )rxData.ATCommand;
}

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.

                          {

        return rxData.error;
}

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().

                                                                {
        
        if( parameterNumber < NUMBER_OF_PARAMETERS ){
  
                return rxData.parameter[ parameterNumber ];
        }
  
  
        else{
  
                return NULL_PARAMETER;
        }
}

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().

                             {
        
        uint8_t receivedData;
        
        receivedData = ( uint8_t )UDR0; //Collect data.
#else
        ISR( INT7_vect ){
          
        unsigned char receivedData;
        
        receivedData = ( uint8_t )*FTDI_Fifo;   //Collect data.
#endif

        switch( rxState ){
        
                case SOC:
                  
                  if( rxData.rx_i <= LENGTH_OF_COMMAND ){
                        
                        if( receivedData == PARAMETER_PREAMBLE_A ){
                                
                                rxData.ATCommand[ rxData.rx_i ] = '\0';
                                rxState = PARAM_PREAMBLE;
                        }
                        
                        else if( receivedData == EOC_DELIMITER ){
                                
                                rxData.ATCommand[ rxData.rx_i ] = '\0';
                                rxState = EOC;
                        }
                        
                        else{
                        
                                rxData.ATCommand[ rxData.rx_i++ ] = receivedData;  
                        }
                  }
                  
                  else{
                  
                        RECEIVER_OFF;
                        rxData.error = BUFFER_OVERFLOW;
                        rxData.receptionComplete = true;                
                  }
                
                break;
                
                case PARAM_PREAMBLE:
                  
                  if( receivedData == PARAMETER_PREAMBLE_B ){
                        
                        rxData.rx_i = 0;
                        rxData.parameter[ rxData.numberOfReceivedParameters++ ] = \
                                          &rxData.parameters[ rxData.rx_i ];
                        rxState = COLLECT_PARAMETERS;
                  }
                  
                  else{
                  
                        RECEIVER_OFF;
                        rxData.error = UNKNOWN_SEQUENCE;
                        rxData.receptionComplete = true;                                
                  }
                  
                break;
                
                case COLLECT_PARAMETERS:
                        
                  
                        if( ( rxData.rx_i < LENGTH_OF_PARAMETER_BUFFER )&& 
                                ( rxData.numberOfReceivedParameters < NUMBER_OF_PARAMETERS ) )
                        {
                        
                                if( receivedData == PARAMETER_DELIMITER ){
                          
                                        rxData.parameters[ rxData.rx_i++ ] = '\0';
                                        rxData.parameter[ rxData.numberOfReceivedParameters++ ] = \
                                          &rxData.parameters[ rxData.rx_i ];
                                }
                                
                                
                                else if( receivedData == EOC_DELIMITER ){
                                        
                                        rxData.parameters[ rxData.rx_i ] = '\0';
                                        rxState = EOC;
                                }
                                
                                else{
                        
                                        rxData.parameters[ rxData.rx_i++ ] = receivedData;  
                                }
                  }
                  
                  else{
                  
                        RECEIVER_OFF;
                        rxData.error = BUFFER_OVERFLOW;
                        rxData.receptionComplete = true;                
                  }  
                break;
                
                case EOC:
                        
                        RECEIVER_OFF;
                        
                        if( receivedData != '\n' ){
                        
                                rxData.error = UNKNOWN_EOC_SEQUENCE;  
                        }
                        
                        rxData.receptionComplete = true;
                break;
                
                default:
                        
                        RECEIVER_OFF;
                        rxData.error = UNKNOWN_RX_STATE;
                        rxData.receptionComplete = true;
                break;
        }
}

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().

                    {
        
        unsigned char dummy = 0x00;
        
        RECEIVER_OFF;
        
        rxState = SOC;
        
        rxData.rx_i = dummy;
        rxData.ATCommand[ rxData.rx_i ] = dummy;
        rxData.parameters[ rxData.rx_i ] = dummy;
        rxData.numberOfReceivedParameters = dummy;
        rxData.receptionComplete = false;
        rxData.error = NO_ERROR;

#ifdef UART     
        //Following loop is used to ensure that the rx FIFO is flushed.
        //Sometimes it gets cloged up with old data.
        for( ;  UCSR0A & ( 1 << RXC0 ); ){
                
                dummy = UDR0;  
        }
#endif

        RECEIVER_ON;
}

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().

                                        {
        
        sendFlashString( ASSOCIATION_NOTIFICATION );
        sendFlashString( CRNL );

        return;
}

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().

                                                                {
        
        uint8_t i, ii, dataLength;
        unsigned char valueReversed[ 3 ];
        unsigned char asciiValue[ 4 ];
        
        dataLength = length;
        
        //Make sure that only 3 iterations are made.
        for( i = ii = 0; (ii < 3) && ( dataLength != 0 ) ; ii++ ){
        
                i = dataLength % 10;
                dataLength = dataLength / 10;
                
                valueReversed[ ii ] = i + '0';
        }
        
        asciiValue[ ii ] = '\0';        //Terminate string
        
        //Reverse the order of digits.
        for( i = 0, ii; ii > 0 ; ii--, i++ ){
        
                asciiValue[ i ] = valueReversed[ ii - 1 ];  
        }
        
        
        sendFlashString( NEW_DATA_NOTIFICATION );
        sendString( asciiValue );
        //sendStringWithLength( asciiValue, length );   //Dummy...hardcoded.
        sendSymbol( ',' );
        sendStringWithLength( data, length );
        sendFlashString( CRNL );

        return;
}

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().

                                           {
        
        sendFlashString( DISASSOCIATION_NOTIFICATION );
        sendFlashString( CRNL );

        return;
}

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().

                                       {

        sendFlashString( ERROR );
          
        //Convert from err to ascii hex:
        sendSymbol( errToHex( (err & 0xF0) >> 4 ) );    //MSB
        sendSymbol( errToHex( err & 0x0F ) );   //LSB
        
        sendFlashString( CRNL );

        return;
}

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().

                                                           {

  for( ; *string != '\0'; ){
    
    sendSymbol( *string++ );
  }

  return;
}

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().

                   {

  sendFlashString( OK );

  return;
}

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().

                                              {

  for( ; *string != '\0'; ){
    
        sendSymbol( *string++ );
        }

        return;
}

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().

                                          {
  
#ifdef UART
        
        uartInitialization( BR_38400 );
#else
        ftdiInitialization( );
#endif
}

Here is the call graph for this function: