Cross-platform serial port implementation.
Based largely off of JavaSerial, CSerial aims to bring cross-platform serial programming to a computer near you.
The library is structured along the lines of the Apache Portable Runtime(APR). It aims to provide as much low-level support as is required to create a working serial port implementation.
CSerial is designed to be fully POSIX-compliant, however if it is not please open an issue on GitHub. See the 'Bugs' section for more details on this.
Find builds on Jenkins!
There is an APT server setup that provides CSerial that you can find here. Note that because the 'nightly' repo contains packages for both amd64 and armhf, you may need to specify the exact version to install, as otherwise it may attempt to install one from an incorrect arch.
Building is done using CMake. On Linux, this should be done like the following:
~$ mkdir CSerial_build
~$ cd CSerial_build
~$ cmake /path/to/CSerial_code
~$ make
~$ make install
On Windows, I recommend using CMake to create a new Visual Studio project and building the code that way. I have not tested cygwin nor MinGW makefiles as generated by CMake.
For information on how to use the library, check out the example program under the 'examples' directory.
The simplified flow of how to use the library is below:
- Allocate a new
c_serial_port_t
struct. Note that this is an opaque type, and can only be passed as a pointer. Use thec_serial_new
function. - Set the name of the serial port. This is the actual serial port that will
be opened. It will be something like
/dev/ttyS0
on Linux systems, andCOM1
on Windows systems. Use thec_serial_set_port_name
function. - Set the serial port parameters. By default, the port will be opened at
9600-8-N-1
. Any other settings can be set with the appropriate setters.
- To set the baud rate, use
c_serial_set_baud_rate
- To set the number of data bits, use
c_serial_set_data_bits
- To set the number of stop bits, use
c_cserial_set_stop_bits
- To set the parity, use
c_serial_set_parity
- To set the flow control, use
c_serial_set_flow_control
- (optional) Set the serial line change flags. This determines what changes
on a serial line will cause a read to return. By default, no flags are set.
Use the
c_serial_set_serial_line_change_flags
function to set the flags. - Open the port. Use
c_serial_open
- Read and write data. Use
c_serial_read_data
andc_serial_write_data
, respectively.
The library has some rudimentary logging. This may be set as either a global log function, or as a log function per-port. There exists a simple implementation of a logger which will print out every message to stderr. This is intended for use with a secondary logging framework, so that logs may all be used by one logging facility.
The relevant functions for logging are c_serial_set_log_function
for logging
a single serial port, and c_serial_set_global_log_function
for logging
all messages. Note that some messages can only go to the global log function,
as there is not always a serial port associated with some of the operations.
Note that all functions can be see in the Doxygen documentation with the proper documentation.
The following presents a brief list of other functions which may be important:
c_serial_get_serial_ports_list
- Go through the system and find all of the valid serial ports.c_serial_get_last_native_errnum
- Return the last native error number.
This corresponds toerrno
on POSIX andGetLastError
on Windows.c_serial_[set|get]_user_data
- Set / get user data(void*
) associated with the port.c_serial_get_available
- Get the number of bytes to read.c_serial_get_native_handle
- Get the native handle(int on POSIX, HANDLE on Windows) for raw I/O accessc_serial_get_poll_handle
- Get the handle used to poll for changes on a port. Useful for use with apoll()
-like function. On POSIX systems, this returns the same asc_serial_get_native_handle
. On Windows, this returns aHANDLE
corresponding to an event created withCreateEvent
on theOVERLAPPED
struct associated with the serial port.
The library also supports toggling of the RTS line when transmitting data
over the serial port. This is generally used for RS-485 transmitting. This
can be set to several different settings(see the enum CSerial_RTS_Handling
for more details). If set to HARDWARE, this will attempt to use the built-in
kernel level functions for controlling the RTS line(using struct serial_rs485
on Linux, or setting fRtsControl
on Windows). Setting it to SOFTWARE will
cause the library to manually toggle the RTS line when sending data.
Questions? Bugs? Open an issue in GitHub and I will take a look at it.
Licensed under Apache 2.0