libspicboard-doc

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  * \retval 0 connection successfully set up
72  * \retval -1 Baud rate achieved is higher than allowed
73  * \retval -2 Baud rate achieved is lower than allowed
74  * \retval -3 Baud rate value overflow
75  * \retval -4; invalid stop bit count
76  */
77 int8_t sb_console_connect_default(void);
78 
79 /**
80  * \brief Read the next character
81  *
82  * Invalid read operations (end of file) will return '\0'
83  *
84  * \retval character read from console
85  */
86 char sb_console_getChar();
87 
88 /**
89  * \brief Read a line into the buffer
90  *
91  * This function reads in at most one less than size characters and stores them into the buffer pointed to by the char array.
92  * Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer.
93  * A terminating null byte (\0) is stored after the last character in the buffer.
94  *
95  * \param string pointer to buffer
96  * \param size size of buffer
97  * \retval string on success
98  * \retval NULL on error or when end of file occurs while no characters have been read
99  */
100 char * sb_console_getString(char *string, uint16_t size);
101 
102 /**
103  * \brief Prints a single character
104  *
105  * \param character character to print
106  * \retval -1 on error
107  * \retval 0 on success
108  */
109 int8_t sb_console_putChar(char character);
110 
111 
112 /**
113  * \brief Writes the string and a trailing newline.
114  *
115  * \param string string to print
116  * \retval -1 on error
117  * \retval 0 on success
118  */
119 int8_t sb_console_putString(const char *string);
120 
121 /**
122  * \brief Writes the string and a trailing newline.
123  *
124  * \param string string from flash memory to print
125  * \retval -1 on error
126  * \retval 0 on success
127  */
128 int8_t sb_console_putStringFromFlash(const __flash char *string);
129 
130 /** @}*/
131 
132 #endif
133 
sb_console_getChar
char sb_console_getChar()
Read the next character.
sb_console_putStringFromFlash
int8_t sb_console_putStringFromFlash(const __flash 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.
sb_console_putChar
int8_t sb_console_putChar(char character)
Prints a single character.
sb_console_putString
int8_t sb_console_putString(const char *string)
Writes the string and a trailing newline.
sb_console_connect_default
int8_t sb_console_connect_default(void)
Connect to serial console with default settings.
CONSOLE_PARITY
CONSOLE_PARITY
Parity bit types.
Definition: console.h:40
sb_console_getString
char * sb_console_getString(char *string, uint16_t size)
Read a line into the buffer.
PARITY_ODD
@ PARITY_ODD
Definition: console.h:43
PARITY_EVEN
@ PARITY_EVEN
Definition: console.h:42
PARITY_DISABLED
@ PARITY_DISABLED
Definition: console.h:41