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