le_tty.h

Go to the documentation of this file.
1 /**
2  * @page c_tty tty API
3  *
4  * @ref le_tty.h "API Reference"
5  *
6  * <HR>
7  *
8  * This API provides routines to configure serial ports.
9  *
10  * @section c_tty_open_close Open/Close serial ports
11  *
12  * - @c le_tty_Open() opens a serial port device and locks it for exclusive use.
13  *
14  * @code
15  * fd = le_tty_Open("/dev/ttyS0", O_RDWR | O_NOCTTY | O_NDELAY);
16  * @endcode
17  *
18  * - @c le_tty_Close() closes and unlocks a serial port file descriptor.
19  *
20  *
21  * @section c_tty_settings Settings serial ports
22  *
23  * - Setting baud rate is done with @c le_tty_SetBaudRate(), value available are listed
24  * by #tty_Speed_t
25  *
26  * - Getting baud rate is done with @c le_tty_GetBaudRate(). when le_tty_SetBaudRate()
27  * failed with LE_UNSUPPORTED, use @c le_tty_GetBaudRate() to retrieve the real
28  * value sets by the driver.
29  *
30  * - Setting framing on serial port is done with @c le_tty_SetFraming().
31  * Parity value can be :
32  * - "N" for No parity
33  * - "O" for Odd parity
34  * - "E" for Even parity
35  *
36  * - Setting flow control on serial port is done with @c le_tty_SetFlowControl().
37  * Flow control options are:
38  * - LE_TTY_FLOW_CONTROL_NONE - flow control disabled
39  * - LE_TTY_FLOW_CONTROL_XON_XOFF - software flow control (XON/XOFF)
40  * - LE_TTY_FLOW_CONTROL_HARDWARE - hardware flow control (RTS/CTS)
41  *
42  * - Setting serial port into terminal mode is done with @c le_tty_SetCanonical().
43  * it converts EOL characters to unix format, enables local echo, line mode.
44  *
45  * - Setting serial port into raw (non-canonical) mode is done with @c le_tty_SetRaw().
46  * it disables conversion of EOL characters, disables local echo, sets character mode,
47  * read timeouts.
48  *
49  * Different use cases for numChars and timeout parameters in @c
50  * le_tty_SetRaw(int fd,int numChars,int timeout)
51  * - numChars = 0 and timeout = 0: Read will be completetly non-blocking.
52  * - numChars = 0 and timeout > 0: Read will be a pure timed read. If the timer expires without
53  * data, zero is returned.
54  * - numChars > 0 and timeout > 0: Read will return when numChar have been transferred to the
55  * caller's buffer or when timeout expire between characters.
56  * - numChars > 0 and timeout = 0: Read will return only when exactly numChars have been
57  * transferred to the caller's buffer. This can wait and block indefinitely, when
58  * read(fd,buffer,nbytes) is performed and that nbytes is smaller than the numChars setted.
59  *
60  * To switch between 'cannonical' and 'raw' mode, just call @c le_tty_SetCanonical() and
61  * @c le_tty_SetRaw() respectively
62  *
63  * <HR>
64  *
65  * Copyright (C) Sierra Wireless Inc.
66  */
67 
68 //--------------------------------------------------------------------------------------------------
69 /**
70  * @file le_tty.h
71  *
72  * Legato @ref c_tty include file
73  *
74  * Copyright (C) Sierra Wireless Inc.
75  */
76 //--------------------------------------------------------------------------------------------------
77 
78 #ifndef LEGATO_TTY_H_INCLUDE_GUARD
79 #define LEGATO_TTY_H_INCLUDE_GUARD
80 
81 typedef enum
82 {
83  LE_TTY_FLOW_CONTROL_NONE = 0,
84  LE_TTY_FLOW_CONTROL_XON_XOFF = 1,
85  LE_TTY_FLOW_CONTROL_HARDWARE = 2
86 }
87 tty_FlowControl_t;
88 
89 //--------------------------------------------------------------------------------------------------
90 /*
91  * Use Bxxxxxx constants from termbits.h to indicate baud rate.
92  */
93 //--------------------------------------------------------------------------------------------------
94 typedef enum
95 {
96  LE_TTY_SPEED_0 = 0,
97  LE_TTY_SPEED_50,
98  LE_TTY_SPEED_75,
99  LE_TTY_SPEED_110,
100  LE_TTY_SPEED_134,
101  LE_TTY_SPEED_150,
102  LE_TTY_SPEED_200,
103  LE_TTY_SPEED_300,
104  LE_TTY_SPEED_600,
105  LE_TTY_SPEED_1200,
106  LE_TTY_SPEED_1800,
107  LE_TTY_SPEED_2400,
108  LE_TTY_SPEED_4800,
109  LE_TTY_SPEED_9600,
110  LE_TTY_SPEED_19200,
111  LE_TTY_SPEED_38400,
112  LE_TTY_SPEED_57600,
113  LE_TTY_SPEED_115200,
114  LE_TTY_SPEED_230400,
115  LE_TTY_SPEED_460800,
116  LE_TTY_SPEED_500000,
117  LE_TTY_SPEED_576000,
118  LE_TTY_SPEED_921600,
119  LE_TTY_SPEED_1000000,
120  LE_TTY_SPEED_1152000,
121  LE_TTY_SPEED_1500000,
122  LE_TTY_SPEED_2000000,
123  LE_TTY_SPEED_2500000,
124  LE_TTY_SPEED_3000000,
125  LE_TTY_SPEED_3500000,
126  LE_TTY_SPEED_4000000
127 }
128 tty_Speed_t;
129 
130 //--------------------------------------------------------------------------------------------------
131 /**
132  * Open a serial port device and locks it for exclusive use.
133  *
134  * @return
135  * - Serial port file descriptor number on success.
136  * - -1 on failure.
137  */
138 //--------------------------------------------------------------------------------------------------
139 int le_tty_Open
140 (
141  const char *ttyDev, ///< [IN] Path name
142  int flags ///< [IN] flags used in open(2)
143 );
144 
145 //--------------------------------------------------------------------------------------------------
146 /**
147  * Close and unlock a serial port file descriptor.
148  */
149 //--------------------------------------------------------------------------------------------------
150 void le_tty_Close
151 (
152  int fd ///< [IN] File descriptor
153 );
154 
155 //--------------------------------------------------------------------------------------------------
156 /**
157  * Set baud rate of serial port.
158  *
159 * @return
160  * - LE_OK if successful
161  * - LE_UNSUPPORTED if value cannot be set
162  * - LE_NOT_FOUND if value is not supported
163  * - LE_FAULT for any other error
164  */
165 //--------------------------------------------------------------------------------------------------
167 (
168  int fd, ///< [IN] File Descriptor
169  tty_Speed_t ttyRate ///< [IN] Baud rate
170 );
171 
172 //--------------------------------------------------------------------------------------------------
173 /**
174  * Get baud rate of serial port.
175  *
176  * @return
177  * - LE_OK if successful
178  = - LE_NOT_FOUND if speed is not supported by legato
179  * - LE_FAULT for any other error
180  */
181 //--------------------------------------------------------------------------------------------------
183 (
184  int fd, ///< [IN] File Descriptor
185  tty_Speed_t *ttyInRatePtr, ///< [OUT] input baud rate
186  tty_Speed_t *ttyOutRatePtr ///< [OUT] output baud rate
187 );
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  * Set framing on serial port. Use human-readable characters/numbers such as 'N', 8, 1 to indicate
192  * parity, word size and stop bit settings.
193  *
194  * @return
195  * - LE_OK if successful
196  * - LE_UNSUPPORTED if value cannot be set
197  * - LE_NOT_FOUND if value is not supported
198  * - LE_FAULT for any other error
199  */
200 //--------------------------------------------------------------------------------------------------
202 (
203  int fd, ///< [IN] File Descriptor
204  char parity, ///< [IN] Parity ('N','O','E')
205  int wordSize, ///< [IN] Data bits (5,6,7,8)
206  int stopBits ///< [IN] Stop bits (1,2)
207 );
208 
209 //--------------------------------------------------------------------------------------------------
210 /**
211  * Set flow control option on serial port. Flow control options are:
212  * LE_TTY_FLOW_CONTROL_NONE - flow control disabled
213  * LE_TTY_FLOW_CONTROL_XON_XOFF - software flow control (XON/XOFF)
214  * LE_TTY_FLOW_CONTROL_HARDWARE - hardware flow control (RTS/CTS)
215  *
216  * @return
217  * - LE_OK if successful
218  * - LE_UNSUPPORTED if value cannot be set
219  * - LE_NOT_FOUND if value is not supported
220  * - LE_FAULT for any other error
221  */
222 //--------------------------------------------------------------------------------------------------
224 (
225  int fd, ///< [IN] File decriptor
226  tty_FlowControl_t ttyFlowControl ///< [IN] Flow control option
227 );
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  * Set serial port into terminal mode. Converts EOL characters to unix format, enables local echo,
232  * line mode, etc.
233  *
234  * @return
235  * - LE_OK if successful
236  * - LE_UNSUPPORTED if canonical mode cannot be set
237  * - LE_FAULT for any other error
238  */
239 //--------------------------------------------------------------------------------------------------
241 (
242  int fd ///< [iIN] File Descriptor
243 );
244 
245 //--------------------------------------------------------------------------------------------------
246 /**
247  * Set serial port into raw (non-canonical) mode. Disables conversion of EOL characters, disables
248  * local echo, sets character mode, read timeouts, etc.
249  *
250  * @return
251  * - LE_OK if successful
252  * - LE_UNSUPPORTED if raw mode cannot be set
253  * - LE_FAULT for any other error
254  */
255 //--------------------------------------------------------------------------------------------------
257 (
258  int fd, ///< [IN] File Descriptor
259  int numChars, ///< [IN] Number of bytes returned by read(2) when a read is performed.
260  int timeout ///< [IN] when a read(2) is performed return after that timeout.
261  ///< The timeout value is given with 1 decimal places.
262 );
263 
264 #endif // LEGATO_TTY_H_INCLUDE_GUARD
int le_tty_Open(const char *ttyDev, int flags)
void le_tty_Close(int fd)
le_result_t
Definition: le_basics.h:35
le_result_t le_tty_SetFlowControl(int fd, tty_FlowControl_t ttyFlowControl)
le_result_t le_tty_SetRaw(int fd, int numChars, int timeout)
le_result_t le_tty_SetFraming(int fd, char parity, int wordSize, int stopBits)
le_result_t le_tty_SetCanonical(int fd)
le_result_t le_tty_SetBaudRate(int fd, tty_Speed_t ttyRate)
le_result_t le_tty_GetBaudRate(int fd, tty_Speed_t *ttyInRatePtr, tty_Speed_t *ttyOutRatePtr)