CSerial

Cross-platform serial port implementation.

Homepage

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.

Continuous Integration

Find builds on Jenkins!

Install(Debian-based systems)

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.

Build / Install from source

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.

Example

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:

1. Allocate a new c_serial_port_t struct. Note that this is an opaque type, and can only be passed as a pointer. Use the c_serial_new function.
2. 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, and COM1 on Windows systems. Use the c_serial_set_port_name function.
3. 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

4. (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.
5. Open the port. Use c_serial_open
6. Read and write data. Use c_serial_read_data and c_serial_write_data, respectively.

Logging

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.

Other Important Functions

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 to errno on POSIX and GetLastError 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 access
• c_serial_get_poll_handle - Get the handle used to poll for changes on a port. Useful for use with a poll()-like function. On POSIX systems, this returns the same as c_serial_get_native_handle. On Windows, this returns a HANDLE corresponding to an event created with CreateEvent on the OVERLAPPED struct associated with the serial port.

RTS Handling

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.

Bugs

Questions? Bugs? Open an issue in GitHub and I will take a look at it.

CMake support

In order to use CSerial in a CMake based project, you can use find_package to properly find and link with it. For example:

find_package(cserial)

add_executable(my-program my-program.c)
target_link_libraries(my-program PRIVATE cserial)

License

Licensed under Apache 2.0