com.h
Go to the documentation of this file.
1 #ifndef _COM_H
2 #define _COM_H
3
4 #include <stdint.h>
5 #include <stddef.h>
6 #include "check.h"
7
8 /**
9 * \addtogroup COM Serial Communication
10 *
11 * \brief Serial communication with SPiCboards
12 *
13 * \image html spicboard3_com_small.jpg
14 * The SPiCboard3 can perform serial communication using the three PINs
15 * on its upper right corner (\c TX at \c PD1, \c GND and \c RX at \c PD0 ).
16 * To establish a connection you have to connect its \c RX with \c TX of
17 * another board, both \c GND pins and \c TX with \c RX, like shown on the image
18 * above.
19 *
20 * For the transmission this library uses the transmission setting \c 8-E-1,
21 * in which we send (in addition to the start bit) 8 data bits,
22 * one even parity bit and one stop bit.
23 *
24 * Example: Transmission of the (decimal) value \c 23
25 * \image html com.png
26 * - \c PD0 is configured as input (\c RX)
27 * - \c PD1 is configured as output (\c TX)
28 * - The idle voltage is 5V, a logical high (this is a historic legacy from
29 * telegraphy, in which the line is held high to show that the line and
30 * transmitter are not damaged).
31 * - the transmission begins with the start bit, which changes the level from
32 * logical high (idle) to logical low.
33 * - the time interval \c T for transmitting one symbol is defined by the
34 * \c BAUD_RATE : \f$ T = \frac{1s}{BAUD\_RATE} \f$
35 * - the payload byte is sent bitwise, starting with the least significant bit
36 * - the parity bit ensures that an even number of logical highs has been sent
37 * (including parity - calculated using \c XOR ) - it can be used to detect
38 * transmission errors.
39 * - the stopbit finishes the transmission and leaves the line in a logical high
40 *
41 * \note The libspicboard implementation uses the 16bit <b>timer 4</b>.
42 *
43 * \note For educational purposes the transmission is implemented completely
44 * in software - for more advanced serial communcation you can use
45 * <a href="https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter">USART</a>,
46 * described in Section 25 of the <a href="Atmel-42397-8-bit-AVR-Microcontroller-ATmega328PB_Datasheet.pdf">ATMega328PB Datasheet</a>.
47 *
48 * \sa COM_EXT
49 *
50 * @{
51 * \file com.h
52 * \version \$Rev: 15477 $
53 */
54
55 #ifndef BAUD_RATE
56 /**
57 * \def BAUD_RATE
58 *
59 * Default baud rate (symbols per second) is 1200
60 */
61 #define BAUD_RATE 1200UL
62 #endif
63
64 #if defined(__BUILTIN_AVR_DELAY_CYCLES)
65 /**
66 * \def sb_com_wait(FACTOR)
67 *
68 * Active wait loop for the transmission interval time \c T (determined by the baud rate) multiplied by \a FACTOR
69 */
70 #define sb_com_wait(FACTOR) __builtin_avr_delay_cycles((F_CPU*FACTOR)/BAUD_RATE)
71 #else
72 #error Compiler does not support __builtin_avr_delay_cycles, which is required for sb_com_wait()
73 #endif
74
75 // Error
76 /**
77 * \brief Error states used in mask
78 */
79 typedef enum {
80 ERROR_NO_STOP_BIT = 1, /**< no stop bit received */
81 ERROR_PARITY = 2, /**< parity bit wrong */
82 ERROR_BUFFER_FULL = 4, /**< receive buffer full */
83 ERROR_INVALID_POINTER = 8, /**< data pointer invalid */
84 } __attribute__ ((__packed__)) COM_ERROR_STATUS;
85
86 CHECK_ENUM_SIZE(COM_ERROR_STATUS, 1)
87 /**
88 * \brief Send a single byte (8-bit) plus one start-, parity and stop bit
89 *
90 * \note Shall not be called inside a ISR!
91 *
92 * \param data the byte to send
93 */
94 void sb_com_sendByte(uint8_t data);
95
96 /**
97 * \brief Receive one byte with start, parity and stop bit each
98 *
99 * We try to sample in the middle of each symbol, therefore we have to wait
100 * about \f$ 1.5T \f$ after receiving the start bit before reading the first
101 * data bit. Every subsequent symbol is sampled after a \f$ T \f$ delay.
102 *
103 * \image html com_recv.png
104 *
105 * Transmission errors are recorded and returned. They should not be ignored,
106 * because they usually indicate invalid data - there is no resend mechanism
107 * implemented in this library!
108 *
109 * \param data pointer to allocated space for the received byte
110 *
111 * \retval 0 no error
112 * \retval >0 bit mask describing the error:
113 * - 1. bit: no stop bit received (\c ERROR_NO_STOP_BIT )
114 * - 2. bit: parity bit wrong (\c ERROR_PARITY )
115 * - 3. bit: receive buffer full (\c ERROR_BUFFER_FULL )
116 * - 4. bit: data pointer invalid (\c ERROR_INVALID_POINTER )
117 */
118 uint8_t sb_com_receiveByte(uint8_t *data);
119
120
121 /** @}*/
122
123 #endif
ERROR_INVALID_POINTER
Definition: com.h:83
CHECK_ENUM_SIZE
#define CHECK_ENUM_SIZE(VAR, LEN)
Definition: check.h:73
check.h
sb_com_receiveByte
uint8_t sb_com_receiveByte(uint8_t *data)
Receive one byte with start, parity and stop bit each.
sb_com_sendByte
void sb_com_sendByte(uint8_t data)
Send a single byte (8-bit) plus one start-, parity and stop bit.
ERROR_PARITY
Definition: com.h:81
ERROR_NO_STOP_BIT
Definition: com.h:80
ERROR_BUFFER_FULL
Definition: com.h:82
COM_ERROR_STATUS
COM_ERROR_STATUS
Error states used in mask.
Definition: com.h:79