X-Git-Url: http://sigrok.org/gitweb/?p=libserialport.git;a=blobdiff_plain;f=README;h=fe3237cd25037e9758d97c86b00a5682d6b69675;hp=ae96bea228182e2f5ea1a472b80e3db166f2b116;hb=ec4b55ae25c368e30a5db6ab6cb33bb6abeca46c;hpb=b9a462bb47d8db62c118bed932e490ffe5b38a57 diff --git a/README b/README index ae96bea..fe3237c 100644 --- a/README +++ b/README @@ -1,6 +1,6 @@ ----------------------------------------------------------------- +------------------------------------------------------------------------------- libserialport: cross-platform library for accessing serial ports ----------------------------------------------------------------- +------------------------------------------------------------------------------- libserialport is a minimal library written in C that is intended to take care of the OS-specific details when writing software that uses serial ports. @@ -11,6 +11,7 @@ transparently on any platform supported by the library. The operations that are supported are: - Port enumeration (obtaining a list of serial ports on the system). +- Obtaining port metadata (USB device information, Bluetooth address, etc). - Opening and closing ports. - Setting port parameters (baud rate, parity, etc). - Reading, writing and flushing data. @@ -24,33 +25,29 @@ Status The library should build and work on any Windows or Unix-based system. If it does not, please submit a bug. -Enumeration is currently only implemented on Windows, Mac OS X and Linux. On -other systems enumeration will return no results, but ports can still be opened +Enumeration is currently implemented on Windows, Mac OS X, FreeBSD and Linux. +On other systems enumeration is not supported, but ports can still be opened by name and then used. If you know how to enumerate available ports on another OS, please submit a bug with this information, or better still a patch implementing it. -Future -====== - -Future versions will add additional API calls for obtaining metadata about a -port, e.g. for USB devices the USB VID and PID of the underlying device. - Dependencies ============ -On Linux, libudev is required. On other systems no other libraries are required. - -The libudev dependency could be eliminated in favour of direct sysfs queries at -the cost of some brevity. This is not currently a priority but if you feel like -doing this feel free to submit a patch. +No other libraries are required. Building ======== The package uses a GNU style build system and requires a Unix style shell. -On Windows it can be built with the MinGW toolchain and MSYS environment. + +Windows builds can be created natively with the MinGW-w64 toolchain and +MSYS2 environment, or cross-compiled using a MinGW-w64 toolchain: + + http://mingw-w64.sourceforge.net/ + +The "old" MinGW from http://mingw.org/ is not supported. Run "./autogen.sh" to generate the build system, "./configure" to setup, then "make" to build the library and "make install" to install it. @@ -58,175 +55,14 @@ Run "./autogen.sh" to generate the build system, "./configure" to setup, then API === -The API is simple, and designed to be a minimal wrapper around the serial port -support in each OS. - -Most functions take a pointer to a struct sp_port, which represents an serial -port. This structure is obtained from the array returned by sp_list_ports(). - -All functions can return only three possible error values. SP_ERR_ARG indicates -the function was called with invalid arguments. SP_ERR_FAIL indicates that the -OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed. -All of these error values are negative. - -When SP_ERR_FAIL is returned, an error code or string description of the error -can be obtained by calling sp_last_error_code() or sp_last_error_message(). The -error code or message is that provided by the OS; libserialport does not define -any error codes or messages of its own. - -Functions calls that succeed return SP_OK, which is equal to zero, or where -otherwise documented a positive value. - -The available functions are as follows: - -Enumeration ------------ - -int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); - - Obtains a pointer to a new sp_port structure representing the named port. The - user should allocate a variable of type "struct sp_port *" and pass a pointer - to this to receive the result. - - The result should be freed after use by calling sp_free_port(). - - Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation - failure, or SP_ERR_ARG if an invalid pointer is passed. If any error - is returned, the variable pointed to by port_ptr will be set to NULL. - Otherwise, it will be set to point to the newly allocated port. - -void sp_free_port(struct sp_port *port); - - Frees a port structure obtained from sp_get_port_by_name(). - -int sp_list_ports(struct sp_port ***list_ptr); - - Lists the serial ports available on the system. The result obtained is an - array of pointers to sp_port structures, terminated by a NULL. The user should - allocate a variable of type "struct sp_port **" and pass a pointer to this to - receive the result. - - The result should be freed after use by calling sp_free_port_list(). - - Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation - failure, or SP_ERR_ARG if an invalid pointer is passed. If any error - is returned, the variable pointed to by list_ptr will be set to NULL. - Otherwise, it will be set to point to the newly allocated array. - -void sp_free_port_list(struct sp_port **list); - - Frees a port list obtained from sp_list_ports(). - -Opening and closing ports -------------------------- - -int sp_open(struct sp_port *port, int flags); - - Opens the specified serial port. - - Parameters: - - port: Pointer to port structure. - flags: Flags to use when opening the serial port. Possible - flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK. - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. - -int sp_close(struct sp_port *port); - - Closes the specified serial port. - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. - -Setting port parameters ------------------------ - -int sp_set_params(struct sp_port *port, int baudrate, - int bits, int parity, int stopbits, - int flowcontrol, int rts, int dtr); - - Sets serial parameters for the specified serial port. - - Parameters: - - port: Pointer to port structure. - baudrate: Baud rate to set. - bits: Number of data bits to use. - parity: Parity setting to use - (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) - stopbits: Number of stop bits to use (1 or 2). - flowcontrol: Flow control setting to use - (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE) - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - for invalid arguments. - -Reading, writing and flushing data ----------------------------------- - -int sp_read(struct sp_port *port, const void *buf, size_t count) - - Reads bytes from the specified serial port. Note that this function may - return after reading less than the specified number of bytes; it is the - user's responsibility to iterate as necessary in this case. - - Parameters: - - port: Pointer to port structure. - buf: Buffer in which to store the bytes read. - count: Maximum number of bytes to read. - - Returns: The number of bytes read, SP_ERR_FAIL on failure, - or SP_ERR_ARG for invalid arguments. - -int sp_write(struct sp_port *port, const void *buf, size_t count) - - Write bytes to the specified serial port. Note that this function may - return after writing less than the specified number of bytes; it is the - user's responsibility to iterate as necessary in this case. - - Parameters: - - port: Pointer to port structure. - buf: Buffer containing the bytes to write. - count: Maximum number of bytes to write. - - Returns: The number of bytes written, SP_ERR_FAIL on failure, - or SP_ERR_ARG for invalid arguments. - -int sp_flush(struct sp_port *port); - - Flushes serial port buffers. - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. - -Error handling --------------- - -int sp_last_error_code(); - - Gets the error code for a failed operation. - - In order to obtain the correct result, this function should be called - straight after the failure, before executing any other system operations. - - Returns: The system's numeric code for the error that caused the last - operation to fail. - -char *sp_last_error_message(); +Doxygen API documentation is included. - Gets the error message for failed operation. +It can also be viewed online at: - In order to obtain the correct result, this function should be called - straight after the failure, before executing other system operations. + http://sigrok.org/api/libserialport/unstable/ - Returns: The system's message for the error that caused the last - operation to fail. This string may be allocated by the function, - and should be freed after use by calling sp_free_error_message. +Website +======= -void sp_free_error_message(char *message); +http://sigrok.org/wiki/Libserialport - Frees the error message returned by sp_last_error_message().