Merge pull request #97 from mcsauder/c++14

Updated SerialPort Read() methods

Author: crayzeewulf

README.md

@@ -1,12 +1,22 @@
 # Libserial
 
 ----
-LibSerial provides a convenient, object oriented approach to accessing serial ports on POSIX systems.
+Thanks for checking out LibSerial!  LibSerial provides a convenient, object oriented approach to accessing serial ports on POSIX systems.
 
-You will need a recent g++ release, (anything after gcc-3.2 should work), to compile libserial, and you will also need to install Google Test (gtest) and the boost unit test library.  For Debian users:
+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
+```
+
+Otherwise, 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), the python sip library, the boost unit test library, and Google Test (gtest).  For Debian users:
 
 ```
-sudo apt install libgtest-dev libboost-dev
+sudo update
+sudo apt install build-essential libgtest-dev libboost-dev python-sip-dev
 ```
 ----
 If you get the source code from github and would like to install the library, you will need to generate the configure script first:
@@ -16,16 +26,26 @@ make -f Makefile.dist
 ```
 
 ----
-You can skip this step if you are using a release package (which already contains the `configure` script). Once you have the `configure` script, run the following commands:
+Then run `configure`:
 
 ```
 ./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:
+```
+./configure --prefix=/usr/include/
+```
+
+Once you have the `configure` script, you can build the library with `make` and install with `make install`:
+
+```
 make
-make install
+sudo make install
 ```
 
 ----
-If you are a developer interested in utilizing the unit tests, ensure serial port names are appropriate for your hardware configuration in the UnitTests.cpp file:
+If you are interested in running the unit tests, ensure serial port names are appropriate for your hardware configuration in the UnitTests.cpp file:
 
 ```
 #define TEST_SERIAL_PORT_1 "/dev/ttyUSB0"
@@ -54,4 +74,4 @@ Alternatively, unit test executables built using the compile script can be run f
 Complete documentation is available [here](http://libserial.readthedocs.io/en/latest/index.html).
 
 ----
-(You can let people know that this Repository was useful to you by clicking the "Star" in the upper right of the repository home page!)
+(You can let people know that this Repository was useful to you by clicking the "star" in the upper right of the repository home page!)

compile.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 mkdir -p build
 cd build
 cmake ..

examples/main_page_example.cpp

@@ -28,13 +28,15 @@ int main()
    char read_byte_2 = 'B';
 
    // Write a character.
-   serial_port.Write(&write_byte_1, 1);
+   serial_port.WriteByte(write_byte_1);
    serial_stream << write_byte_2;
 
+   size_t timeout_milliseconds = 5;
+
    try
    {
       // Read a character.
-      serial_port.Read(read_byte_1, 1);
+      serial_port.ReadByte(read_byte_1, timeout_milliseconds);
       serial_stream >> read_byte_2;
    }
    catch (ReadTimeout)

examples/serial_port_read.cpp

@@ -4,9 +4,10 @@
 
 #include <SerialPort.h>
 
+#include <cstring>
+#include <cstdlib>
 #include <iostream>
 #include <unistd.h>
-#include <cstdlib>
 
 using namespace LibSerial;
 
@@ -44,32 +45,46 @@ int main()
     }
 
     // Timeout value in milliseconds to wait for data being read.
-    size_t ms_timeout = 25;
+    size_t ms_timeout = 250;
 
-    // Variable to store data coming from the serial port.
+    // Char variable to store data coming from the serial port.
     char data_byte;
 
