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 an open
  65 port. This structure should be allocated by the user and is populated by
  66 sp_open(). It can be freed safely after sp_close().
  67
  68 All functions can return only two 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. Both these error values are negative.
  71
  72 When SP_ERR_FAIL is returned, an error code or string description of the error
  73 can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
  74 error code or message is that provided by the OS; libserialport does not define
  75 any error codes or messages of its own.
  76
  77 Functions calls that succeed return SP_OK, which is equal to zero, or where
  78 otherwise documented a positive value.
  79
  80 The available functions are as follows:
  81
  82 Enumeration
  83 -----------
  84
  85 char **sp_list_ports();
  86
  87  Lists the serial ports available on the system. The value returned is an array
  88  of port names as C strings, terminated by a NULL. It should be freed after use
  89  by calling sp_free_port_list().
  90
  91 void sp_free_port_list(char **list);
  92
  93  Frees the data structure returned by sp_list_ports().
  94
  95 Opening and closing ports
  96 -------------------------
  97
  98 int sp_open(struct sp_port *port, char *portname, int flags);
  99
 100  Opens the specified serial port.
 101
 102  Parameters:
 103
 104   port:      Pointer to empty port structure, allocated by caller.
 105   portname:  Name of port to open.
 106   flags:     Flags to use when opening the serial port. Possible
 107              flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
 108
 109  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 110           if an invalid port or name is passed.
 111
 112 int sp_close(struct sp_port *port);
 113
 114  Closes the specified serial port.
 115
 116  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 117           if an invalid port is passed.
 118
 119 Setting port parameters
 120 -----------------------
 121
 122 int sp_set_params(struct sp_port *port, int baudrate,
 123                               int bits, int parity, int stopbits,
 124                               int flowcontrol, int rts, int dtr);
 125
 126  Sets serial parameters for the specified serial port.
 127
 128  Parameters:
 129
 130   port:        Pointer to port structure.
 131   baudrate:    Baud rate to set.
 132   bits:        Number of data bits to use.
 133   parity:      Parity setting to use
 134                (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
 135   stopbits:    Number of stop bits to use (1 or 2).
 136   flowcontrol: Flow control setting to use
 137                (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE)
 138
 139  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 140           for invalid arguments.
 141
 142 Reading, writing and flushing data
 143 ----------------------------------
 144
 145 int sp_read(struct sp_port *port, const void *buf, size_t count)
 146
 147  Reads a number of bytes from the specified serial port.
 148
 149  Parameters:
 150
 151   port:  Pointer to port structure.
 152   buf:   Buffer in which to store the bytes read.
 153   count: Number of bytes to read.
 154
 155  Returns: The number of bytes read, SP_ERR_FAIL on failure,
 156           or SP_ERR_ARG for invalid arguments.
 157
 158 int sp_write(struct sp_port *port, const void *buf, size_t count)
 159
 160  Writes a number of bytes to the specified serial port.
 161
 162  Parameters:
 163
 164   port:  Pointer to port structure.
 165   buf:   Buffer containing the bytes to write.
 166   count: Number of bytes to write.
 167
 168  Returns: The number of bytes written, SP_ERR_FAIL on failure,
 169           or SP_ERR_ARG for invalid arguments.
 170
 171 int sp_flush(struct sp_port *port);
 172
 173  Flushes serial port buffers.
 174
 175  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 176           if an invalid port is passed.
 177
 178 Error handling
 179 --------------
 180
 181 int sp_last_error_code();
 182
 183  Gets the error code for a failed operation.
 184
 185  In order to obtain the correct result, this function should be called
 186  straight after the failure, before executing any other system operations.
 187
 188  Returns: The system's numeric code for the error that caused the last
 189           operation to fail.
 190
 191 char *sp_last_error_message();
 192
 193  Gets the error message for failed operation.
 194
 195  In order to obtain the correct result, this function should be called
 196  straight after the failure, before executing other system operations.
 197
 198  Returns: The system's message for the error that caused the last
 199           operation to fail. This string may be allocated by the function,
 200           and should be freed after use by calling sp_free_error_message.
 201
 202 void sp_free_error_message(char *message);
 203
 204  Frees the error message returned by sp_last_error_message().