1 /*
2  * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
3  * Contributions: Jon Trulson <jtrulson@ics.com>
4  *                Brendan Le Foll <brendan.le.foll@intel.com>
5  * Copyright (c) 2014 - 2015 Intel Corporation
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining
8  * a copy of this software and associated documentation files (the
9  * "Software"), to deal in the Software without restriction, including
10  * without limitation the rights to use, copy, modify, merge, publish,
11  * distribute, sublicense, and/or sell copies of the Software, and to
12  * permit persons to whom the Software is furnished to do so, subject to
13  * the following conditions:
14  *
15  * The above copyright notice and this permission notice shall be
16  * included in all copies or substantial portions of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
22  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
23  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25  */
26 
27 #pragma once
28 
29 /**
30  * @file
31  * @brief UART module
32  *
33  * UART is the Universal asynchronous receiver/transmitter interface to
34  * libmraa. It allows the exposure of UART pins on supported boards.
35  * With functionality to expand at a later date.
36  *
37  * @snippet uart.c Interesting
38  */
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 #include <stdio.h>
45 
46 #include "common.h"
47 
48 typedef struct _uart* mraa_uart_context;
49 
50 /**
51  * Initialise uart_context, uses board mapping
52  *
53  * @param uart the index of the uart set to use
54  * @return uart context or NULL
55  */
56 mraa_uart_context mraa_uart_init(int uart);
57 
58 /**
59  * Initialise a raw uart_context. No board setup.
60  *
61  * @param path for example "/dev/ttyS0"
62  * @return uart context or NULL
63  */
64 mraa_uart_context mraa_uart_init_raw(const char* path);
65 
66 /**
67  * Flush the outbound data.
68  * Blocks until complete.
69  *
70  * @param dev The UART context
71  * @return Result of operation
72  */
73 mraa_result_t mraa_uart_flush(mraa_uart_context dev);
74 
75 /**
76  * Set the baudrate.
77  * Takes an int and will attempt to decide what baudrate  is
78  * to be used on the UART hardware.
79  *
80  * @param dev The UART context
81  * @param baud unsigned int of baudrate i.e. 9600
82  * @return Result of operation
83  */
84 mraa_result_t mraa_uart_set_baudrate(mraa_uart_context dev, unsigned int baud);
85 
86 /**
87  * Set the transfer mode
88  * For example setting the mode to 8N1 would be
89  * "mraa_uart_set_mode(dev, 8,MRAA_UART_PARITY_NONE , 1)"
90  *
91  * @param dev The UART context
92  * @param bytesize data bits
93  * @param parity Parity bit setting
94  * @param stopbits stop bits
95  * @return Result of operation
96  */
97 mraa_result_t mraa_uart_set_mode(mraa_uart_context dev, int bytesize, mraa_uart_parity_t parity, int stopbits);
98 
99 /**
100  * Set the flowcontrol
101  *
102  * @param dev The UART context
103  * @param xonxoff XON/XOFF Software flow control.
104  * @param rtscts RTS/CTS out of band hardware flow control
105  * @return Result of operation
106  */
107 mraa_result_t mraa_uart_set_flowcontrol(mraa_uart_context dev, mraa_boolean_t xonxoff, mraa_boolean_t rtscts);
108 
109 /**
110  * Set the timeout for read and write operations
111  * <= 0 will disable that timeout
112  *
113  * @param dev The UART context
114  * @param read read timeout
115  * @param write write timeout
116  * @param interchar inbetween char timeout
117  * @return Result of operation
118  */
119 mraa_result_t mraa_uart_set_timeout(mraa_uart_context dev, int read, int write, int interchar);
120 
121 /**
122  * Get Char pointer with tty device path within Linux
123  * For example. Could point to "/dev/ttyS0"
124  *
125  * @param dev uart context
126  * @return char pointer of device path
127  */
128 const char* mraa_uart_get_dev_path(mraa_uart_context dev);
129 
130 /**
131  * Destroy a mraa_uart_context
132  *
133  * @param dev uart context
134  * @return mraa_result_t
135  */
136 mraa_result_t mraa_uart_stop(mraa_uart_context dev);
137 
138 /**
139  * Read bytes from the device into a buffer
140  *
141  * @param dev uart context
142  * @param buf buffer pointer
143  * @param length maximum size of buffer
144  * @return the number of bytes read, or -1 if an error occurred
145  */
146 int mraa_uart_read(mraa_uart_context dev, char* buf, size_t length);
147 
148 /**
149  * Write bytes in buffer to a device
150  *
151  * @param dev uart context
152  * @param buf buffer pointer
153  * @param length maximum size of buffer
154  * @return the number of bytes written, or -1 if an error occurred
155  */
156 int mraa_uart_write(mraa_uart_context dev, const char* buf, size_t length);
157 
158 /**
159  * Check to see if data is available on the device for reading
160  *
161  * @param dev uart context
162  * @param millis number of milliseconds to wait, or 0 to return immediately
163  * @return 1 if there is data available to read, 0 otherwise
164  */
165 mraa_boolean_t mraa_uart_data_available(mraa_uart_context dev, unsigned int millis);
166 
167 #ifdef __cplusplus
168 }
169 #endif
170