Peter M. Groen / CppLinuxSerial

Commit 0265fb78af7339b3842dcc237d5faeeda1aac65d

Authored by Geoffrey Hunter
Committed by GitHub
2 parents 77b01015 96cbf20d

Merge pull request #4 from gbmhunter/develop 

v2.0.2
Inline Side-by-side
Showing 12 changed files with 288 additions and 74 deletions
.gitignore
  View file @0265fb7
1 1 build/
2 2 cmake-build-debug/
3 3 .idea/workspace.xml
4   -.vscode/c_cpp_properties.json
5 4 \ No newline at end of file
  5 +.vscode/
  6 +
  7 +# Sphinx build dir
  8 +docs/_build/
6 9 \ No newline at end of file
... ...
CHANGELOG.md
  View file @0265fb7
1 1 # Changelog
  2 +
2 3 All notable changes to this project will be documented in this file.
3 4  
4 5 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
... ... @@ -6,6 +7,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
6 7  
7 8 ## [Unreleased]
8 9  
  10 +## [v2.0.2] - 2020-07-07
  11 +
  12 +### Added
  13 +- Sphinx documentation.
  14 +- Unit tests for testing `SetTimeout()`.
  15 +
  16 +### Fixed
  17 +- Serial port state is set to `CLOSED` on initialization.
  18 +- Fixed build commands in README.
  19 +
