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
check.h
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.