SPiCboard

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 */
40typedef 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 */
61int8_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 */
77int8_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 */
86char 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 */
100char * 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 */
109int8_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 */
119int8_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 */
128int8_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