Rev 1145 Rev 1858
1 /*! \file uart.h \brief UART driver with buffer support. */ 1 /*! \file uart.h \brief UART driver with buffer support. */
2 //***************************************************************************** 2 //*****************************************************************************
3 // 3 //
4 // File Name : 'uart.h' 4 // File Name : 'uart.h'
5 // Title : UART driver with buffer support 5 // Title : UART driver with buffer support
6 // Author : Pascal Stang - Copyright (C) 2000-2002 6 // Author : Pascal Stang - Copyright (C) 2000-2002
7 // Created : 11/22/2000 7 // Created : 11/22/2000
8 // Revised : 02/01/2004 8 // Revised : 02/01/2004
9 // Version : 1.3 9 // Version : 1.3
10 // Target MCU : ATMEL AVR Series 10 // Target MCU : ATMEL AVR Series
11 // Editor Tabs : 4 11 // Editor Tabs : 4
12 // 12 //
13 // This code is distributed under the GNU Public License 13 // This code is distributed under the GNU Public License
14 // which can be found at http://www.gnu.org/licenses/gpl.txt 14 // which can be found at http://www.gnu.org/licenses/gpl.txt
15 // 15 //
16 /// \ingroup driver_avr 16 /// \ingroup driver_avr
17 /// \defgroup uart UART Driver/Function Library (uart.c) 17 /// \defgroup uart UART Driver/Function Library (uart.c)
18 /// \code #include "uart.h" \endcode 18 /// \code #include "uart.h" \endcode
19 /// \par Overview 19 /// \par Overview
20 /// This library provides both buffered and unbuffered transmit and receive 20 /// This library provides both buffered and unbuffered transmit and receive
21 /// functions for the AVR processor UART.  Buffered access means that the 21 /// functions for the AVR processor UART.  Buffered access means that the
22 /// UART can transmit and receive data in the "background", while your code 22 /// UART can transmit and receive data in the "background", while your code
23 /// continues executing.  Also included are functions to initialize the 23 /// continues executing.  Also included are functions to initialize the
24 /// UART, set the baud rate, flush the buffers, and check buffer status. 24 /// UART, set the baud rate, flush the buffers, and check buffer status.
25 /// 25 ///
26 /// \note For full text output functionality, you may wish to use the rprintf 26 /// \note For full text output functionality, you may wish to use the rprintf
27 /// functions along with this driver. 27 /// functions along with this driver.
28 /// 28 ///
29 /// \par About UART operations 29 /// \par About UART operations
30 /// Most Atmel AVR-series processors contain one or more hardware UARTs 30 /// Most Atmel AVR-series processors contain one or more hardware UARTs
31 /// (aka, serial ports). UART serial ports can communicate with other 31 /// (aka, serial ports). UART serial ports can communicate with other
32 /// serial ports of the same type, like those used on PCs. In general, 32 /// serial ports of the same type, like those used on PCs. In general,
33 /// UARTs are used to communicate with devices that are RS-232 compatible 33 /// UARTs are used to communicate with devices that are RS-232 compatible
34 /// (RS-232 is a certain kind of serial port). 34 /// (RS-232 is a certain kind of serial port).
35 /// \par 35 /// \par
36 /// By far, the most common use for serial communications on AVR processors 36 /// By far, the most common use for serial communications on AVR processors
37 /// is for sending information and data to a PC running a terminal program. 37 /// is for sending information and data to a PC running a terminal program.
38 /// Here is an exmaple: 38 /// Here is an exmaple:
39 /// \code 39 /// \code
40 /// uartInit(); // initialize UART (serial port) 40 /// uartInit(); // initialize UART (serial port)
41 /// uartSetBaudRate(9600); // set UART speed to 9600 baud 41 /// uartSetBaudRate(9600); // set UART speed to 9600 baud
42 /// rprintfInit(uartSendByte); // configure rprintf to use UART for output 42 /// rprintfInit(uartSendByte); // configure rprintf to use UART for output
43 /// rprintf("Hello World\r\n"); // send "hello world" message via serial port 43 /// rprintf("Hello World\r\n"); // send "hello world" message via serial port
44 /// \endcode 44 /// \endcode
45 /// 45 ///
46 /// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h 46 /// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h
47 /// for the UART library to calculate correct baud rates. Furthermore, 47 /// for the UART library to calculate correct baud rates. Furthermore,
48 /// certain CPU frequencies will not produce exact baud rates due to 48 /// certain CPU frequencies will not produce exact baud rates due to
49 /// integer frequency division round-off. See your AVR processor's 49 /// integer frequency division round-off. See your AVR processor's
50 /// datasheet for full details. 50 /// datasheet for full details.
51 // 51 //
52 //***************************************************************************** 52 //*****************************************************************************
53 //@{ 53 //@{
54   54  
55 #ifndef UART_H 55 #ifndef UART_H
56 #define UART_H 56 #define UART_H
57   57  
58 #include "global.h" 58 #include "global.h"
59 #include "buffer.h" 59 #include "buffer.h"
60   60  
61 //! Default uart baud rate. 61 //! Default uart baud rate.
62 /// This is the default speed after a uartInit() command, 62 /// This is the default speed after a uartInit() command,
63 /// and can be changed by using uartSetBaudRate(). 63 /// and can be changed by using uartSetBaudRate().
64 #define UART_DEFAULT_BAUD_RATE 9600 64 #define UART_DEFAULT_BAUD_RATE 9600
65   65  
66 // buffer memory allocation defines 66 // buffer memory allocation defines
67 // buffer sizes 67 // buffer sizes
68 #ifndef UART_TX_BUFFER_SIZE 68 #ifndef UART_TX_BUFFER_SIZE
69 //! Number of bytes for uart transmit buffer. 69 //! Number of bytes for uart transmit buffer.
70 /// Do not change this value in uart.h, but rather override 70 /// Do not change this value in uart.h, but rather override
71 /// it with the desired value defined in your project's global.h 71 /// it with the desired value defined in your project's global.h
72 #define UART_TX_BUFFER_SIZE 0x0040 72 #define UART_TX_BUFFER_SIZE 0x0040
73 #endif 73 #endif
74 #ifndef UART_RX_BUFFER_SIZE 74 #ifndef UART_RX_BUFFER_SIZE
75 //! Number of bytes for uart receive buffer. 75 //! Number of bytes for uart receive buffer.
76 /// Do not change this value in uart.h, but rather override 76 /// Do not change this value in uart.h, but rather override
77 /// it with the desired value defined in your project's global.h 77 /// it with the desired value defined in your project's global.h
78 #define UART_RX_BUFFER_SIZE 0x0040 78 #define UART_RX_BUFFER_SIZE 0x0040
79 #endif 79 #endif
80   80  
81 // define this key if you wish to use 81 // define this key if you wish to use
82 // external RAM for the UART buffers 82 // external RAM for the UART buffers
83 //#define UART_BUFFER_EXTERNAL_RAM 83 //#define UART_BUFFER_EXTERNAL_RAM
84 #ifdef UART_BUFFER_EXTERNAL_RAM 84 #ifdef UART_BUFFER_EXTERNAL_RAM
85 // absolute address of uart buffers 85 // absolute address of uart buffers
86 #define UART_TX_BUFFER_ADDR 0x1000 86 #define UART_TX_BUFFER_ADDR 0x1000
87 #define UART_RX_BUFFER_ADDR 0x1100 87 #define UART_RX_BUFFER_ADDR 0x1100
88 #endif 88 #endif
89   89  
90 //! Type of interrupt handler to use for uart interrupts. 90 //! Type of interrupt handler to use for uart interrupts.
91 /// Value may be SIGNAL or INTERRUPT. 91 /// Value may be SIGNAL or INTERRUPT.
92 /// \warning Do not change unless you know what you're doing. 92 /// \warning Do not change unless you know what you're doing.
93 #ifndef UART_INTERRUPT_HANDLER 93 #ifndef UART_INTERRUPT_HANDLER
94 #define UART_INTERRUPT_HANDLER SIGNAL 94 #define UART_INTERRUPT_HANDLER SIGNAL
95 #endif 95 #endif
96   96  
97 // compatibility with most newer processors 97 // compatibility with most newer processors
98 #ifdef UCSRB 98 #ifdef UCSRB
99 #define UCR UCSRB 99 #define UCR UCSRB
100 #endif 100 #endif
101 // compatibility with old Mega processors 101 // compatibility with old Mega processors
102 #if defined(UBRR) && !defined(UBRRL) 102 #if defined(UBRR) && !defined(UBRRL)
103 #define UBRRL UBRR 103 #define UBRRL UBRR
104 #endif 104 #endif
105 // compatibility with megaXX8 processors 105 // compatibility with megaXX8 processors
106 #if defined(__AVR_ATmega88__) || \ 106 #if defined(__AVR_ATmega88__) || \
107 defined(__AVR_ATmega168__) || \ 107 defined(__AVR_ATmega168__) || \
108 defined(__AVR_ATmega644__) 108 defined(__AVR_ATmega644__)
109 #define UDR UDR0 109 #define UDR UDR0
110 #define UCR UCSR0B 110 #define UCR UCSR0B
111 #define RXCIE RXCIE0 111 #define RXCIE RXCIE0
112 #define TXCIE TXCIE0 112 #define TXCIE TXCIE0
113 #define RXC RXC0 113 #define RXC RXC0
114 #define TXC TXC0 114 #define TXC TXC0
115 #define RXEN RXEN0 115 #define RXEN RXEN0
116 #define TXEN TXEN0 116 #define TXEN TXEN0
117 #define UBRRL UBRR0L 117 #define UBRRL UBRR0L
118 #define UBRRH UBRR0H 118 #define UBRRH UBRR0H
119 #define SIG_UART_TRANS SIG_USART_TRANS 119 #define SIG_UART_TRANS SIG_USART_TRANS
120 #define SIG_UART_RECV SIG_USART_RECV 120 #define SIG_UART_RECV SIG_USART_RECV
121 #define SIG_UART_DATA SIG_USART_DATA 121 #define SIG_UART_DATA SIG_USART_DATA
122 #endif 122 #endif
123 // compatibility with mega169 processors 123 // compatibility with mega169 processors
124 #if defined(__AVR_ATmega169__) 124 #if defined(__AVR_ATmega169__)
125 #define SIG_UART_TRANS SIG_USART_TRANS 125 #define SIG_UART_TRANS SIG_USART_TRANS
126 #define SIG_UART_RECV SIG_USART_RECV 126 #define SIG_UART_RECV SIG_USART_RECV
127 #define SIG_UART_DATA SIG_USART_DATA 127 #define SIG_UART_DATA SIG_USART_DATA
128 #endif 128 #endif
129 // compatibility with dual-uart processors 129 // compatibility with dual-uart processors
130 // (if you need to use both uarts, please use the uart2 library) 130 // (if you need to use both uarts, please use the uart2 library)
131 #if defined(__AVR_ATmega161__) 131 #if defined(__AVR_ATmega161__)
132 #define UDR UDR0 132 #define UDR UDR0
133 #define UCR UCSR0B 133 #define UCR UCSR0B
134 #define UBRRL UBRR0 134 #define UBRRL UBRR0
135 #define SIG_UART_TRANS SIG_UART0_TRANS 135 #define SIG_UART_TRANS SIG_UART0_TRANS
136 #define SIG_UART_RECV SIG_UART0_RECV 136 #define SIG_UART_RECV SIG_UART0_RECV
137 #define SIG_UART_DATA SIG_UART0_DATA 137 #define SIG_UART_DATA SIG_UART0_DATA
138 #endif 138 #endif
139 #if defined(__AVR_ATmega128__) 139 #if defined(__AVR_ATmega128__)
140 #ifdef UART_USE_UART1 140 #ifdef UART_USE_UART1
141 #define UDR UDR1 141 #define UDR UDR1
142 #define UCR UCSR1B 142 #define UCR UCSR1B
143 #define UBRRL UBRR1L 143 #define UBRRL UBRR1L
144 #define UBRRH UBRR1H 144 #define UBRRH UBRR1H
145 #define SIG_UART_TRANS SIG_UART1_TRANS 145 #define SIG_UART_TRANS SIG_UART1_TRANS
146 #define SIG_UART_RECV SIG_UART1_RECV 146 #define SIG_UART_RECV SIG_UART1_RECV
147 #define SIG_UART_DATA SIG_UART1_DATA 147 #define SIG_UART_DATA SIG_UART1_DATA
148 #else 148 #else
149 #define UDR UDR0 149 #define UDR UDR0
150 #define UCR UCSR0B 150 #define UCR UCSR0B
151 #define UBRRL UBRR0L 151 #define UBRRL UBRR0L
152 #define UBRRH UBRR0H 152 #define UBRRH UBRR0H
153 #define SIG_UART_TRANS SIG_UART0_TRANS 153 #define SIG_UART_TRANS SIG_UART0_TRANS
154 #define SIG_UART_RECV SIG_UART0_RECV 154 #define SIG_UART_RECV SIG_UART0_RECV
155 #define SIG_UART_DATA SIG_UART0_DATA 155 #define SIG_UART_DATA SIG_UART0_DATA
156 #endif 156 #endif
157 #endif 157 #endif
158   158  
159 // functions 159 // functions
160   160  
161 //! Initializes uart. 161 //! Initializes uart.
162 /// \note After running this init function, the processor 162 /// \note After running this init function, the processor
163 /// I/O pins that used for uart communications (RXD, TXD) 163 /// I/O pins that used for uart communications (RXD, TXD)
164 /// are no long available for general purpose I/O. 164 /// are no long available for general purpose I/O.
165 void uartInit(void); 165 void uartInit(void);
166   166  
167 //! Initializes transmit and receive buffers. 167 //! Initializes transmit and receive buffers.
168 /// Automatically called from uartInit() 168 /// Automatically called from uartInit()
169 void uartInitBuffers(void); 169 void uartInitBuffers(void);
170   170  
171 //! Redirects received data to a user function. 171 //! Redirects received data to a user function.
172 /// 172 ///
173 void uartSetRxHandler(void (*rx_func)(unsigned char c)); 173 void uartSetRxHandler(void (*rx_func)(unsigned char c));
174   174  
175 //! Sets the uart baud rate. 175 //! Sets the uart baud rate.
176 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600); 176 /// Argument should be in bits-per-second, like \c uartSetBaudRate(9600);
177 void uartSetBaudRate(u32 baudrate); 177 void uartSetBaudRate(u32 baudrate);
178   178  
179 //! Returns pointer to the receive buffer structure. 179 //! Returns pointer to the receive buffer structure.
180 /// 180 ///
181 cBuffer* uartGetRxBuffer(void); 181 cBuffer* uartGetRxBuffer(void);
182   182  
183 //! Returns pointer to the transmit buffer structure. 183 //! Returns pointer to the transmit buffer structure.
184 /// 184 ///
185 cBuffer* uartGetTxBuffer(void); 185 cBuffer* uartGetTxBuffer(void);
186   186  
187 //! Sends a single byte over the uart. 187 //! Sends a single byte over the uart.
188 /// \note This function waits for the uart to be ready, 188 /// \note This function waits for the uart to be ready,
189 /// therefore, consecutive calls to uartSendByte() will 189 /// therefore, consecutive calls to uartSendByte() will
190 /// go only as fast as the data can be sent over the 190 /// go only as fast as the data can be sent over the
191 /// serial port. 191 /// serial port.
192 void uartSendByte(u08 data); 192 void uartSendByte(u08 data);
193   193  
194 //! Gets a single byte from the uart receive buffer. 194 //! Gets a single byte from the uart receive buffer.
195 /// Returns the byte, or -1 if no byte is available (getchar-style). 195 /// Returns the byte, or -1 if no byte is available (getchar-style).
196 int uartGetByte(void); 196 int uartGetByte(void);
197   197  
198 //! Gets a single byte from the uart receive buffer. 198 //! Gets a single byte from the uart receive buffer.
199 /// Function returns TRUE if data was available, FALSE if not. 199 /// Function returns TRUE if data was available, FALSE if not.
200 /// Actual data is returned in variable pointed to by "data". 200 /// Actual data is returned in variable pointed to by "data".
201 /// Example usage: 201 /// Example usage:
202 /// \code 202 /// \code
203 /// char myReceivedByte; 203 /// char myReceivedByte;
204 /// uartReceiveByte( &myReceivedByte ); 204 /// uartReceiveByte( &myReceivedByte );
205 /// \endcode 205 /// \endcode
206 u08 uartReceiveByte(u08* data); 206 u08 uartReceiveByte(u08* data);
207   207  
208 //! Returns TRUE/FALSE if receive buffer is empty/not-empty. 208 //! Returns TRUE/FALSE if receive buffer is empty/not-empty.
209 /// 209 ///
210 u08 uartReceiveBufferIsEmpty(void); 210 u08 uartReceiveBufferIsEmpty(void);
211   211  
212 //! Flushes (deletes) all data from receive buffer. 212 //! Flushes (deletes) all data from receive buffer.
213 /// 213 ///
214 void uartFlushReceiveBuffer(void); 214 void uartFlushReceiveBuffer(void);
215   215  
216 //! Add byte to end of uart Tx buffer. 216 //! Add byte to end of uart Tx buffer.
217 /// Returns TRUE if successful, FALSE if failed (no room left in buffer). 217 /// Returns TRUE if successful, FALSE if failed (no room left in buffer).
218 u08 uartAddToTxBuffer(u08 data); 218 u08 uartAddToTxBuffer(u08 data);
219   219  
220 //! Begins transmission of the transmit buffer under interrupt control. 220 //! Begins transmission of the transmit buffer under interrupt control.
221 /// 221 ///
222 void uartSendTxBuffer(void); 222 void uartSendTxBuffer(void);
223   223  
224 //! Sends a block of data via the uart using interrupt control. 224 //! Sends a block of data via the uart using interrupt control.
225 /// \param buffer pointer to data to be sent 225 /// \param buffer pointer to data to be sent
226 /// \param nBytes length of data (number of bytes to sent) 226 /// \param nBytes length of data (number of bytes to sent)
227 u08 uartSendBuffer(char *buffer, u16 nBytes); 227 u08 uartSendBuffer(char *buffer, u16 nBytes);
228   228  
229 #endif 229 #endif
230 //@} 230 //@}
231   231  
232   232