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 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 //--------------------------------------------------------------------------------------------------
  166 le_result_t le_tty_SetBaudRate
  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 //--------------------------------------------------------------------------------------------------
  182 le_result_t le_tty_GetBaudRate
  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 //--------------------------------------------------------------------------------------------------
  201 le_result_t le_tty_SetFraming
  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 //--------------------------------------------------------------------------------------------------
  223 le_result_t le_tty_SetFlowControl
  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 //--------------------------------------------------------------------------------------------------
  240 le_result_t le_tty_SetCanonical
  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 //--------------------------------------------------------------------------------------------------
  256 le_result_t le_tty_SetRaw
  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
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:45
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)