1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
/**
* \file
*
* \brief Serial Mode management
*
* Copyright (c) 2010-2015 Atmel Corporation. All rights reserved.
*
* \asf_license_start
*
* \page License
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. The name of Atmel may not be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* 4. This software may only be redistributed and used in connection with an
* Atmel microcontroller product.
*
* THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
* EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* \asf_license_stop
*
*/
/*
* Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
*/
#ifndef SERIAL_H_INCLUDED
#define SERIAL_H_INCLUDED
#include <parts.h>
#include "status_codes.h"
/**
* \typedef usart_if
*
* This type can be used independently to refer to USART module for the
* architecture used. It refers to the correct type definition for the
* architecture, ie. USART_t* for XMEGA or avr32_usart_t* for UC3.
*/
#if XMEGA
# include "xmega_usart/usart_serial.h"
#elif MEGA_RF
# include "megarf_usart/usart_serial.h"
#elif UC3
# include "uc3_usart/usart_serial.h"
#elif (SAMB)
#include "samb_uart/uart_serial.h"
#elif (SAM0)
#include "sam0_usart/usart_serial.h"
#elif SAM
# include "sam_uart/uart_serial.h"
#else
# error Unsupported chip type
#endif
/**
*
* \defgroup serial_group Serial Interface (Serial)
*
* See \ref serial_quickstart.
*
* This is the common API for serial interface. Additional features are available
* in the documentation of the specific modules.
*
* \section serial_group_platform Platform Dependencies
*
* The serial API is partially chip- or platform-specific. While all
* platforms provide mostly the same functionality, there are some
* variations around how different bus types and clock tree structures
* are handled.
*
* The following functions are available on all platforms, but there may
* be variations in the function signature (i.e. parameters) and
* behaviour. These functions are typically called by platform-specific
* parts of drivers, and applications that aren't intended to be
* portable:
* - usart_serial_init()
* - usart_serial_putchar()
* - usart_serial_getchar()
* - usart_serial_write_packet()
* - usart_serial_read_packet()
*
*
* @{
*/
//! @}
/**
* \page serial_quickstart Quick start guide for Serial Interface service
*
* This is the quick start guide for the \ref serial_group "Serial Interface module", with
* step-by-step instructions on how to configure and use the serial in a
* selection of use cases.
*
* The use cases contain several code fragments. The code fragments in the
* steps for setup can be copied into a custom initialization function, while
* the steps for usage can be copied into, e.g., the main application function.
*
* \section serial_use_cases Serial use cases
* - \ref serial_basic_use_case
* - \subpage serial_use_case_1
*
* \section serial_basic_use_case Basic use case - transmit a character
* In this use case, the serial module is configured for:
* - Using USARTD0
* - Baudrate: 9600
* - Character length: 8 bit
* - Parity mode: Disabled
* - Stop bit: None
* - RS232 mode
*
* The use case waits for a received character on the configured USART and
* echoes the character back to the same USART.
*
* \section serial_basic_use_case_setup Setup steps
*
* \subsection serial_basic_use_case_setup_prereq Prerequisites
* -# \ref sysclk_group "System Clock Management (sysclk)"
*
* \subsection serial_basic_use_case_setup_code Example code
* The following configuration must be added to the project (typically to a
* conf_uart_serial.h file, but it can also be added to your main application file.)
*
* \note The following takes SAM3X configuration for example, other devices have similar
* configuration, but their parameters may be different, refer to corresponding header files.
*
* \code
#define USART_SERIAL &USARTD0
#define USART_SERIAL_BAUDRATE 9600
#define USART_SERIAL_CHAR_LENGTH US_MR_CHRL_8_BIT
#define USART_SERIAL_PARITY US_MR_PAR_NO
#define USART_SERIAL_STOP_BIT false
\endcode
*
* A variable for the received byte must be added:
* \code uint8_t received_byte; \endcode
*
* Add to application initialization:
* \code
sysclk_init();
static usart_serial_options_t usart_options = {
.baudrate = USART_SERIAL_BAUDRATE,
.charlength = USART_SERIAL_CHAR_LENGTH,
.paritytype = USART_SERIAL_PARITY,
.stopbits = USART_SERIAL_STOP_BIT
};
usart_serial_init(USART_SERIAL, &usart_options);
\endcode
*
* \subsection serial_basic_use_case_setup_flow Workflow
* -# Initialize system clock:
* - \code sysclk_init(); \endcode
* -# Create serial USART options struct:
* - \code
static usart_serial_options_t usart_options = {
.baudrate = USART_SERIAL_BAUDRATE,
.charlength = USART_SERIAL_CHAR_LENGTH,
.paritytype = USART_SERIAL_PARITY,
.stopbits = USART_SERIAL_STOP_BIT
};
\endcode
* -# Initialize the serial service:
* - \code usart_serial_init(USART_SERIAL, &usart_options);\endcode
*
* \section serial_basic_use_case_usage Usage steps
*
* \subsection serial_basic_use_case_usage_code Example code
* Add to application C-file:
* \code
usart_serial_getchar(USART_SERIAL, &received_byte);
usart_serial_putchar(USART_SERIAL, received_byte);
\endcode
*
* \subsection serial_basic_use_case_usage_flow Workflow
* -# Wait for reception of a character:
* - \code usart_serial_getchar(USART_SERIAL, &received_byte); \endcode
* -# Echo the character back:
* - \code usart_serial_putchar(USART_SERIAL, received_byte); \endcode
*/
/**
* \page serial_use_case_1 Advanced use case - Send a packet of serial data
*
* In this use case, the USART module is configured for:
* - Using USARTD0
* - Baudrate: 9600
* - Character length: 8 bit
* - Parity mode: Disabled
* - Stop bit: None
* - RS232 mode
*
* The use case sends a string of text through the USART.
*
* \section serial_use_case_1_setup Setup steps
*
* \subsection serial_use_case_1_setup_prereq Prerequisites
* -# \ref sysclk_group "System Clock Management (sysclk)"
*
* \subsection serial_use_case_1_setup_code Example code
* The following configuration must be added to the project (typically to a
* conf_uart_serial.h file, but it can also be added to your main application file.):
*
* \note The following takes SAM3X configuration for example, other devices have similar
* configuration, but their parameters may be different, refer to corresponding header files.
*
* \code
#define USART_SERIAL &USARTD0
#define USART_SERIAL_BAUDRATE 9600
#define USART_SERIAL_CHAR_LENGTH US_MR_CHRL_8_BIT
#define USART_SERIAL_PARITY US_MR_PAR_NO
#define USART_SERIAL_STOP_BIT false
\endcode
*
* Add to application initialization:
* \code
sysclk_init();
static usart_serial_options_t usart_options = {
.baudrate = USART_SERIAL_BAUDRATE,
.charlength = USART_SERIAL_CHAR_LENGTH,
.paritytype = USART_SERIAL_PARITY,
.stopbits = USART_SERIAL_STOP_BIT
};
usart_serial_init(USART_SERIAL, &usart_options);
\endcode
*
* \subsection serial_use_case_1_setup_flow Workflow
* -# Initialize system clock:
* - \code sysclk_init(); \endcode
* -# Create USART options struct:
* - \code
static usart_serial_options_t usart_options = {
.baudrate = USART_SERIAL_BAUDRATE,
.charlength = USART_SERIAL_CHAR_LENGTH,
.paritytype = USART_SERIAL_PARITY,
.stopbits = USART_SERIAL_STOP_BIT
};
\endcode
* -# Initialize in RS232 mode:
* - \code usart_serial_init(USART_SERIAL_EXAMPLE, &usart_options); \endcode
*
* \section serial_use_case_1_usage Usage steps
*
* \subsection serial_use_case_1_usage_code Example code
* Add to, e.g., main loop in application C-file:
* \code
usart_serial_write_packet(USART_SERIAL, "Test String", strlen("Test String"));
\endcode
*
* \subsection serial_use_case_1_usage_flow Workflow
* -# Write a string of text to the USART:
* - \code usart_serial_write_packet(USART_SERIAL, "Test String", strlen("Test String")); \endcode
*/
#endif /* SERIAL_H_INCLUDED */
|
