Awesome
Libserial
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 examples
directory.
A self-contained example project demonstrating the use of CMake and GNU Autotools (make) can be found in examples/example_project
directory.
Developers
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:
Building Using CMake
If you are using CMake, to build the library you can simply run the compile.sh
script:
./compile.sh
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 ..
Building Using GNU Autotools
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.a
and libgtest_main.a
into your /usr/lib/
directory which you can accomplish by running the gtest.sh
convenience script:
./gtest.sh
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:
../configure
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:
./configure --prefix=/usr/
Once you have executed the configure
script, you can build the library with make
and install with make install
:
make
sudo make install
Example Code and Unit Tests
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 build
directory:
./compile
./build/bin/UnitTests
./build/bin/SerialPortReadWriteExample
Unit test executables built using make can be run from the build
directory in the following manner:
ctest -V .
Hardware and Software Considerations
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
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 /dev/ttyS1
:
socat -d -d pty,raw,echo=0,link=/dev/ttyS0 pty,raw,echo=0,link=/dev/ttyS1
Documentation
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!