-    // Keep reading data from serial port and print it to the screen.
-    while(serial_port.IsDataAvailable()) 
+    // Read one byte from the serial port and print it to the terminal.
+    try
     {
-        try
-        {
-            // Read a single byte of data from the serial port.
-            serial_port.ReadByte(data_byte, ms_timeout);
+        // Read a single byte of data from the serial port.
+        serial_port.ReadByte(data_byte, ms_timeout);
 
-            // Show the user what is being read from the serial port.
-            std::cout << data_byte;
-        }
-        catch (ReadTimeout)
+        // Show the user what is being read from the serial port.
+        std::cout << data_byte << std::flush;
+    }
+    catch (ReadTimeout)
+    {
+        std::cerr << "\nThe ReadByte() call has timed out." << std::endl;
+    }
+
+    // Wait a brief period for more data to arrive.
+    usleep(1000);
+
+    DataBuffer read_buffer;
+
+    try
+    {
+        // Read as many bytes as are available during the timeout period.
+        serial_port.Read(read_buffer, 0, ms_timeout);
+    }
+    catch (ReadTimeout)
+    {
+        for (size_t i = 0; i < read_buffer.size(); i++)
         {
-            std::cerr << "The ReadByte() call has timed out." << std::endl;
+            std::cout << read_buffer.at(i) << std::flush;
         }
 
-        // Wait a brief period for more data to arrive.
-        usleep(1000);
+        std::cerr << "The Read() call timed out waiting for additional data." << std::endl;
     }
 
     // Successful program completion.
-    std::cout << "Done." << std::endl;
+    std::cout << "The example program successfully completed!" << std::endl;
     return EXIT_SUCCESS;
 }

examples/serial_port_read_write.cpp

@@ -61,8 +61,11 @@ int main()
     char read_byte_2  = ' ';
 
     // Variables to store outgoing and incoming data.
-    std::string write_string_1 = "\"Do what you can, with what you have, where you are.\" - Theodore Roosevelt";
-    std::string write_string_2 = "\"Simplicity is prerequisite for reliability.\" - Edsger W. Dijkstra";
+    std::string write_string_1 =
+        "\"Do what you can, with what you have, where you are.\" - Theodore Roosevelt";
+    
+    std::string write_string_2 =
+        "\"Simplicity is prerequisite for reliability.\" - Edsger W. Dijkstra";
 
     std::string read_string_1 = "";
     std::string read_string_2 = "";
@@ -75,6 +78,10 @@ int main()
     serial_port_1.WriteByte(write_byte_1);
     serial_port_2.WriteByte(write_byte_2);
 
+    // Wait until the data has actually been transmitted.
+    serial_port_1.DrainWriteBuffer();
+    serial_port_2.DrainWriteBuffer();
+
     // Specify a read timeout value in milliseconds.
     size_t timeout_milliseconds = 25;
 
@@ -106,6 +113,10 @@ int main()
     serial_port_1.Write(write_string_1);
     serial_port_2.Write(write_string_2);
 
+    // Wait until the data has actually been transmitted.
+    serial_port_1.DrainWriteBuffer();
+    serial_port_2.DrainWriteBuffer();
+
     try
     {
         // Read the appropriate number of bytes from each serial port.
@@ -130,9 +141,13 @@ int main()
     std::string user_input;
     user_input.clear();
 
+    // Print to the terminal what will take place next.
+    std::cout << "Using Write() and ReadLine() to write a string and "
+              << "read a line of data:" << std::endl << std::endl;
+
     // Prompt the user for input.
-    std::cout << "Type something you would like to send over serial,"
-              << " (enter \"Q\" or \"q\" to quit): " << std::flush;
+    std::cout << "Enter something you would like to send over "
+              << "serial, (enter \"Q\" or \"q\" to quit): " << std::flush;
 
     while(true)
     {
@@ -145,10 +160,6 @@ int main()
             break;
         }
 
-        // Print to the terminal what will take place next.
-        std::cout << "Using Write() and ReadLine() to write a string and "
-                  << "read a line of data:" << std::endl;
-
         // Write the user input to the serial port.
         serial_port_1.Write(user_input + "\n");
 
@@ -164,6 +175,7 @@ int main()
     serial_port_1.Close();
     serial_port_2.Close();
 
+    // Successful program completion.
     std::cout << "The example program successfully completed!" << std::endl;
     return EXIT_SUCCESS;
 }

examples/serial_port_write.cpp

@@ -74,11 +74,14 @@ int main(int argc, char** argv)
         // Write the data to the serial port.
         serial_port.WriteByte(data_byte);
 
