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 #define UDR UDR0 00109 #define UCR UCSR0B 00110 #define RXCIE RXCIE0 00111 #define TXCIE TXCIE0 00112 #define RXC RXC0 00113 #define TXC TXC0 00114 #define RXEN RXEN0 00115 #define TXEN TXEN0 00116 #define UBRRL UBRR0L 00117 #define UBRRH UBRR0H 00118 #define SIG_UART_TRANS SIG_USART_TRANS 00119 #define SIG_UART_RECV SIG_USART_RECV 00120 #define SIG_UART_DATA SIG_USART_DATA 00121 #endif 00122 // compatibility with mega169 processors 00123 #if defined(__AVR_ATmega169__) 00124 #define SIG_UART_TRANS SIG_USART_TRANS 00125 #define SIG_UART_RECV SIG_USART_RECV 00126 #define SIG_UART_DATA SIG_USART_DATA 00127 #endif 00128 // compatibility with dual-uart processors 00129 // (if you need to use both uarts, please use the uart2 library) 00130 #if defined(__AVR_ATmega161__) 00131 #define UDR UDR0 00132 #define UCR UCSR0B 00133 #define UBRRL UBRR0 00134 #define SIG_UART_TRANS SIG_UART0_TRANS 00135 #define SIG_UART_RECV SIG_UART0_RECV 00136 #define SIG_UART_DATA SIG_UART0_DATA 00137 #endif 00138 #if defined(__AVR_ATmega128__) 00139 #ifdef UART_USE_UART1 00140 #define UDR UDR1 00141 #define UCR UCSR1B 00142 #define UBRRL UBRR1L 00143 #define UBRRH UBRR1H 00144 #define SIG_UART_TRANS SIG_UART1_TRANS 00145 #define SIG_UART_RECV SIG_UART1_RECV 00146 #define SIG_UART_DATA SIG_UART1_DATA 00147 #else 00148 #define UDR UDR0 00149 #define UCR UCSR0B 00150 #define UBRRL UBRR0L 00151 #define UBRRH UBRR0H 00152 #define SIG_UART_TRANS SIG_UART0_TRANS 00153 #define SIG_UART_RECV SIG_UART0_RECV 00154 #define SIG_UART_DATA SIG_UART0_DATA 00155 #endif 00156 #endif 00157 00158 // functions 00159 00160 //! Initializes uart. 00161 /// \note After running this init function, the processor 00162 /// I/O pins that used for uart communications (RXD, TXD) 00163 /// are no long available for general purpose I/O. 00164 void uartInit(void); 00165 00166 //! Initializes transmit and receive buffers. 00167 /// Automatically called from uartInit() 00168 void uartInitBuffers(void); 00169 00170 //! Redirects received data to a user function. 00171 /// 00172 void uartSetRxHandler(void (*rx_func)(unsigned char c)); 00173 00174 //! Sets the uart baud rate. 00175 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600); 00176 void uartSetBaudRate(u32 baudrate); 00177 00178 //! Returns pointer to the receive buffer structure. 00179 /// 00180 cBuffer* uartGetRxBuffer(void); 00181 00182 //! Returns pointer to the transmit buffer structure. 00183 /// 00184 cBuffer* uartGetTxBuffer(void); 00185 00186 //! Sends a single byte over the uart. 00187 /// \note This function waits for the uart to be ready, 00188 /// therefore, consecutive calls to uartSendByte() will 00189 /// go only as fast as the data can be sent over the 00190 /// serial port. 00191 void uartSendByte(u08 data); 00192 00193 //! Gets a single byte from the uart receive buffer. 00194 /// Returns the byte, or -1 if no byte is available (getchar-style). 00195 int uartGetByte(void); 00196 00197 //! Gets a single byte from the uart receive buffer. 00198 /// Function returns TRUE if data was available, FALSE if not. 00199 /// Actual data is returned in variable pointed to by "data". 00200 /// Example usage: 00201 /// \code 00202 /// char myReceivedByte; 00203 /// uartReceiveByte( &myReceivedByte ); 00204 /// \endcode 00205 u08 uartReceiveByte(u08* data); 00206 00207 //! Returns TRUE/FALSE if receive buffer is empty/not-empty. 00208 /// 00209 u08 uartReceiveBufferIsEmpty(void); 00210 00211 //! Flushes (deletes) all data from receive buffer. 00212 /// 00213 void uartFlushReceiveBuffer(void); 00214 00215 //! Add byte to end of uart Tx buffer. 00216 /// Returns TRUE if successful, FALSE if failed (no room left in buffer). 00217 u08 uartAddToTxBuffer(u08 data); 00218 00219 //! Begins transmission of the transmit buffer under interrupt control. 00220 /// 00221 void uartSendTxBuffer(void); 00222 00223 //! Sends a block of data via the uart using interrupt control. 00224 /// \param buffer pointer to data to be sent 00225 /// \param nBytes length of data (number of bytes to sent) 00226 u08 uartSendBuffer(char *buffer, u16 nBytes); 00227 00228 #endif 00229 //@} 00230 00231