1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
# 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:
```sh
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](https://github.com/crayzeewulf/libserial#developers). 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`](https://github.com/crayzeewulf/libserial/tree/master/examples) directory.
A self-contained example project demonstrating the use of CMake and GNU Autotools (make) can be found in [`examples/example_project`](https://github.com/crayzeewulf/libserial/tree/master/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:
```sh
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:
```sh
./compile.sh
```
To install the library:
```sh
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:
```sh
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:
```sh
./gtest.sh
```
To generate the configure script:
```sh
make -f Makefile.dist
```
To execute the `configure` script, first create a build directory, then run the script from the build directory as follows:
```sh
../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:
```sh
./configure --prefix=/usr/
```
Once you have executed the `configure` script, you can build the library with `make` and install with `make install`:
```sh
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:
```cpp
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:
```sh
./compile
```
```sh
./build/bin/UnitTests
```
```sh
./build/bin/SerialPortReadWriteExample
```
Unit test executables built using make can be run from the `build` directory in the following manner:
```sh
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):
```sh
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`:
```sh
socat -d -d pty,raw,echo=0,link=/dev/ttyS0 pty,raw,echo=0,link=/dev/ttyS1
```
## Documentation
Complete documentation is available [here](http://libserial.readthedocs.io/en/latest/index.html).
> 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!
|
