libserial  1.6.2
RoadNarrows Roboitics Serial Library
serdev.h
Go to the documentation of this file.
1 ////////////////////////////////////////////////////////////////////////////////
2 //
3 // Package: RCB3
4 //
5 // Library: libserial
6 //
7 // File: serdev.h
8 //
9 /*! \file
10  *
11  * $LastChangedDate: 2015-01-07 20:22:07 -0700 (Wed, 07 Jan 2015) $
12  * $Rev: 3839 $
13  *
14  * \brief RS-232 serial device communication declarations and defines.
15  *
16  * Ported from ipser.h (RoadNarrows)
17  *
18  * \author Robin Knight (robin.knight@roadnarrows.com)
19  *
20  * \copyright
21  * \h_copy 2006-2017. RoadNarrows LLC.\n
22  * http://www.roadnarrows.com\n
23  * All Rights Reserved
24  */
25 /*
26  * @EulaBegin@
27 // Permission is hereby granted, without written agreement and without
28 // license or royalty fees, to use, copy, modify, and distribute this
29 // software and its documentation for any purpose, provided that
30 // (1) The above copyright notice and the following two paragraphs
31 // appear in all copies of the source code and (2) redistributions
32 // including binaries reproduces these notices in the supporting
33 // documentation. Substantial modifications to this software may be
34 // copyrighted by their authors and need not follow the licensing terms
35 // described here, provided that the new terms are clearly indicated in
36 // all files where they apply.
37 //
38 // IN NO EVENT SHALL THE AUTHOR, ROADNARROWS LLC, OR ANY MEMBERS/EMPLOYEES
39 // OF ROADNARROW LLC OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
40 // PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
41 // DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
42 // EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
43 // THE POSSIBILITY OF SUCH DAMAGE.
44 //
45 // THE AUTHOR AND ROADNARROWS LLC SPECIFICALLY DISCLAIM ANY WARRANTIES,
46 // INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
47 // FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
48 // "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
49 // PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
50  * @EulaEnd@
51  */
52 ////////////////////////////////////////////////////////////////////////////////
53 
54 #ifndef _SERDEV_H
55 #define _SERDEV_H
56 
57 #include "rnr/rnrconfig.h"
58 
59 C_DECLS_BEGIN
60 
61 //
62 // Common character end-of-line terminator sequences.
63 //
64 #ifndef EOL_CRLF
65 #define EOL_CRLF "\r\n" // carriage-return,line-feed
66 #endif
67 #ifndef EOL_LFCR
68 #define EOL_LFCR "\n\r" // line-feed,carriage-return
69 #endif
70 #ifndef EOL_CR
71 #define EOL_CR "\r" // carriage-return
72 #endif
73 #ifndef EOL_NL
74 #define EOL_NL "\n" // line-feed
75 #endif
76 
77 
78 //-----------------------------------------------------------------------------
79 // Prototypes
80 //-----------------------------------------------------------------------------
81 
82 /*!
83  * \brief Open and configure serial device for communication.
84  *
85  * \param sSerDevName Serial device port name (e.g. /dev/ttyS0).
86  * \param nBaudRate Baud rate.
87  * \param nByteSize Bytes size in bits 5...8.
88  * \param cParity Parity. One of: 'N', 'E', 'O'
89  * \param nStopBits Number of stop bits 1, 2
90  * \param bRtsCts Do [not] use hardware flow control.
91  * \param bXonXoff Do [not] use software flow control.
92  *
93  * \return
94  * On success, a file descriptor(>=0) to the opened serial device.
95  * \n On failure, errno is set and RC_ERROR(-1) is returned.
96  */
97 extern int SerDevOpen(const char *sSerDevName,
98  int nBaudRate,
99  int nByteSize,
100  int cParity,
101  int nStopBits,
102  bool_t bRtsCts,
103  bool_t bXonXoff);
104 
105 /*!
106  * \brief Close serial device port.
107  *
108  * \param fd File descriptor to the opened serial device.
109  *
110  * \return
111  * On success, OK(0) is returned.
112  * \n On failure, errno is set and RC_ERROR(-1) is returned.
113  */
114 extern int SerDevClose(int fd);
115 
116 /*!
117  * \brief Read a ASCII character line from the serial device.
118  *
119  * Read up to \em count bytes into \em buffer from the serial device input.
120  * This call is non-blocking if the timeout value \em usec is greater than
121  * zero. Otherwise the read can block indefinitely.
122  *
123  * The end-of-line sequence defines the end of the line. It is stripped from the
124  * return buffer.
125  *
126  * \param fd File descriptor to the opened serial device.
127  * \param [out] buffer Output read buffer.
128  * \param count Number of bytes to read.
129  * \param eol End-of-line character sequence > 0.
130  * \param usec Timeout in microseconds.
131  * \n If \em usec > 0, an upper timeout limit is placed on
132  * the read.
133  * \n If \em usec == 0, then the read will block indefinitely
134  * until \em count bytes are read or an I/O error occurred.
135  *
136  * \return
137  * On success, the number of bytes read into buffer.
138  * \n On failure, errno is set and RC_ERROR(-1) is returned.
139  * \n In either case, the buffer is guaranteed to be NULL terminated.
140  */
141 extern ssize_t SerDevReadLine(int fd,
142  char buffer[],
143  size_t count,
144  char *eol,
145  uint_t usec);
146 
147 /*!
148  * \brief Write null-terminated ASCII character line to serial device.
149  *
150  * Write line plus end-of-line sequence.
151  * This call is non-blocking if the timeout value \em usec is greater
152  * than zero. Otherwise the write can block indefinitely.
153  *
154  * \param fd File descriptor to the opened serial device.
155  * \param [in] buffer Buffer to write.
156  * \param eol End-of-line character sequence to append to buffer
157  * output.
158  * \param usec Timeout in microseconds.
159  * \n If \em usec > 0, an upper timeout limit is placed on
160  * the write.
161  * \n If \em usec == 0, then the write will block indefinitely
162  * until \em count bytes are written or an I/O error
163  * occurred.
164  *
165  * \return
166  * On success, the number of bytes written is returned.
167  * \n On failure, errno is set and RC_ERROR(-1) is returned.
168  */
169 extern ssize_t SerDevWriteLine(int fd,
170  char *buffer,
171  char *eol,
172  uint_t usec);
173 
174 /*!
175  * \brief Get 1 character from the serial device.
176  *
177  * Read 1 character from the serial device input.
178  * This call is non-blocking if the timeout value \em usec is greater than
179  * zero. Otherwise the read can block indefinitely.
180  *
181  * \param fd File descriptor to the opened serial device.
182  * \param usec Timeout in microseconds.
183  * \n If \em usec > 0, an upper timeout limit is placed on the
184  * read.
185  * \n If \em usec == 0, then the read will block indefinitely
186  * until \em count bytes are read or an I/O error occurred.
187  *
188  * \return
189  * On success, returns the character read as unsigned char cast to an int.
190  * \n On failure, errno is set and RC_ERROR(-1) is returned.
191  */
192 extern int SerDevGetc(int fd, uint_t usec);
193 
194 /*!
195  * \brief Put one character to serial device.
196  *
197  * Write 1 character to the serial device output.
198  * This call is non-blocking if the timeout value \em usec is greater than
199  * zero. Otherwise the write can block indefinitely.
200  *
201  * \param fd File descriptor to the opened serial device.
202  * \param byte Character to write.
203  * \param usec Timeout in microseconds.
204  * \n If \em usec > 0, an upper timeout limit is placed on the
205  * write.
206  * \n If \em usec == 0, then the write will block indefinitely
207  * until \em count bytes are written or an I/O error occurred.
208  *
209  * \return
210  * On success, returns the character written as unsigned char cast to an int.
211  * \n On failure, errno is set and RC_ERROR(-1) is returned.
212  */
213 extern int SerDevPutc(int fd, byte_t byte, uint_t usec);
214 
215 /*!
216  * \brief Read from the serial device.
217  *
218  * Read up to \em count bytes into \em buffer from the serial device input.
219  * This call is non-blocking if the timeout value \em usec is greater than
220  * zero. Otherwise the read can block indefinitely.
221  *
222  * Note the the bytes read can be less than the \em count.
223  *
224  * \param fd File descriptor to the opened serial device.
225  * \param buffer Output read buffer.
226  * \param count Number of bytes to read.
227  * \param usec Timeout in microseconds.
228  * \n If \em usec > 0, an upper timeout limit is placed on the
229  * read.
230  * \n If \em usec == 0, then the read will block indefinitely
231  * until \em count bytes are read or an I/O error occurred.
232  *
233  * \return
234  * On success, the number of bytes read into buffer.
235  * \n On failure, errno is set and RC_ERROR(-1) is returned.
236  */
237 extern ssize_t SerDevRead(int fd,
238  byte_t *buffer,
239  size_t count,
240  uint_t usec);
241 
242 /*!
243  * \brief Write to serial device.
244  *
245  * Write up to \em count bytes from the \em buffer to the serial device
246  * output. This call is non-blocking if the timeout value \em usec is greater
247  * than zero. Otherwise the write can block indefinitely.
248  *
249  * Note that the number of bytes written can be less than the \em count.
250  *
251  * \param fd File descriptor to the opened serial device.
252  * \param buffer Input write buffer.
253  * \param count Number of of bytes to write.
254  * \param usec Timeout in microseconds.
255  * \n If \em usec > 0, an upper timeout limit is placed on the
256  * write.
257  * \n If \em usec == 0, then the write will block indefinitely
258  * until \em count bytes are written or an I/O error occurred.
259  *
260  * \return
261  * On success, the number of bytes written is returned.
262  * \n On failure, errno is set and RC_ERROR(-1) is returned.
263  */
264 extern ssize_t SerDevWrite(int fd,
265  byte_t *buffer,
266  size_t count,
267  uint_t usec);
268 
269 /*!
270  * \brief Determine the number of bytes in the input FIFO of the serial device.
271  *
272  * The input FIFO holds data received but not read.
273  *
274  * \param fd File descriptor to the opened serial device.
275  *
276  * \return
277  * On success, the number of bytes in the input FIFO.
278  * \n On failure, errno is set and RC_ERROR(-1) is returned.
279  */
280 extern ssize_t SerDevFIFOInputCount(int fd);
281 
282 /*!
283  * \brief Flush the input FIFO buffer, discarding all data in buffer.
284  *
285  * The input FIFO holds data received but not read.
286  *
287  * This function does not block.
288  *
289  * \param fd File descriptor to the opened serial device.
290  *
291  * \return The number of bytes flushed.
292  */
293 extern ssize_t SerDevFIFOInputFlush(int fd);
294 
295 /*!
296  * \brief Flush output FIFO buffer, discarding all data in buffer.
297  *
298  * The output FIFO holds data written to the device but not transmitted.
299  *
300  * This function does not block.
301  *
302  * \param fd File descriptor to the opened serial device.
303  */
304 extern void SerDevFIFOOutputFlush(int fd);
305 
306 /*!
307  * \brief Transmit (drain) all data written to the output FIFO buffer.
308  *
309  * The output FIFO holds data written to the device but not transmitted.
310  *
311  * This function blocks until all of the FIFO data has been transmitted.
312  *
313  * \param fd File descriptor to the opened serial device.
314  */
315 extern void SerDevFIFOOutputDrain(int fd);
316 
317 /*!
318  * \brief Checks to see if there are bytes in the input queue availabe
319  * to be read.
320  *
321  * \param fd File descriptor to the opened serial device.
322  *
323  * \return Returns true if bytes are available, else false.
324  */
325 INLINE_IN_H bool_t SerDevIsInputDataPresent(int fd)
326 {
327  return SerDevFIFOInputCount(fd)>0? true: false;
328 }
329 
330 /*!
331  * \brief Set the baudrate.
332  *
333  * \param fd File descriptor to the opened serial device.
334  * \param nBaudRate Baud rate.
335  *
336  * \return
337  * Returns OK(0) on success.
338  * \n On failure, errno is set and RC_ERROR(-1) is returned.
339  */
340 extern int SerDevSetBaudRate(int fd, int nBaudRate);
341 
342 /*!
343  * \brief Set the byte size.
344  *
345  * \param fd File descriptor to the opened serial device.
346  * \param nByteSize Bytes size in bits 5...8.
347  *
348  * \return
349  * Returns OK(0) on success.
350  * \n On failure, errno is set and RC_ERROR(-1) is returned.
351  */
352 extern int SerDevSetByteSize(int fd, int nByteSize);
353 
354 /*!
355  * \brief Set the parity.
356  *
357  * \param fd File descriptor to the opened serial device.
358  * \param cParity Parity. One of: 'N', 'E', 'O'
359  *
360  * \return
361  * Returns OK(0) on success.
362  * \n On failure, errno is set and RC_ERROR(-1) is returned.
363  */
364 extern int SerDevSetParity(int fd, int cParity);
365 
366 /*!
367  * \brief Set the number of stop bits.
368  *
369  * \param fd File descriptor to the opened serial device.
370  * \param nStopBits Number of stop bits 1, 2
371  *
372  * \return
373  * Returns OK(0) on success.
374  * \n On failure, errno is set and RC_ERROR(-1) is returned.
375  */
376 extern int SerDevSetStopBits(int fd, int nStopBitgs);
377 
378 /*!
379  * \brief Set hardware flow control state.
380  *
381  * \param fd File descriptor to the opened serial device.
382  * \param bRtsCts Do [not] use hardware flow control.
383  *
384  * \return
385  * Returns OK(0) on success.
386  * \n On failure, errno is set and RC_ERROR(-1) is returned.
387  */
388 extern int SerDevSetHwFlowControl(int fd, bool_t bRtsCts);
389 
390 /*!
391  * \brief Set software flow control state.
392  *
393  * \param fd File descriptor to the opened serial device.
394  * \param bXonXoff Do [not] use software flow control.
395  *
396  * \return
397  * Returns OK(0) on success.
398  * \n On failure, errno is set and RC_ERROR(-1) is returned.
399  */
400 extern int SerDevSetSwFlowControl(int fd, bool_t bXonXoff);
401 
402 /*!
403  * \brief Assert RTS (request to send).
404  *
405  * \param fd File descriptor to the opened serial device.
406  *
407  * \return
408  * Returns OK(0) on success.
409  * \n On failure, errno is set and RC_ERROR(-1) is returned.
410  */
411 extern int SerDevAssertRTS(int fd);
412 
413 /*!
414  * \brief De-assert RTS (request to send).
415  *
416  * \param fd File descriptor to the opened serial device.
417  *
418  * \return
419  * Returns OK(0) on success.
420  * \n On failure, errno is set and RC_ERROR(-1) is returned.
421  */
422 extern int SerDevDeassertRTS(int fd);
423 
424 /*!
425  * \brief Assert RTS (clear to send).
426  *
427  * \param fd File descriptor to the opened serial device.
428  *
429  * \return
430  * Returns OK(0) on success.
431  * \n On failure, errno is set and RC_ERROR(-1) is returned.
432  */
433 extern int SerDevAssertCTS(int fd);
434 
435 /*!
436  * \brief De-assert RTS (clear to send).
437  *
438  * \param fd File descriptor to the opened serial device.
439  *
440  * \return
441  * Returns OK(0) on success.
442  * \n On failure, errno is set and RC_ERROR(-1) is returned.
443  */
444 extern int SerDevDeassertCTS(int fd);
445 
446 
447 C_DECLS_END
448 
449 
450 #endif // _SERDEV_H
SerDevFIFOInputFlush
ssize_t SerDevFIFOInputFlush(int fd)
Flush the input FIFO buffer, discarding all data in buffer.
Definition: serdev.c:1202
SerDevWriteLine
ssize_t SerDevWriteLine(int fd, char *buffer, char *eol, uint_t usec)
Write null-terminated ASCII character line to serial device.
Definition: serdev.c:812
SerDevOpen
int SerDevOpen(const char *sSerDevName, int nBaudRate, int nByteSize, int cParity, int nStopBits, bool_t bRtsCts, bool_t bXonXoff)
Open and configure serial device for communication.
Definition: serdev.c:663
SerDevIsInputDataPresent
INLINE_IN_H bool_t SerDevIsInputDataPresent(int fd)
Checks to see if there are bytes in the input queue availabe to be read.
Definition: serdev.h:325
SerDevDeassertCTS
int SerDevDeassertCTS(int fd)
De-assert RTS (clear to send).
Definition: serdev.c:1521
SerDevSetByteSize
int SerDevSetByteSize(int fd, int nByteSize)
Set the byte size.
Definition: serdev.c:1266
SerDevSetSwFlowControl
int SerDevSetSwFlowControl(int fd, bool_t bXonXoff)
Set software flow control state.
Definition: serdev.c:1410
SerDevFIFOInputCount
ssize_t SerDevFIFOInputCount(int fd)
Determine the number of bytes in the input FIFO of the serial device.
Definition: serdev.c:1146
SerDevClose
int SerDevClose(int fd)
Close serial device port.
Definition: serdev.c:704
SerDevReadLine
ssize_t SerDevReadLine(int fd, char buffer[], size_t count, char *eol, uint_t usec)
Read a ASCII character line from the serial device.
Definition: serdev.c:720
SerDevPutc
int SerDevPutc(int fd, byte_t byte, uint_t usec)
Put one character to serial device.
Definition: serdev.c:910
SerDevWrite
ssize_t SerDevWrite(int fd, byte_t *buffer, size_t count, uint_t usec)
Write to serial device.
Definition: serdev.c:1061
SerDevRead
ssize_t SerDevRead(int fd, byte_t *buffer, size_t count, uint_t usec)
Read from the serial device.
Definition: serdev.c:976
SerDevSetBaudRate
int SerDevSetBaudRate(int fd, int nBaudRate)
Set the baudrate.
Definition: serdev.c:1230
SerDevGetc
int SerDevGetc(int fd, uint_t usec)
Get 1 character from the serial device.
Definition: serdev.c:843
SerDevDeassertRTS
int SerDevDeassertRTS(int fd)
De-assert RTS (request to send).
Definition: serdev.c:1479
SerDevSetHwFlowControl
int SerDevSetHwFlowControl(int fd, bool_t bRtsCts)
Set hardware flow control state.
Definition: serdev.c:1350
SerDevFIFOOutputFlush
void SerDevFIFOOutputFlush(int fd)
Flush output FIFO buffer, discarding all data in buffer.
Definition: serdev.c:1216
SerDevFIFOOutputDrain
void SerDevFIFOOutputDrain(int fd)
Transmit (drain) all data written to the output FIFO buffer.
Definition: serdev.c:1223
SerDevSetParity
int SerDevSetParity(int fd, int cParity)
Set the parity.
Definition: serdev.c:1297
SerDevAssertCTS
int SerDevAssertCTS(int fd)
Assert RTS (clear to send).
Definition: serdev.c:1500
SerDevSetStopBits
int SerDevSetStopBits(int fd, int nStopBitgs)
Set the number of stop bits.
Definition: serdev.c:1326
SerDevAssertRTS
int SerDevAssertRTS(int fd)
Assert RTS (request to send).
Definition: serdev.c:1458