X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=blobdiff_plain;f=README;h=f63be5cdb2161415bddc402d9e5c54e95ff097bf;hp=6e3b480129b683e36104bf03609de245fc056eab;hb=HEAD;hpb=c45eb4bee2533fc4ac65375c12ba8ed369f61379 diff --git a/README b/README index 6e3b480..817dff7 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,210 +25,68 @@ 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. +On Windows, libserialport can be built with Visual Studio 2019 or with +the standalone MSBuild tool, using the solution and project files provided. + +For other environments, the package uses a GNU style build based on autotools. Run "./autogen.sh" to generate the build system, "./configure" to setup, then "make" to build the library and "make install" to install it. -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 a serial -port. These structures are always allocated and freed by the library, using the -functions in the 'Enumeration' section below. - -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. +Windows builds can also be created using the autotools build system, using the +MinGW-w64 toolchain from http://mingw-w64.sourceforge.net/ - either natively +in Windows with the MSYS2 environment, or cross-compiling from another system. - Parameters: +To build from MSYS2, the following packages must be installed: autoconf, +automake-wrapper, libtool, make, and either mingw-w64-i686-gcc (for 32-bit) +or mingw-w64-x86_64-gcc (for 64-bit). Open either the "MSYS2 MinGW 32-bit" or +"MSYS2 MinGW 64-bit" command window from the Start menu and use this when +configuring and building the package. Using the "MSYS2 MSYS" shell will build +against the Cygwin compatibility layer; this works, but port enumeration and +metadata will not be available, and binaries will depend on Cygwin. The builds +produced by MinGW-w64 are normal Windows DLLs without additional dependencies. - 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. +API +=== - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. +Doxygen API documentation is included. -Error handling --------------- +It can also be viewed online at: -int sp_last_error_code(); + http://sigrok.org/api/libserialport/unstable/ - Gets the error code for a failed operation. +Bug reports +=========== - In order to obtain the correct result, this function should be called - straight after the failure, before executing any other system operations. +You can report bugs for libserialport at https://sigrok.org/bugzilla. - Returns: The system's numeric code for the error that caused the last - operation to fail. +Mailing list +============ -char *sp_last_error_message(); + https://lists.sourceforge.net/lists/listinfo/sigrok-devel - Gets the error message for failed operation. +IRC +=== - In order to obtain the correct result, this function should be called - straight after the failure, before executing other system operations. +You can find the developers in the #sigrok IRC channel on Libera.Chat. - 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().