le_tty.h

Go to the documentation of this file.
1 /**
2  * @page c_tty tty API
3  *
4  * @subpage 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 lock it for exclusive use.
133  *
134  * @return
135  * - Serial port file descriptor number on success.
136  * - -1 on failure.
137  *
138  * @note
139  * Previous versions of le_tty_Open() would exit the process with LE_FATAL if the tty failed
140  * to successfully open; now either a file descriptor is returned or -1 on failure.
141  *
142  */
143 //--------------------------------------------------------------------------------------------------
144 int le_tty_Open
145 (
146  const char *ttyDev, ///< [IN] Path name
147  int flags ///< [IN] flags used in open(2)
148 );
149 
150 //--------------------------------------------------------------------------------------------------
151 /**
152  * Close and unlock a serial port file descriptor.
153  */
154 //--------------------------------------------------------------------------------------------------
155 void le_tty_Close
156 (
157  int fd ///< [IN] File descriptor
158 );
159 
160 //--------------------------------------------------------------------------------------------------
161 /**
162  * Set baud rate of serial port.
163  *
164 * @return
165  * - LE_OK if successful
166  * - LE_UNSUPPORTED if value cannot be set
167  * - LE_NOT_FOUND if value is not supported
168  * - LE_FAULT for any other error
169  */
170 //--------------------------------------------------------------------------------------------------
172 (
173  int fd, ///< [IN] File Descriptor
174  tty_Speed_t ttyRate ///< [IN] Baud rate
175 );
176 
177 //--------------------------------------------------------------------------------------------------
178 /**
179  * Get baud rate of serial port.
180  *
181  * @return
182  * - LE_OK if successful
183  = - LE_NOT_FOUND if speed is not supported by legato
184  * - LE_FAULT for any other error
185  */
186 //--------------------------------------------------------------------------------------------------
188 (
189  int fd, ///< [IN] File Descriptor
190  tty_Speed_t *ttyInRatePtr, ///< [OUT] input baud rate
191  tty_Speed_t *ttyOutRatePtr ///< [OUT] output baud rate
192 );
193 
194 //--------------------------------------------------------------------------------------------------
195 /**
196  * Set framing on serial port. Use human-readable characters/numbers such as 'N', 8, 1 to indicate
197  * parity, word size and stop bit settings.
198  *
199  * @return
200  * - LE_OK if successful
201  * - LE_UNSUPPORTED if value cannot be set
202  * - LE_NOT_FOUND if value is not supported
203  * - LE_FAULT for any other error
204  */
205 //--------------------------------------------------------------------------------------------------
207 (
208  int fd, ///< [IN] File Descriptor
209  char parity, ///< [IN] Parity ('N','O','E')
210  int wordSize, ///< [IN] Data bits (5,6,7,8)
211  int stopBits ///< [IN] Stop bits (1,2)
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Set flow control option on serial port. Flow control options are:
217  * LE_TTY_FLOW_CONTROL_NONE - flow control disabled
218  * LE_TTY_FLOW_CONTROL_XON_XOFF - software flow control (XON/XOFF)
219  * LE_TTY_FLOW_CONTROL_HARDWARE - hardware flow control (RTS/CTS)
220  *
221  * @return
222  * - LE_OK if successful
223  * - LE_UNSUPPORTED if value cannot be set
224  * - LE_NOT_FOUND if value is not supported
225  * - LE_FAULT for any other error
226  */
227 //--------------------------------------------------------------------------------------------------
229 (
230  int fd, ///< [IN] File decriptor
231  tty_FlowControl_t ttyFlowControl ///< [IN] Flow control option
232 );
233 
234 //--------------------------------------------------------------------------------------------------
235 /**
236  * Set serial port into terminal mode. Converts EOL characters to unix format, enables local echo,
237  * line mode, etc.
238  *
239  * @return
240  * - LE_OK if successful
241  * - LE_UNSUPPORTED if canonical mode cannot be set
242  * - LE_FAULT for any other error
243  */
244 //--------------------------------------------------------------------------------------------------
246 (
247  int fd ///< [iIN] File Descriptor
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  * Set serial port into raw (non-canonical) mode. Disables conversion of EOL characters, disables
253  * local echo, sets character mode, read timeouts, etc.
254  *
255  * @return
256  * - LE_OK if successful
257  * - LE_UNSUPPORTED if raw mode cannot be set
258  * - LE_FAULT for any other error
259  */
260 //--------------------------------------------------------------------------------------------------
262 (
263  int fd, ///< [IN] File Descriptor
264  int numChars, ///< [IN] Number of bytes returned by read(2) when a read is performed.
265  int timeout ///< [IN] when a read(2) is performed return after that timeout.
266  ///< The timeout value is given with 1 decimal places.
267 );
268 
269 #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:45
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)