le_tty.h

    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 //--------------------------------------------------------------------------------------------------
  171 le_result_t le_tty_SetBaudRate
  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 //--------------------------------------------------------------------------------------------------
  187 le_result_t le_tty_GetBaudRate
  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 //--------------------------------------------------------------------------------------------------
  206 le_result_t le_tty_SetFraming
  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 //--------------------------------------------------------------------------------------------------
  228 le_result_t le_tty_SetFlowControl
  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 //--------------------------------------------------------------------------------------------------
  245 le_result_t le_tty_SetCanonical
  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 //--------------------------------------------------------------------------------------------------
  261 le_result_t le_tty_SetRaw
  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
le_tty_Open
int le_tty_Open(const char *ttyDev, int flags)
le_tty_Close
void le_tty_Close(int fd)
le_result_t
le_result_t
Definition: le_basics.h:46
le_tty_SetFlowControl
le_result_t le_tty_SetFlowControl(int fd, tty_FlowControl_t ttyFlowControl)
le_tty_SetRaw
le_result_t le_tty_SetRaw(int fd, int numChars, int timeout)
le_tty_SetFraming
le_result_t le_tty_SetFraming(int fd, char parity, int wordSize, int stopBits)
le_tty_SetCanonical
le_result_t le_tty_SetCanonical(int fd)
le_tty_SetBaudRate
le_result_t le_tty_SetBaudRate(int fd, tty_Speed_t ttyRate)
le_tty_GetBaudRate
le_result_t le_tty_GetBaudRate(int fd, tty_Speed_t *ttyInRatePtr, tty_Speed_t *ttyOutRatePtr)