| 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 |
|