diff --git a/.gitignore b/.gitignore index 7028873..1fc2c47 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,7 @@ build/ cmake-build-debug/ .idea/workspace.xml -.vscode/c_cpp_properties.json \ No newline at end of file +.vscode/ + +# Sphinx build dir +docs/_build/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 4de23bc..9350a3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,5 @@ # Changelog + All notable changes to this project will be documented in this file. 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. ## [Unreleased] +## [v2.0.2] - 2020-07-07 + +### Added +- Sphinx documentation. +- Unit tests for testing `SetTimeout()`. + +### Fixed +- Serial port state is set to `CLOSED` on initialization. +- Fixed build commands in README. + ## [v2.0.1] - 2017-11-27 ### Fixed diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e50609 --- /dev/null +++ b/README.md @@ -0,0 +1,98 @@ +# CppLinuxSerial + +Serial port library written in C++ + +[![Build Status](https://travis-ci.org/gbmhunter/CppLinuxSerial.svg?branch=master)](https://travis-ci.org/gbmhunter/CppLinuxSerial) + +## Description + +Library for communicating with COM ports on a Linux system. + +Uses fstream to the file I/O. + +## Installation + +### Linux, MacOS, Windows + +1. Make sure you have `cmake` installed. + +1. Clone the git repo onto your local storage. + +1. Change into root repo directory: + + ``` + $ cd CppLinuxSerial + ``` + +1. Create a new build directory and change into it: + + ```bash + $ mkdir build + $ cd build + ``` + +1. Run cmake on the parent directory to generate makefile: + + ```bash + $ cmake .. + ``` + +1. Run make on the generated makefile to generate the static library `libCppLinuxSerial.a` and an unit test executable: + + ```bash + $ make + ``` + +1. To install the headers on your system: + + ```bash + $ sudo make install + ``` + +1. To run the unit tests (NOTE: because this uses virtual serial ports via `stty`, this only works on Linux!): + + ```bash + $ make run_unit_tests + ``` + + 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. + + +## Dependencies + +The following table lists all of the libraries dependencies. + + + + + + + + + + + + + + + + + + + + + + +
DependencyComments
C++14C++14 used for strongly typed enums, `std::chrono` and literals.
stdio.hsnprintf()
sttyUsed in unit tests to verify the serial port is configured correctly.
+ +## Issues + +See GitHub Issues. + +## FAQ + +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). + +## Changelog + +See CHANGELOG.md. \ No newline at end of file diff --git a/README.rst b/README.rst deleted file mode 100644 index f7792b8..0000000 --- a/README.rst +++ /dev/null @@ -1,64 +0,0 @@ -============== -CppLinuxSerial -============== - ----------------------------------- -Serial port library written in C++ ----------------------------------- - -.. image:: https://travis-ci.org/gbmhunter/CppLinuxSerial.svg?branch=master - :target: https://travis-ci.org/gbmhunter/CppLinuxSerial - -.. role:: bash(code) - :language: bash - -Description -=========== - -Library for communicating with COM ports on a Linux system. - -Uses fstream to the file I/O. - -Installation -============ - -1. Clone the git repo onto your local storage. - -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. - -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/". - - -Dependencies -============ - -The following table lists all of the libraries dependencies. - -====================== ====================================================================== -Dependency Comments -====================== ====================================================================== -C++14 C++14 used for strongly typed enums, std::chrono and literals. - snprintf() -stty Used in unit tests to verify the serial port is configured correctly. -====================== ====================================================================== - -Issues -====== - -See GitHub Issues. - -Usage -===== - -Nothing here yet... - -FAQ -=== - -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). - - -Changelog -========= - -See CHANGELOG.md. \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..298ea9e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..647d082 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,58 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'CppLinuxSerial' +copyright = '2019, Geoffrey Hunter' +author = 'Geoffrey Hunter' + +# The full version, including alpha/beta/rc tags +release = 'v1.0.0' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Assign master document so readthedocs is happy +master_doc = 'index' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..0005406 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,29 @@ +.. CppLinuxSerial documentation master file, created by + sphinx-quickstart on Wed May 29 22:11:17 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to CppLinuxSerial's documentation! +========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +Building +======== + +``` +mkdir build +cd build/ +cmake .. +make +``` + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..27f573b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/include/CppLinuxSerial/SerialPort.hpp b/include/CppLinuxSerial/SerialPort.hpp index b12565b..1ece112 100644 --- a/include/CppLinuxSerial/SerialPort.hpp +++ b/include/CppLinuxSerial/SerialPort.hpp @@ -1,8 +1,8 @@ /// /// \file SerialPort.hpp -/// \author Geoffrey Hunter () +/// \author Geoffrey Hunter (www.mbedded.ninja) /// \created 2014-01-07 -/// \last-modified 2017-11-23 +/// \last-modified 2019-05-30 /// \brief The main serial port class. /// \details /// See README.rst in repo root dir for more info. @@ -19,6 +19,7 @@ #include // User headers +#include "Exception.hpp" namespace mn { namespace CppLinuxSerial { diff --git a/src/SerialPort.cpp b/src/SerialPort.cpp index c80a831..9bf0aca 100644 --- a/src/SerialPort.cpp +++ b/src/SerialPort.cpp @@ -31,6 +31,7 @@ namespace CppLinuxSerial { baudRate_ = defaultBaudRate_; readBufferSize_B_ = defaultReadBufferSize_B_; readBuffer_.reserve(readBufferSize_B_); + state_ = State::CLOSED; } SerialPort::SerialPort(const std::string& device, BaudRate baudRate) : diff --git a/test/unit/BasicTests.cpp b/test/unit/BasicTests.cpp index b918c8e..69c8ea3 100644 --- a/test/unit/BasicTests.cpp +++ b/test/unit/BasicTests.cpp @@ -2,7 +2,7 @@ /// \file BasicTests.cpp /// \author Geoffrey Hunter (www.mbedded.ninja) /// \created 2017-11-24 -/// \last-modified 2017-11-24 +/// \last-modified 2019-05-30 /// \brief Basic tests for the SerialPort class. /// \details /// See README.rst in repo root dir for more info. @@ -58,7 +58,6 @@ namespace { ASSERT_EQ("Hello", readData); } - TEST_F(BasicTests, ReadWriteDiffBaudRates) { SerialPort serialPort0(device0Name_, BaudRate::B_9600); serialPort0.Open(); @@ -74,4 +73,26 @@ namespace { ASSERT_EQ("Hello", readData); } + TEST_F(BasicTests, SetTimeoutCorrectly) { + SerialPort serialPort0(device0Name_, BaudRate::B_57600); + serialPort0.SetTimeout(-1); // Infinite timeout + serialPort0.Open(); + + SerialPort serialPort1(device1Name_, BaudRate::B_57600); + serialPort1.Open(); + + serialPort0.Write("Hello"); + + std::string readData; + serialPort1.Read(readData); + + ASSERT_EQ("Hello", readData); + } + + TEST_F(BasicTests, SetTimeoutIncorrectly) { + SerialPort serialPort0(device0Name_, BaudRate::B_57600); + serialPort0.Open(); + EXPECT_THROW(serialPort0.SetTimeout(-1), mn::CppLinuxSerial::Exception); + } + } // namespace \ No newline at end of file diff --git a/test/unit/TestUtil.hpp b/test/unit/TestUtil.hpp index 1cf1a34..a00e8a1 100644 --- a/test/unit/TestUtil.hpp +++ b/test/unit/TestUtil.hpp @@ -55,13 +55,15 @@ namespace mn { void CreateVirtualSerialPortPair() { std::cout << "Creating virtual serial port pair..." << std::endl; - std::system("nohup sudo socat -d -d pty,raw,echo=0,link=/dev/ttyS10 pty,raw,echo=0,link=/dev/ttyS11 &"); + std::system((std::string("nohup sudo socat -d -d pty,raw,echo=0,link=") + + device0Name_ + " pty,raw,echo=0,link=" + + device1Name_ + " &").c_str()); // Hacky! Since socat is detached, we have no idea at what point it has created // ttyS10 and ttyS11. Assume 1 second is long enough... std::this_thread::sleep_for(1s); - std::system("sudo chmod a+rw /dev/ttyS10"); - std::system("sudo chmod a+rw /dev/ttyS11"); + std::system((std::string("sudo chmod a+rw ") + GetDevice0Name()).c_str()); + std::system((std::string("sudo chmod a+rw ") + GetDevice1Name()).c_str()); } void CloseSerialPorts() { @@ -78,8 +80,8 @@ namespace mn { return device1Name_; } - std::string device0Name_ = "/dev/ttyS10"; - std::string device1Name_ = "/dev/ttyS11"; + std::string device0Name_ = "/dev/ttyS31"; + std::string device1Name_ = "/dev/ttyS32"; protected: