Thanks for checking out LibSerial! LibSerial provides a convenient, object oriented approach to accessing serial ports on Linux operating system.
After you get to know LibSerial a bit, if you find that you have ideas for improvement, please be sure to let us know!
If you simply want to use LibSerial and you already utilize a Debian Linux distribution, use apt to install the current release package:
sudo apt install libserial-dev
Note that the above command may install an older version of LibSerial (e.g. 0.6.0 on Ubuntu 18.04). In order to use the latest features and the example project mentioned below, please build the library from source code as described in here. We are working to release updated versions of the library from package repositories of major Linux distribution in the mean time and apologize for the inconvenience.
Example code to demonstrate how to use the library can be found in the
A self-contained example project demonstrating the use of CMake and GNU Autotools (make) can be found in
If you are a developer and would like to make use of the latest code, you will need to have a few packages installed to build LibSerial: a recent g++ release (anything after gcc-3.2 should work), autotools, cmake, doxygen, sphinx, the python3 sip library, the boost unit test library, pkg-config, and Google Test (gtest). The following commands should install the required packages for Debian/Ubuntu users:
sudo apt update sudo apt install g++ git autogen autoconf build-essential cmake graphviz \ libboost-dev libboost-test-dev libgtest-dev libtool \ python3-sip-dev doxygen python3-sphinx pkg-config \ python3-sphinx-rtd-theme
If you get the source code from github and would like to install the library, there are a few steps you will need to accomplish:
If you are using CMake, to build the library you can simply run the
To install the library:
cd build sudo make install
You can specify an installation directory different from the default, (/usr/local/), by replacing the
cmake .. command in the
compile.sh script. For example, to install under
/usr instead of the
/usr/local directory, use the following:
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
GNU Autotools is currently configured to built all unit tests, so first you will need to compile the GTest library object files and copy
libgtest_main.a into your
/usr/lib/ directory which you can accomplish by running the
gtest.sh convenience script:
To generate the configure script:
make -f Makefile.dist
To execute the
configure script, first create a build directory, then run the script from the build directory as follows:
You can specify an installation directory different from the default, (
/usr/local/), by adding
--prefix=/installation/directory/path/ to the configure command. For example, to install into the top level include directory as the package manager would accomplish, you can simply run the following:
Once you have executed the
configure script, you can build the library with
make and install with
make sudo make install
If you are interested in running the unit tests or example code, ensure serial port names are appropriate for your hardware configuration in the
examples/ directory files and in the
test/UnitTests.h file as such:
constexpr const char* const SERIAL_PORT_1 = "/dev/ttyUSB0" ; constexpr const char* const SERIAL_PORT_2 = "/dev/ttyUSB1" ;
Example code and Unit test executables are easily built using the cmake compile script and can be run from the
Unit test executables built using make can be run from the
build directory in the following manner:
ctest -V .
If needed, you can grant user permissions to utilize the hardware ports in the following manner, (afterwards a reboot is required):
sudo usermod -a -G dialout $USER sudo usermod -a -G plugdev $USER
Socat is a useful tool to allow hardware ports to communicate on the same system via a software pipe. As an example, to allow hardware UART port
/dev/ttyS0 to communicate via software with hardware UART port
socat -d -d pty,raw,echo=0,link=/dev/ttyS0 pty,raw,echo=0,link=/dev/ttyS1
Complete documentation is available here.
Let us know that this repository was useful to you by clicking the "star" in the upper right corner of the LibSerial Github home page!