Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# uart.h

Go to the documentation of this file.

    00001 /*! \file uart.h \brief UART driver with buffer support. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'uart.h'
    00005 // Title        : UART driver with buffer support
    00006 // Author       : Pascal Stang - Copyright (C) 2000-2002
    00007 // Created      : 11/22/2000
    00008 // Revised      : 02/01/2004
    00009 // Version      : 1.3
    00010 // Target MCU   : ATMEL AVR Series
    00011 // Editor Tabs  : 4
    00012 //
    00013 // This code is distributed under the GNU Public License
    00014 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00015 //
    00016 /// \ingroup driver_avr
    00017 /// \defgroup uart UART Driver/Function Library (uart.c)
    00018 /// \code #include "uart.h" \endcode
    00019 /// \par Overview
    00020 ///     This library provides both buffered and unbuffered transmit and receive
    00021 ///     functions for the AVR processor UART.  Buffered access means that the
    00022 ///     UART can transmit and receive data in the "background", while your code
    00023 ///     continues executing.  Also included are functions to initialize the
    00024 ///     UART, set the baud rate, flush the buffers, and check buffer status.
    00025 ///
    00026 /// \note   For full text output functionality, you may wish to use the rprintf
    00027 ///     functions along with this driver.
    00028 ///
    00029 /// \par About UART operations
    00030 ///     Most Atmel AVR-series processors contain one or more hardware UARTs
    00031 ///     (aka, serial ports).  UART serial ports can communicate with other
    00032 ///     serial ports of the same type, like those used on PCs.  In general,
    00033 ///     UARTs are used to communicate with devices that are RS-232 compatible
    00034 ///     (RS-232 is a certain kind of serial port).
    00035 /// \par
    00036 ///     By far, the most common use for serial communications on AVR processors
    00037 ///     is for sending information and data to a PC running a terminal program.
    00038 ///     Here is an exmaple:
    00039 /// \code
    00040 /// uartInit();                 // initialize UART (serial port)
    00041 /// uartSetBaudRate(9600);      // set UART speed to 9600 baud
    00042 /// rprintfInit(uartSendByte);  // configure rprintf to use UART for output
    00043 /// rprintf("Hello World\r\n"); // send "hello world" message via serial port
    00044 /// \endcode
    00045 ///
    00046 /// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h
    00047 ///     for the UART library to calculate correct baud rates.  Furthermore,
    00048 ///     certain CPU frequencies will not produce exact baud rates due to
    00049 ///     integer frequency division round-off.  See your AVR processor's
    00050 ///      datasheet for full details.
    00051 //
    00052 //*****************************************************************************
    00053 //@{
    00054
    00055 #ifndef UART_H
    00056 #define UART_H
    00057
    00058 #include "global.h"
    00059 #include "buffer.h"
    00060
    00061 //! Default uart baud rate.
    00062 /// This is the default speed after a uartInit() command,
    00063 /// and can be changed by using uartSetBaudRate().
    00064 #define UART_DEFAULT_BAUD_RATE  9600
    00065
    00066 // buffer memory allocation defines
    00067 // buffer sizes
    00068 #ifndef UART_TX_BUFFER_SIZE
    00069 //! Number of bytes for uart transmit buffer.
    00070 /// Do not change this value in uart.h, but rather override
    00071 /// it with the desired value defined in your project's global.h
    00072 #define UART_TX_BUFFER_SIZE     0x0040
    00073 #endif
    00074 #ifndef UART_RX_BUFFER_SIZE
    00075 //! Number of bytes for uart receive buffer.
    00076 /// Do not change this value in uart.h, but rather override
    00077 /// it with the desired value defined in your project's global.h
    00078 #define UART_RX_BUFFER_SIZE     0x0040
    00079 #endif
    00080
    00081 // define this key if you wish to use
    00082 // external RAM for the UART buffers
    00083 //#define UART_BUFFER_EXTERNAL_RAM
    00084 #ifdef UART_BUFFER_EXTERNAL_RAM
    00085     // absolute address of uart buffers
    00086     #define UART_TX_BUFFER_ADDR 0x1000
    00087     #define UART_RX_BUFFER_ADDR 0x1100
    00088 #endif
    00089
    00090 //! Type of interrupt handler to use for uart interrupts.
    00091 /// Value may be SIGNAL or INTERRUPT.
    00092 /// \warning Do not change unless you know what you're doing.
    00093 #ifndef UART_INTERRUPT_HANDLER
    00094 #define UART_INTERRUPT_HANDLER  SIGNAL
    00095 #endif
    00096
    00097 // compatibility with most newer processors
    00098 #ifdef UCSRB
    00099     #define UCR                 UCSRB
    00100 #endif
    00101 // compatibility with old Mega processors
    00102 #if defined(UBRR) && !defined(UBRRL)
    00103     #define UBRRL               UBRR
    00104 #endif
    00105 // compatibility with megaXX8 processors
    00106 #if defined(__AVR_ATmega88__)   || \
    00107     defined(__AVR_ATmega168__)  || \
    00108     defined(__AVR_ATmega644__)
    00109     #define UDR                 UDR0
    00110     #define UCR                 UCSR0B
    00111     #define RXCIE               RXCIE0
    00112     #define TXCIE               TXCIE0
    00113     #define RXC                 RXC0
    00114     #define TXC                 TXC0
    00115     #define RXEN                RXEN0
    00116     #define TXEN                TXEN0
    00117     #define UBRRL               UBRR0L
    00118     #define UBRRH               UBRR0H
    00119     #define SIG_UART_TRANS      SIG_USART_TRANS
    00120     #define SIG_UART_RECV       SIG_USART_RECV
    00121     #define SIG_UART_DATA       SIG_USART_DATA
    00122 #endif
    00123 // compatibility with mega169 processors
    00124 #if defined(__AVR_ATmega169__)
    00125     #define SIG_UART_TRANS      SIG_USART_TRANS
    00126     #define SIG_UART_RECV       SIG_USART_RECV
    00127     #define SIG_UART_DATA       SIG_USART_DATA
    00128 #endif
    00129 // compatibility with dual-uart processors
    00130 // (if you need to use both uarts, please use the uart2 library)
    00131 #if defined(__AVR_ATmega161__)
    00132     #define UDR                 UDR0
    00133     #define UCR                 UCSR0B
    00134     #define UBRRL               UBRR0
    00135     #define SIG_UART_TRANS      SIG_UART0_TRANS
    00136     #define SIG_UART_RECV       SIG_UART0_RECV
    00137     #define SIG_UART_DATA       SIG_UART0_DATA
    00138 #endif
    00139 #if defined(__AVR_ATmega128__)
    00140 #ifdef UART_USE_UART1
    00141     #define UDR                 UDR1
    00142     #define UCR                 UCSR1B
    00143     #define UBRRL               UBRR1L
    00144     #define UBRRH               UBRR1H
    00145     #define SIG_UART_TRANS      SIG_UART1_TRANS
    00146     #define SIG_UART_RECV       SIG_UART1_RECV
    00147     #define SIG_UART_DATA       SIG_UART1_DATA
    00148 #else
    00149     #define UDR                 UDR0
    00150     #define UCR                 UCSR0B
    00151     #define UBRRL               UBRR0L
    00152     #define UBRRH               UBRR0H
    00153     #define SIG_UART_TRANS      SIG_UART0_TRANS
    00154     #define SIG_UART_RECV       SIG_UART0_RECV
    00155     #define SIG_UART_DATA       SIG_UART0_DATA
    00156 #endif
    00157 #endif
    00158
    00159 // functions
    00160
    00161 //! Initializes uart.
    00162 /// \note   After running this init function, the processor
    00163 /// I/O pins that used for uart communications (RXD, TXD)
    00164 /// are no long available for general purpose I/O.
    00165 void uartInit(void);
    00166
    00167 //! Initializes transmit and receive buffers.
    00168 /// Automatically called from uartInit()
    00169 void uartInitBuffers(void);
    00170
    00171 //! Redirects received data to a user function.
    00172 ///
    00173 void uartSetRxHandler(void (*rx_func)(unsigned char c));
    00174
    00175 //! Sets the uart baud rate.
    00176 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600);
    00177 void uartSetBaudRate(u32 baudrate);
    00178
    00179 //! Returns pointer to the receive buffer structure.
    00180 ///
    00181 cBuffer* uartGetRxBuffer(void);
    00182
    00183 //! Returns pointer to the transmit buffer structure.
    00184 ///
    00185 cBuffer* uartGetTxBuffer(void);
    00186
    00187 //! Sends a single byte over the uart.
    00188 /// \note This function waits for the uart to be ready,
    00189 /// therefore, consecutive calls to uartSendByte() will
    00190 /// go only as fast as the data can be sent over the
    00191 /// serial port.
    00192 void uartSendByte(u08 data);
    00193
    00194 //! Gets a single byte from the uart receive buffer.
    00195 /// Returns the byte, or -1 if no byte is available (getchar-style).
    00196 int uartGetByte(void);
    00197
    00198 //! Gets a single byte from the uart receive buffer.
    00199 /// Function returns TRUE if data was available, FALSE if not.
    00200 /// Actual data is returned in variable pointed to by "data".
    00201 /// Example usage:
    00202 /// \code
    00203 /// char myReceivedByte;
    00204 /// uartReceiveByte( &myReceivedByte );
    00205 /// \endcode
    00206 u08 uartReceiveByte(u08* data);
    00207
    00208 //! Returns TRUE/FALSE if receive buffer is empty/not-empty.
    00209 ///
    00210 u08 uartReceiveBufferIsEmpty(void);
    00211
    00212 //! Flushes (deletes) all data from receive buffer.
    00213 ///
    00214 void uartFlushReceiveBuffer(void);
    00215
    00216 //! Add byte to end of uart Tx buffer.
    00217 /// Returns TRUE if successful, FALSE if failed (no room left in buffer).
    00218 u08 uartAddToTxBuffer(u08 data);
    00219
    00220 //! Begins transmission of the transmit buffer under interrupt control.
    00221 ///
    00222 void uartSendTxBuffer(void);
    00223
    00224 //! Sends a block of data via the uart using interrupt control.
    00225 /// \param buffer   pointer to data to be sent
    00226 /// \param nBytes   length of data (number of bytes to sent)
    00227 u08  uartSendBuffer(char *buffer, u16 nBytes);
    00228
    00229 #endif
    00230 //@}
    00231
    00232