Friedrich-Alexander-Universität Erlangen-Nürnberg  /   Technische Fakultät  /   Department Informatik

 

console.h
Go to the documentation of this file.
1 #ifndef _CONSOLE_H
2 #define _CONSOLE_H
3 
4 #include <stdarg.h>
5 
6 #include "check.h"
7 
8 /**
9  * \addtogroup Console serial console
10  *
11  * \brief In- and output using a serial console
12  *
13  * This adds the ability to print and read from a connected serial console (via USB).
14  * You can use the primitives supplied by this module or even printf and scanf.
15  *
16  * In Atmel Studio 7 select Menu "Tools" and choose "Data Visualizer".
17  * Click on sidebar "Configuration"
18  * In frame "Modules" expand "External Connection" and select "Serial Port"
19  * Configure "Serial Port Control Panel":
20  * - choose the correct interface (something like "mEDBG Virtual COM Port (COM4)"
21  * - set the "Baud rate" to the same value as the "BAUD_RATE" macro (by default 38400)
22  * - choose correct "Parity" (default "disabled") and "Stop bits" (default "1")
23  * - check "DTR" and "Open Terminal" (and "RTS" on slow systems)
24  * Click "Connect"
25  *
26  * In Linux you can try to connect to the console using the libspicboard make target "console":
27  *
28  * \warning Cannot be used in conjunction with any other serial communication (including \ref COM )
29  *
30  * \warning Using printf/scanf (and derived functions) will consume a noticeable amount of flash memory!
31  *
32  * @{
33  * \file console.h
34  * \version \$Rev: 16347 $
35  */
36 
37 /**
38  * \brief Parity bit types
39  */
40 typedef enum {
41  PARITY_DISABLED, /**< parity bit disabled */
42  PARITY_EVEN, /**< use even parity bit */
43  PARITY_ODD /**< use odd parity bit */
44 } __attribute__ ((__packed__)) CONSOLE_PARITY;
45 
46 /**
47  * \brief Connect to serial console
48  *
49  * Specify the baud rate, parity type and number of stop bits and initiate a
50  * connection using the serial port (USART)
51  *
52  * \param baud baud rate for serial connection
53  * \param parity pairty type (even/odd) if enabled
54  * \param stopbits number of stop bits (1 or 2)
55  * \retval 0 connection successfully set up
56  * \retval -1 Baud rate achieved is higher than allowed
57  * \retval -2 Baud rate achieved is lower than allowed
58  * \retval -3 Baud rate value overflow
59  * \retval -4; invalid stop bit count
60  */
61 int8_t sb_console_connect(uint32_t baud, CONSOLE_PARITY parity, uint8_t stopbits);
62 
63 /**
64  * \brief Connect to serial console with default settings
65  *
66  * Connect with 38400 baud, no parity and single stop bit to a serial console.
67  *
68  * This is automatically used for the sb_console_* functions
69  * if sb_console_connect was not called before.
70  *
71  * \param baud baud rate for serial connection
72  * \param parity pairty type (even/odd) if enabled
73  * \param stopbits number of stop bits (1 or 2)
74  * \retval 0 connection successfully set up
75  * \retval -1 Baud rate achieved is higher than allowed
76  * \retval -2 Baud rate achieved is lower than allowed
77  * \retval -3 Baud rate value overflow
78  * \retval -4; invalid stop bit count
79  */
80 int8_t sb_console_connect_default(void);
81 
82 /**
83  * \brief Read the next character
84  *
85  * Invalid read operations (end of file) will return '\0'
86  *
87  * \retval character read from console
88  */
89 char sb_console_getChar();
90 
91 /**
92  * \brief Read a line into the buffer
93  *
94  * This function reads in at most one less than size characters and stores them into the buffer pointed to by the char array.
95  * Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer.
96  * A terminating null byte (\0) is stored after the last character in the buffer.
97  *
98  * \param string pointer to buffer
99  * \param size size of buffer
100  * \retval string on success
101  * \retval NULL on error or when end of file occurs while no characters have been read
102  */
103 char * sb_console_getString(char *string, uint16_t size);
104 
105 /**
106  * \brief Prints a single character
107  *
108  * \param character character to print
109  * \retval -1 on error
110  * \retval 0 on success
111  */
112 int8_t sb_console_putChar(char character);
113 
114 
115 /**
116  * \brief Writes the string and a trailing newline.
117  *
118  * \param string string to print
119  * \retval -1 on error
120  * \retval 0 on success
121  */
122 int8_t sb_console_putString(const char *string);
123 
124 /**
125  * \brief Writes the string and a trailing newline.
126  *
127  * \param string string from flash memory to print
128  * \retval -1 on error
129  * \retval 0 on success
130  */
131 int8_t sb_console_putStringFromFlash(const __flash char *string);
132 
133 /** @}*/
134 
135 #endif
136 
PARITY_DISABLED
Definition: console.h:41
sb_console_getString
char * sb_console_getString(char *string, uint16_t size)
Read a line into the buffer.
CONSOLE_PARITY
CONSOLE_PARITY
Parity bit types.
Definition: console.h:40
PARITY_ODD
Definition: console.h:43
sb_console_putString
int8_t sb_console_putString(const char *string)
Writes the string and a trailing newline.
sb_console_connect
int8_t sb_console_connect(uint32_t baud, CONSOLE_PARITY parity, uint8_t stopbits)
Connect to serial console.
PARITY_EVEN
Definition: console.h:42
sb_console_connect_default
int8_t sb_console_connect_default(void)
Connect to serial console with default settings.
sb_console_putStringFromFlash
int8_t sb_console_putStringFromFlash(const __flash char *string)
Writes the string and a trailing newline.
sb_console_putChar
int8_t sb_console_putChar(char character)
Prints a single character.
sb_console_getChar
char sb_console_getChar()
Read the next character.