libspicboard-Doku

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 */
79typedef 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
86CHECK_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 */
94void 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 */
118uint8_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