X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=README;h=817dff743df4ae7ae07f37eea955e0d0a8853f4b;hb=HEAD;hp=e0ace9787d3077d168d0ccd12fbe698b1f355e45;hpb=e9a2f9c9d35624148b4715e80c2dc2ac0387ee6b;p=libserialport.git diff --git a/README b/README index e0ace97..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,182 +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 an open -port. This structure should be allocated by the user and is populated by -sp_open(). It can be freed safely after sp_close(). - -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. -Aoth 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 ------------ - -char **sp_list_ports(); - - Lists the serial ports available on the system. The value returned is an array - of port names as C strings, terminated by a NULL. It should be freed after use - by calling sp_free_port_list(). - -void sp_free_port_list(char **list); - - Frees the data structure returned by sp_list_ports(). - -Opening and closing ports -------------------------- - -int sp_open(struct sp_port *port, char *portname, int flags); - - Opens the specified serial port. - - Parameters: - - port: Pointer to empty port structure, allocated by caller. - portname: Name of port to open. - 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 or name is passed. +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. -int sp_close(struct sp_port *port); +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. - 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 a number of bytes from the specified serial port. - - Parameters: - - port: Pointer to port structure. - buf: Buffer in which to store the bytes read. - count: 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) - - Writes a number of bytes to the specified serial port. - - Parameters: - - port: Pointer to port structure. - buf: Buffer containing the bytes to write. - count: 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().