+        // Wait until the data has actually been transmitted.
+        serial_port.DrainWriteBuffer();
+
         // Print to the terminal what is being written to the serial port.
         std::cout << data_byte;
     }
 
     // Successful program completion.
-    std::cout << std::endl << "Done." << std::endl;
+    std::cout << "The example program successfully completed!" << std::endl;
     return EXIT_SUCCESS;
 }

examples/serial_stream_read_write.cpp

@@ -69,6 +69,10 @@ int main()
     serial_stream_1.write(write_string_1.c_str(), write_string_1.size());
     serial_stream_2.write(write_string_2.c_str(), write_string_2.size());
 
+    // Wait until the data has actually been transmitted.
+    serial_stream_1.DrainWriteBuffer();
+    serial_stream_2.DrainWriteBuffer();
+
     // Char arrays to store incoming data.
     char* read_array_1 = new char[write_string_2.size()];
     char* read_array_2 = new char[write_string_1.size()];
@@ -94,6 +98,10 @@ int main()
     serial_stream_1 << write_string_1 << std::endl;
     serial_stream_2 << write_string_2 << std::endl;
 
+    // Wait until the data has actually been transmitted.
+    serial_stream_1.DrainWriteBuffer();
+    serial_stream_2.DrainWriteBuffer();
+
     // Read a line at each serial port.
     std::getline(serial_stream_1, read_string_1);
     std::getline(serial_stream_2, read_string_2);
@@ -147,6 +155,7 @@ int main()
     serial_stream_1.Close();
     serial_stream_2.Close();
 
+    // Successful program completion.
     std::cout << "The example program successfully completed!" << std::endl;
     return EXIT_SUCCESS;
 }

examples/serial_stream_write.cpp

@@ -74,11 +74,14 @@ int main(int argc, char** argv)
         // Write the data to the serial port.
         serial_stream.write(&data_byte, 1);
 
+        // Wait until the data has actually been transmitted.
+        serial_stream.DrainWriteBuffer();
+
         // Print to the terminal what is being written to the serial port.
         std::cout << data_byte;
     }
 
     // Successful program completion.
-    std::cout << std::endl << "Done." << std::endl;
+    std::cout << "The example program successfully completed!" << std::endl;
     return EXIT_SUCCESS;
 }

sip/SerialPort.sip

@@ -106,20 +106,10 @@ public:
     int
     GetFileDescriptor();
 
+    // NOTE: There is not a Python equivalent to std::vector.
     // std::vector<std::string>
     // GetAvailableSerialPorts();
 
-    // NOTE: Python3 provides a mechanism for method overloading, however Python2 does not.
-    // void
-    // Read(char&              charBuffer,
-    //      const unsigned int numberOfBytes = 0,
-    //      const unsigned int msTimeout  = 0);
-
-    void
-    Read(unsigned char&     charBuffer,
-         const unsigned int numberOfBytes = 0,
-         const unsigned int msTimeout  = 0);
-
     void
     Read(LibSerial::DataBuffer& dataBuffer,
          const unsigned int     numOfBytes = 0,
@@ -144,27 +134,18 @@ public:
              const char         lineTerminator = 10, // Sip does not like '\n'
              const unsigned int msTimeout = 0);
 
-    // NOTE: Python3 provides a mechanism for method overloading, however Python2 does not.
-    // void
-    // Write(const char*        charBuffer,
-    //       const unsigned int numberOfBytes);
-    
-    void
-    Write(const unsigned char* charBuffer,
-          const unsigned int   numberOfBytes);
-    
     void
     Write(const LibSerial::DataBuffer& dataBuffer);
 
     void
     Write(const std::string& dataString);
 
+    void
+    WriteByte(const char charbuffer);
+
     // NOTE: Python3 provides a mechanism for method overloading, however Python2 does not.
     // void
-    // WriteByte(const char charbuffer);
-
-    void
-    WriteByte(const unsigned char charbuffer);
+    // WriteByte(const unsigned char charbuffer);
 
 private:
     SerialPort(const SerialPort& otherSerialPort);