README

   1 -------------------------------------------------------------------------------
   2 libserialport: cross-platform library for accessing serial ports
   3 -------------------------------------------------------------------------------
   4
   5 libserialport is a minimal library written in C that is intended to take care
   6 of the OS-specific details when writing software that uses serial ports.
   7
   8 By writing your serial code to use libserialport, you enable it to work
   9 transparently on any platform supported by the library.
  10
  11 The operations that are supported are:
  12
  13 - Port enumeration (obtaining a list of serial ports on the system).
  14 - Opening and closing ports.
  15 - Setting port parameters (baud rate, parity, etc).
  16 - Reading, writing and flushing data.
  17 - Obtaining error information.
  18
  19 libserialport is an open source project released under the LGPL3+ license.
  20
  21 Status
  22 ======
  23
  24 The library should build and work on any Windows or Unix-based system. If it
  25 does not, please submit a bug.
  26
  27 Enumeration is currently only implemented on Windows, Mac OS X and Linux. On
  28 other systems enumeration will return no results, but ports can still be opened
  29 by name and then used.
  30
  31 If you know how to enumerate available ports on another OS, please submit a bug
  32 with this information, or better still a patch implementing it.
  33
  34 Future
  35 ======
  36
  37 Future versions will add additional API calls for obtaining metadata about a
  38 port, e.g. for USB devices the USB VID and PID of the underlying device.
  39
  40 Dependencies
  41 ============
  42
  43 On Linux, libudev is required. On other systems no other libraries are required.
  44
  45 The libudev dependency could be eliminated in favour of direct sysfs queries at
  46 the cost of some brevity. This is not currently a priority but if you feel like
  47 doing this feel free to submit a patch.
  48
  49 Building
  50 ========
  51
  52 The package uses a GNU style build system and requires a Unix style shell.
  53 On Windows it can be built with the MinGW toolchain and MSYS environment.
  54
  55 Run "./autogen.sh" to generate the build system, "./configure" to setup, then
  56 "make" to build the library and "make install" to install it.
  57
  58 API
  59 ===
  60
  61 The API is simple, and designed to be a minimal wrapper around the serial port
  62 support in each OS.
  63
  64 Most functions take a pointer to a struct sp_port, which represents a serial
  65 port. These structures are always allocated and freed by the library, using the
  66 functions in the 'Enumeration' section below.
  67
  68 All functions can return only three possible error values. SP_ERR_ARG indicates
  69 the function was called with invalid arguments. SP_ERR_FAIL indicates that the
  70 OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed.
  71 All of these error values are negative.
  72
  73 When SP_ERR_FAIL is returned, an error code or string description of the error
  74 can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
  75 error code or message is that provided by the OS; libserialport does not define
  76 any error codes or messages of its own.
  77
  78 Function calls that succeed return SP_OK, which is equal to zero, or where
  79 otherwise documented a positive value.
  80
  81 The available functions are as follows:
  82
  83 Enumeration
  84 -----------
  85
  86 int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
  87
  88  Obtains a pointer to a new sp_port structure representing the named port. The
  89  user should allocate a variable of type "struct sp_port *" and pass a pointer
  90  to this to receive the result.
  91
  92  The result should be freed after use by calling sp_free_port().
  93
  94  Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
  95           failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
  96           is returned, the variable pointed to by port_ptr will be set to NULL.
  97           Otherwise, it will be set to point to the newly allocated port.
  98
  99 void sp_free_port(struct sp_port *port);
 100
 101  Frees a port structure obtained from sp_get_port_by_name().
 102
 103 int sp_list_ports(struct sp_port ***list_ptr);
 104
 105  Lists the serial ports available on the system. The result obtained is an
 106  array of pointers to sp_port structures, terminated by a NULL. The user should
 107  allocate a variable of type "struct sp_port **" and pass a pointer to this to
 108  receive the result.
 109
 110  The result should be freed after use by calling sp_free_port_list(). If a port
 111  from the list is to be used after freeing the list, it must be copied first
 112  using sp_copy_port().
 113
 114  Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 115           failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
 116           is returned, the variable pointed to by list_ptr will be set to NULL.
 117           Otherwise, it will be set to point to the newly allocated array.
 118
 119 int sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
 120
 121  Makes a new copy of a sp_port structure. The user should allocate a variable
 122  of type "struct sp_port *" and pass a pointer to this to receive the result.
 123
 124  The copy should be freed after use by calling sp_free_port().
 125
 126  Returns: SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG
 127           if an invalid port or pointer is passed. If any error is returned,
 128           the variable pointed to by copy_ptr will be set to NULL. Otherwise,
 129           it will be set to point to the newly allocated copy.
 130
 131 void sp_free_port_list(struct sp_port **list);
 132
 133  Frees a port list obtained from sp_list_ports(). This will also free all
 134  the sp_port structures referred to from the list; any that are to be retained
 135  must be copied first using sp_copy_port().
 136
 137 Opening and closing ports
 138 -------------------------
 139
 140 int sp_open(struct sp_port *port, int flags);
 141
 142  Opens the specified serial port.
 143
 144  Parameters:
 145
 146   port:      Pointer to port structure.
 147   flags:     Flags to use when opening the serial port. Possible
 148              flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
 149
 150  Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 151           failure, or SP_ERR_ARG if an invalid port is passed.
 152
 153 int sp_close(struct sp_port *port);
 154
 155  Closes the specified serial port.
 156
 157  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 158           if an invalid port is passed.
 159
 160 Setting port parameters
 161 -----------------------
 162
 163 int sp_set_baudrate(struct sp_port *port, int baudrate)
 164
 165  Sets the baud rate for the specified serial port.
 166
 167  Parameters:
 168
 169   port: Pointer to port structure.
 170   baud: Baud rate in bits per second.
 171
 172  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 173           for invalid arguments.
 174
 175 int sp_set_bits(struct sp_port *port, int bits)
 176
 177  Sets the number of data bits for the specified serial port.
 178
 179  Parameters:
 180
 181   port: Pointer to port structure.
 182   bits: Number of data bits to use. Valid values are 5 to 8.
 183
 184  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 185           for invalid arguments.
 186
 187 int sp_set_parity(struct sp_port *port, int parity)
 188
 189  Sets the parity for the specified serial port.
 190
 191  Parameters:
 192
 193   port:   Pointer to port structure.
 194   parity: Parity setting to use.
 195           (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
 196
 197  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 198           for invalid arguments.
 199
 200 int sp_set_stopbits(struct sp_port *port, int stopbits)
 201
 202  Sets the number of stop bits for the specified port.
 203
 204  Parameters:
 205
 206   port:     Pointer to port structure.
 207   stopbits: Number of stop bits to use (1 or 2).
 208
 209  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 210           for invalid arguments.
 211
 212 int sp_set_flowcontrol(struct sp_port *port, int flowcontrol)
 213
 214  Sets the flow control type for the specified serial port.
 215
 216  This function is a wrapper that sets the RTS, CTS, DTR, DSR and
 217  XON/XOFF settings as necessary for the specified flow control
 218  type. For more fine-grained control of these settings, use their
 219  individual configuration functions or the sp_set_config() function.
 220
 221  Parameters:
 222
 223   port:        Pointer to port structure.
 224   flowcontrol: Flow control setting to use. Valid settings are:
 225
 226    SP_FLOWCONTROL_NONE: No flow control.
 227    SP_FLOWCONTROL_XONXOFF: Software flow control using XON/XOFF characters.
 228    SP_FLOWCONTROL_RTSCTS: Hardware flow control using RTS/CTS signals.
 229    SP_FLOWCONTROL_DTRDSR: Hardware flow control using DTR/DSR signals.
 230
 231  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 232           for invalid arguments.
 233
 234 int sp_set_config(struct sp_port *port, struct sp_port_config *config)
 235
 236  Sets all parameters for the specified serial port.
 237
 238  The user should populate a struct sp_port_config, then pass a pointer to it
 239  as the config parameter.
 240
 241  The fields of sp_port_config are:
 242
 243   int baudrate: Baud rate in bits per second.
 244   int bits:     Number of data bits to use. Valid values are 5 to 8.
 245   int parity:   Parity setting to use.
 246                  (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
 247   int stopbits: Number of stop bits to use (1 or 2).
 248   int rts:      RTS pin mode.
 249                  (SP_RTS_ON, SP_RTS_OFF or SP_RTS_FLOW_CONTROL)
 250   int cts:      CTS pin mode.
 251                  (SP_CTS_IGNORE or SP_CTS_FLOW_CONTROL)
 252   int dtr:      DTR pin mode.
 253                  (SP_DTR_ON, SP_DTR_OFF or SP_DTR_FLOW_CONTROL)
 254   int dsr:      DSR pin mode.
 255                  (SP_DSR_IGNORE or SP_DSR_FLOW_CONTROL)
 256   int xon_xoff: XON/XOFF flow control mode.
 257                  (SP_XONXOFF_DISABLED, SP_XONXOFF_IN,
 258                   SP_XONXOFF_OUT or SP_XONXOFF_INOUT)
 259
 260  To retain the current value of any setting, set the field to to a
 261  negative value.
 262
 263  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 264           for invalid arguments.
 265
 266 Reading, writing and flushing data
 267 ----------------------------------
 268
 269 int sp_read(struct sp_port *port, const void *buf, size_t count)
 270
 271  Reads bytes from the specified serial port. Note that this function may
 272  return after reading less than the specified number of bytes; it is the
 273  user's responsibility to iterate as necessary in this case.
 274
 275  Parameters:
 276
 277   port:  Pointer to port structure.
 278   buf:   Buffer in which to store the bytes read.
 279   count: Maximum number of bytes to read.
 280
 281  Returns: The number of bytes read, SP_ERR_FAIL on failure,
 282           or SP_ERR_ARG for invalid arguments.
 283
 284 int sp_write(struct sp_port *port, const void *buf, size_t count)
 285
 286  Write bytes to the specified serial port. Note that this function may
 287  return after writing less than the specified number of bytes; it is the
 288  user's responsibility to iterate as necessary in this case.
 289
 290  Parameters:
 291
 292   port:  Pointer to port structure.
 293   buf:   Buffer containing the bytes to write.
 294   count: Maximum number of bytes to write.
 295
 296  Returns: The number of bytes written, SP_ERR_FAIL on failure,
 297           or SP_ERR_ARG for invalid arguments.
 298
 299 int sp_flush(struct sp_port *port);
 300
 301  Flushes serial port buffers.
 302
 303  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 304           if an invalid port is passed.
 305
 306 Error handling
 307 --------------
 308
 309 int sp_last_error_code();
 310
 311  Gets the error code for a failed operation.
 312
 313  In order to obtain the correct result, this function should be called
 314  straight after the failure, before executing any other system operations.
 315
 316  Returns: The system's numeric code for the error that caused the last
 317           operation to fail.
 318
 319 char *sp_last_error_message();
 320
 321  Gets the error message for failed operation.
 322
 323  In order to obtain the correct result, this function should be called
 324  straight after the failure, before executing other system operations.
 325
 326  Returns: The system's message for the error that caused the last
 327           operation to fail. This string may be allocated by the function,
 328           and should be freed after use by calling sp_free_error_message.
 329
 330 void sp_free_error_message(char *message);
 331
 332  Frees the error message returned by sp_last_error_message().