libspicboard-doc

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
COM_ERROR_STATUS
COM_ERROR_STATUS
Error states used in mask.
Definition: com.h:79
sb_com_sendByte
void sb_com_sendByte(uint8_t data)
Send a single byte (8-bit) plus one start-, parity and stop bit.
sb_com_receiveByte
uint8_t sb_com_receiveByte(uint8_t *data)
Receive one byte with start, parity and stop bit each.
ERROR_PARITY
@ ERROR_PARITY
Definition: com.h:81
ERROR_BUFFER_FULL
@ ERROR_BUFFER_FULL
Definition: com.h:82
ERROR_INVALID_POINTER
@ ERROR_INVALID_POINTER
Definition: com.h:83
ERROR_NO_STOP_BIT
@ ERROR_NO_STOP_BIT
Definition: com.h:80
CHECK_ENUM_SIZE
#define CHECK_ENUM_SIZE(VAR, LEN)
Definition: check.h:71