9 20 ## [v2.0.1] - 2017-11-27
10 21  
11 22 ### Fixed
... ...
README.md 0 → 100644
  View file @0265fb7
  1 +# CppLinuxSerial
  2 +
  3 +Serial port library written in C++
  4 +
  5 +[![Build Status](https://travis-ci.org/gbmhunter/CppLinuxSerial.svg?branch=master)](https://travis-ci.org/gbmhunter/CppLinuxSerial)
  6 +
  7 +## Description
  8 +
  9 +Library for communicating with COM ports on a Linux system.
  10 +
  11 +Uses fstream to the file I/O.
  12 +
  13 +## Installation
  14 +
  15 +### Linux, MacOS, Windows
  16 +
  17 +1. Make sure you have `cmake` installed.
  18 +
  19 +1. Clone the git repo onto your local storage.
  20 +
  21 +1. Change into root repo directory:
  22 +
  23 + ```
  24 + $ cd CppLinuxSerial
  25 + ```
  26 +
  27 +1. Create a new build directory and change into it:
  28 +
  29 + ```bash
  30 + $ mkdir build
  31 + $ cd build
  32 + ```
  33 +
  34 +1. Run cmake on the parent directory to generate makefile:
  35 +
  36 + ```bash
  37 + $ cmake ..
  38 + ```
  39 +
  40 +1. Run make on the generated makefile to generate the static library `libCppLinuxSerial.a` and an unit test executable:
  41 +
  42 + ```bash
  43 + $ make
  44 + ```
  45 +
  46 +1. To install the headers on your system:
  47 +
  48 + ```bash
  49 + $ sudo make install
  50 + ```
  51 +
  52 +1. To run the unit tests (NOTE: because this uses virtual serial ports via `stty`, this only works on Linux!):
  53 +
  54 + ```bash
  55 + $ make run_unit_tests
  56 + ```
  57 +
  58 + If you get errors such as `Could not open device /dev/ttyS10. Is the device name correct and do you have read/write permission?" thrown in the test fixture's constructor.`, it is probably an issue with either creating the virtual serial ports or permissions to access them.
  59 +
  60 +
  61 +## Dependencies
  62 +
  63 +The following table lists all of the libraries dependencies.
  64 +
  65 +<table>
  66 + <thead>
  67 + <tr>
  68 + <td>Dependency</td>
  69 + <td>Comments</td>
  70 + </tr>
  71 + </thead>
  72 + <tbody>
  73 + <tr>
  74 + <td>C++14</td>
  75 + <td>C++14 used for strongly typed enums, `std::chrono` and literals.</td>
  76 + </tr>
  77 + <tr>
  78 + <td>stdio.h</td>
  79 + <td>snprintf()</td>
  80 + </tr>
  81 + <tr>
  82 + <td>stty</td>
  83 + <td>Used in unit tests to verify the serial port is configured correctly.</td>
  84 + </tr>
  85 + </tbody>
  86 +</table>
  87 +
  88 +## Issues
  89 +
  90 +See GitHub Issues.
  91 +
  92 +## FAQ
  93 +
  94 +1. My code stalls when calling functions like `SerialPort::Read()`. This is probably because the library is set up to do a blocking read, and not enough characters have been received to allow `SerialPort::Read()` to return. Use `SerialPort::SetNumCharsToWait()` to determine how many characters to wait for before returning (set to 0 for non-blocking mode).
  95 +
  96 +## Changelog
  97 +
  98 +See CHANGELOG.md.
0 99 \ No newline at end of file
... ...
README.rst deleted
View file @77b0101
1   -==============
2   -CppLinuxSerial
3   -==============
4   -
5   -----------------------------------
6   -Serial port library written in C++
7   -----------------------------------
8   -
9   -.. image:: https://travis-ci.org/gbmhunter/CppLinuxSerial.svg?branch=master
10   - :target: https://travis-ci.org/gbmhunter/CppLinuxSerial
11   -
12   -.. role:: bash(code)
13   - :language: bash
14   -
15   -Description
16   -===========
17   -
18   -Library for communicating with COM ports on a Linux system.
19   -
20   -Uses fstream to the file I/O.
21   -
22   -Installation
23   -============
24   -
25   -1. Clone the git repo onto your local storage.
26   -
27   -2. Run `make all` to compile and run unit tests. Do not worry about error messages being printed when unit tests are run, the unit tests are designed to specifically cause errors to test the response.
28   -
29   -3. To include serial-port-cpp into your embedded (or otherwise) firmware/software project, copy the repo into your project folder (or other suitable place), include the file "/api/SerialPortApi.hpp" from your C++ code, and make sure to compile all the files within "/src/".
30   -
31   -
32   -Dependencies
33   -============
34   -
35   -The following table lists all of the libraries dependencies.
36   -
37   -====================== ======================================================================
38   -Dependency Comments
39   -====================== ======================================================================
40   -C++14 C++14 used for strongly typed enums, std::chrono and literals.
41   -<stdio.h> snprintf()
42   -stty Used in unit tests to verify the serial port is configured correctly.
43   -====================== ======================================================================
44   -
45   -Issues
46   -======
47   -
48   -See GitHub Issues.
49   -
50   -Usage
51   -=====
52   -
53   -Nothing here yet...
54   -
55   -FAQ
56   -===
57   -
58   -1. My code stalls when calling functions like :code:`SerialPort::Read()`. This is probably because the library is set up to do a blocking read, and not enough characters have been received to allow :code:`SerialPort::Read()` to return. Use :code:`SerialPort::SetNumCharsToWait()` to determine how many characters to wait for before returning (set to 0 for non-blocking mode).
59   -
60   -
61   -Changelog
62   -=========
63   -
64   -See CHANGELOG.md.
65 0 \ No newline at end of file
docs/Makefile 0 → 100644
  View file @0265fb7
  1 +# Minimal makefile for Sphinx documentation
  2 +#
  3 +
  4 +# You can set these variables from the command line.
  5 +SPHINXOPTS =
  6 +SPHINXBUILD = sphinx-build
  7 +SOURCEDIR = .
  8 +BUILDDIR = _build
  9 +
  10 +# Put it first so that "make" without argument is like "make help".
  11 +help:
  12 + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
  13 +
  14 +.PHONY: help Makefile
  15 +
  16 +# Catch-all target: route all unknown targets to Sphinx using the new
  17 +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
  18 +%: Makefile
  19 + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
0 20 \ No newline at end of file
... ...
docs/conf.py 0 → 100644
  View file @0265fb7
  1 +# Configuration file for the Sphinx documentation builder.
  2 +#
  3 +# This file only contains a selection of the most common options. For a full
  4 +# list see the documentation:
  5 +# http://www.sphinx-doc.org/en/master/config
  6 +
  7 +# -- Path setup --------------------------------------------------------------
  8 +
  9 +# If extensions (or modules to document with autodoc) are in another directory,
  10 +# add these directories to sys.path here. If the directory is relative to the
  11 +# documentation root, use os.path.abspath to make it absolute, like shown here.
  12 +#
  13 +# import os
  14 +# import sys
  15 +# sys.path.insert(0, os.path.abspath('.'))
  16 +
  17 +
  18 +# -- Project information -----------------------------------------------------
  19 +
  20 +project = 'CppLinuxSerial'
  21 +copyright = '2019, Geoffrey Hunter'
  22 +author = 'Geoffrey Hunter'
  23 +
  24 +# The full version, including alpha/beta/rc tags
  25 +release = 'v1.0.0'
  26 +
  27 +
  28 +# -- General configuration ---------------------------------------------------
  29 +
  30 +# Add any Sphinx extension module names here, as strings. They can be
  31 +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  32 +# ones.
  33 +extensions = [
  34 +]
  35 +
  36 +# Add any paths that contain templates here, relative to this directory.
  37 +templates_path = ['_templates']
  38 +
  39 +# List of patterns, relative to source directory, that match files and
  40 +# directories to ignore when looking for source files.
  41 +# This pattern also affects html_static_path and html_extra_path.
  42 +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  43 +
  44 +
  45 +# -- Options for HTML output -------------------------------------------------
  46 +
  47 +# The theme to use for HTML and HTML Help pages. See the documentation for
  48 +# a list of builtin themes.
  49 +#
  50 +html_theme = 'alabaster'
  51 +
  52 +# Add any paths that contain custom static files (such as style sheets) here,
  53 +# relative to this directory. They are copied after the builtin static files,
  54 +# so a file named "default.css" will overwrite the builtin "default.css".
  55 +html_static_path = ['_static']
  56 +
  57 +# Assign master document so readthedocs is happy
  58 +master_doc = 'index'
... ...
docs/index.rst 0 → 100644
  View file @0265fb7
  1 +.. CppLinuxSerial documentation master file, created by
  2 + sphinx-quickstart on Wed May 29 22:11:17 2019.
  3 + You can adapt this file completely to your liking, but it should at least
  4 + contain the root `toctree` directive.
  5 +
  6 +Welcome to CppLinuxSerial's documentation!
  7 +==========================================
  8 +
  9 +.. toctree::
  10 + :maxdepth: 2
  11 + :caption: Contents:
  12 +
  13 +Building
  14 +========
  15 +
  16 +```
  17 +mkdir build
  18 +cd build/
  19 +cmake ..
  20 +make
  21 +```
  22 +
  23 +
  24 +Indices and tables
  25 +==================
  26 +
  27 +* :ref:`genindex`
  28 +* :ref:`modindex`
  29 +* :ref:`search`
... ...
docs/make.bat 0 → 100644
  View file @0265fb7
  1 +@ECHO OFF
  2 +
  3 +pushd %~dp0
  4 +
  5 +REM Command file for Sphinx documentation
  6 +
  7 +if "%SPHINXBUILD%" == "" (
  8 + set SPHINXBUILD=sphinx-build
  9 +)
  10 +set SOURCEDIR=.
  11 +set BUILDDIR=_build
  12 +
  13 +if "%1" == "" goto help
  14 +
  15 +%SPHINXBUILD% >NUL 2>NUL
  16 +if errorlevel 9009 (
  17 + echo.
  18 + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
  19 + echo.installed, then set the SPHINXBUILD environment variable to point
  20 + echo.to the full path of the 'sphinx-build' executable. Alternatively you
  21 + echo.may add the Sphinx directory to PATH.
  22 + echo.
  23 + echo.If you don't have Sphinx installed, grab it from
  24 + echo.http://sphinx-doc.org/
  25 + exit /b 1
  26 +)
  27 +
  28 +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
  29 +goto end
  30 +
  31 +:help
  32 +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
  33 +
  34 +:end
  35 +popd
... ...
include/CppLinuxSerial/SerialPort.hpp
  View file @0265fb7
1 1 ///
2 2 /// \file SerialPort.hpp
3   -/// \author Geoffrey Hunter <gbmhunter@gmail.com> ()
  3 +/// \author Geoffrey Hunter <gbmhunter@gmail.com> (www.mbedded.ninja)
4 4 /// \created 2014-01-07
5   -/// \last-modified 2017-11-23
  5 +/// \last-modified 2019-05-30
6 6 /// \brief The main serial port class.
7 7 /// \details
8 8 /// See README.rst in repo root dir for more info.
... ... @@ -19,6 +19,7 @@
19 19 #include <vector>
20 20  
21 21 // User headers
  22 +#include "Exception.hpp"
22 23  
23 24 namespace mn {
24 25 namespace CppLinuxSerial {
... ...
src/SerialPort.cpp
  View file @0265fb7
... ... @@ -31,6 +31,7 @@ namespace CppLinuxSerial {
31 31 baudRate_ = defaultBaudRate_;
32 32 readBufferSize_B_ = defaultReadBufferSize_B_;
33 33 readBuffer_.reserve(readBufferSize_B_);
  34 + state_ = State::CLOSED;
34 35 }
35 36  
36 37 SerialPort::SerialPort(const std::string& device, BaudRate baudRate) :
... ...
test/unit/BasicTests.cpp
  View file @0265fb7
... ... @@ -2,7 +2,7 @@
2 2 /// \file BasicTests.cpp
3 3 /// \author Geoffrey Hunter <gbmhunter@gmail.com> (www.mbedded.ninja)
4 4 /// \created 2017-11-24
5   -/// \last-modified 2017-11-24
  5 +/// \last-modified 2019-05-30
6 6 /// \brief Basic tests for the SerialPort class.
7 7 /// \details
8 8 /// See README.rst in repo root dir for more info.
... ... @@ -58,7 +58,6 @@ namespace {
58 58 ASSERT_EQ("Hello", readData);
59 59 }
60 60  
61   -
62 61 TEST_F(BasicTests, ReadWriteDiffBaudRates) {
63 62 SerialPort serialPort0(device0Name_, BaudRate::B_9600);
64 63 serialPort0.Open();
... ... @@ -74,4 +73,26 @@ namespace {
74 73 ASSERT_EQ("Hello", readData);
75 74 }
76 75  
  76 + TEST_F(BasicTests, SetTimeoutCorrectly) {
  77 + SerialPort serialPort0(device0Name_, BaudRate::B_57600);
  78 + serialPort0.SetTimeout(-1); // Infinite timeout
  79 + serialPort0.Open();
  80 +
  81 + SerialPort serialPort1(device1Name_, BaudRate::B_57600);
  82 + serialPort1.Open();
  83 +
  84 + serialPort0.Write("Hello");
  85 +
  86 + std::string readData;
  87 + serialPort1.Read(readData);
  88 +
  89 + ASSERT_EQ("Hello", readData);
  90 + }
  91 +
  92 + TEST_F(BasicTests, SetTimeoutIncorrectly) {
  93 + SerialPort serialPort0(device0Name_, BaudRate::B_57600);
  94 + serialPort0.Open();
  95 + EXPECT_THROW(serialPort0.SetTimeout(-1), mn::CppLinuxSerial::Exception);
  96 + }
  97 +
77 98 } // namespace
78 99 \ No newline at end of file
... ...
test/unit/TestUtil.hpp
  View file @0265fb7
... ... @@ -55,13 +55,15 @@ namespace mn {
55 55  
56 56 void CreateVirtualSerialPortPair() {
57 57 std::cout << "Creating virtual serial port pair..." << std::endl;
58   - std::system("nohup sudo socat -d -d pty,raw,echo=0,link=/dev/ttyS10 pty,raw,echo=0,link=/dev/ttyS11 &");
  58 + std::system((std::string("nohup sudo socat -d -d pty,raw,echo=0,link=")
  59 + + device0Name_ + " pty,raw,echo=0,link="
  60 + + device1Name_ + " &").c_str());
59 61  
60 62 // Hacky! Since socat is detached, we have no idea at what point it has created
61 63 // ttyS10 and ttyS11. Assume 1 second is long enough...
62 64 std::this_thread::sleep_for(1s);
63   - std::system("sudo chmod a+rw /dev/ttyS10");
64   - std::system("sudo chmod a+rw /dev/ttyS11");
  65 + std::system((std::string("sudo chmod a+rw ") + GetDevice0Name()).c_str());
  66 + std::system((std::string("sudo chmod a+rw ") + GetDevice1Name()).c_str());
65 67 }
66 68  
67 69 void CloseSerialPorts() {
... ... @@ -78,8 +80,8 @@ namespace mn {
78 80 return device1Name_;
79 81 }
80 82  
81   - std::string device0Name_ = "/dev/ttyS10";
82   - std::string device1Name_ = "/dev/ttyS11";
  83 + std::string device0Name_ = "/dev/ttyS31";
  84 + std::string device1Name_ = "/dev/ttyS32";
83 85  
84 86 protected:
85 87  
... ...