Robot Control Library
uart.h
Go to the documentation of this file.
1 /**
2  * <rc/uart.h>
3  *
4  * @brief C interface for the Linux UART driver
5  *
6  * This is a general-purpose C interface to the linux UART driver device
7  * (/dev/ttyO*). This is developed and tested on the BeagleBone platform but
8  * should work on other linux systems too.
9  *
10  * @author James Strawson
11  * @date 3/6/2018
12  *
13  * @addtogroup UART
14  * @ingroup IO
15  * @{
16  */
17 
18 #ifndef RC_UART_H
19 #define RC_UART_H
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 #include <stdint.h>
26 
27 /**
28  * @brief Initializes a UART bus /dev/ttyO{bus} at specified baudrate and
29  * timeout.
30  *
31  * This is a very generalized function that configures the bus for 8-bit
32  * characters and ignores the modem status lines.
33  *
34  * If you need a configuration other than whats presented here then you are
35  * probably doing something fancy with the bus and you will probably want to do
36  * your own reading/writing with standard linux methods.
37  *
38  * @param[in] bus The bus number /dev/ttyO{bus}
39  * @param[in] baudrate must be one of the standard speeds in the UART
40  * spec. 115200 and 57600 are most common.
41  * @param[in] timeout timeout is in seconds and must be >=0.1
42  * @param[in] canonical_en 0 for non-canonical mode (raw data), non-zero for
43  * canonical mode where only one line ending in '\n' is read at a time.
44  * @param[in] stop_bits number of stop bits, 1 or 2, usually 1 for most
45  * sensors
46  * @param[in] parity_en 0 to disable parity, nonzero to enable. usually
47  * disabled for most sensors.
48  *
49  * @return 0 on success, -1 on failure
50  */
51 int rc_uart_init(int bus, int baudrate, float timeout, int canonical_en, int stop_bits, int parity_en);
52 
53 
54 /**
55  * @brief closes a UART bus
56  *
57  * @param[in] bus The bus number /dev/ttyO{bus}
58  *
59  * @return returns 0 on success, -1 on error.
60  */
61 int rc_uart_close(int bus);
62 
63 /**
64  * @brief Fetches the file descriptor to a uart bus after the bus has been
65  * initialized.
66  *
67  * This is so the user can optionally do additional configuration or IO
68  * operations on the bus.
69  *
70  * @param[in] bus The bus number /dev/ttyO{bus}
71  *
72  * @return the file descriptor to /dev/ttyO{bus} or -1 on error
73  */
74 int rc_uart_get_fd(int bus);
75 
76 /**
77  * @brief flushes (discards) any data received but not read, or data
78  * written but not sent.
79  *
80  * @param[in] bus The bus number /dev/ttyO{bus}
81  *
82  * @return 0 on success or -1 on failure
83  */
84 int rc_uart_flush(int bus);
85 
86 /**
87  * @brief Sends data out the uart port
88  *
89  * @param[in] bus The bus number /dev/ttyO{bus}
90  * @param[in] data data pointer
91  * @param[in] bytes number of bytes to send
92  *
93  * @return returns number of bytes sent or -1 on error
94  */
95 int rc_uart_write(int bus, uint8_t* data, size_t bytes);
96 
97 /**
98  * @brief reads bytes from the UART bus
99  *
100  * This is a blocking function call. It will only return once the desired number
101  * of bytes has been read from the buffer or the shutdown flag is set. due to
102  * the Sitara's UART FIFO buffer, MAX_READ_LEN (128bytes) is the largest packet
103  * that can be read with a single call to read(). For reads larger than
104  * 128bytes, we run a loop instead.
105  *
106  * @param[in] bus The bus number /dev/ttyO{bus}
107  * @param[out] buf data pointer
108  * @param[in] bytes number of bytes to read
109  *
110  * @return Returns number of bytes actually read or -1 on error.
111  */
112 int rc_uart_read_bytes(int bus, uint8_t* buf, size_t bytes);
113 
114 /**
115  * @brief reads a line of characters ending in newline '\n'
116  *
117  * This is a blocking function call. It will only return on these conditions:
118  *
119  * - a newline character was read, this is discarded.
120  * - max_bytes were read, this prevents overflowing a user buffer.
121  * - timeout declared in rc_uart_init() is reached
122  * - shutdown flag is set by rc_uart_close
123  *
124  * @param[in] bus The bus number /dev/ttyO{bus}
125  * @param[out] buf data pointer
126  * @param[in] max_bytes max bytes to read in case newline character not found
127  *
128  * @return Returns number of bytes actually read or -1 on error.
129  */
130 int rc_uart_read_line(int bus, uint8_t* buf, size_t max_bytes);
131 
132 /**
133  * @brief Fetches the number of bytes ready to be read from a bus
134  *
135  * @param[in] bus The bus
136  *
137  * @return Returns number of bytes ready to be read or -1 on error.
138  */
139 int rc_uart_bytes_available(int bus);
140 
141 
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 #endif // RC_UART_H
147 
148 ///@} end group IO
rc_uart_read_line
int rc_uart_read_line(int bus, uint8_t *buf, size_t max_bytes)
reads a line of characters ending in newline &#39; &#39;
rc_uart_read_bytes
int rc_uart_read_bytes(int bus, uint8_t *buf, size_t bytes)
reads bytes from the UART bus
rc_uart_write
int rc_uart_write(int bus, uint8_t *data, size_t bytes)
Sends data out the uart port.
rc_uart_get_fd
int rc_uart_get_fd(int bus)
Fetches the file descriptor to a uart bus after the bus has been initialized.
rc_uart_init
int rc_uart_init(int bus, int baudrate, float timeout, int canonical_en, int stop_bits, int parity_en)
Initializes a UART bus /dev/ttyO{bus} at specified baudrate and timeout.
rc_uart_flush
int rc_uart_flush(int bus)
flushes (discards) any data received but not read, or data written but not sent.
rc_uart_close
int rc_uart_close(int bus)
closes a UART bus
rc_uart_bytes_available
int rc_uart_bytes_available(int bus)
Fetches the number of bytes ready to be read from a bus.