.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LIBSERIAL" "1" "Jul 14, 2023" "1.0" "LibSerial"
.SH NAME
LibSerial \- LibSerial Documentation
.sp
Contents:
.SH FEATURE SUMMARY
.INDENT 0.0
.IP \(bu 2
Simplified serial port programming in C++ under POSIX operating systems.
.IP \(bu 2
Support for USB\-serial converters.
.IP \(bu 2
Access serial ports from scripting languages such as PHP, Python, Perl,
Ruby, and Java.
.UNINDENT
.SH DESCRIPTION
.sp
LibSerial was created to simplify serial port programming on POSIX
systems through a collection of object oriented C++ classes.
.sp
The \fISerialPort\fP class allows simplified access to serial port
settings and usage through a convenient set of methods.
This class is useful for embedded systems where a complete C++ STL
may not be available.
.sp
The \fISerialStream\fP class allows access to serial ports in the same manner as
standard C++ iostream objects.
.sp
Methods are provided for setting serial port parameters
such as baud rate, character size, flow control, etc.
.sp
Here is short example using libserial:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <libserial/SerialPort.h>
#include <libserial/SerialStream.h>

using namespace LibSerial;

int main()
{
   // Instantiate a Serial Port and a Serial Stream object.
   SerialPort serial_port;
   SerialStream serial_stream;

   // Open the hardware serial ports.
   serial_port.Open( \(dq/dev/ttyUSB0\(dq );
   serial_stream.Open( \(dq/dev/ttyUSB1\(dq );

   // Set the baud rates.
   serial_port.SetBaudRate( BaudRate::BAUD_115200 );
   serial_stream.SetBaudRate( BaudRate::BAUD_115200 );

   char write_byte_1 = \(aqa\(aq;
   char write_byte_2 = \(aqb\(aq;

   char read_byte_1 = \(aqA\(aq;
   char read_byte_2 = \(aqB\(aq;

   // Write a character.
   serial_port.Write(&write_byte_1, 1);
   serial_stream << write_byte_2;

   // Read a character.
   serial_port.Read(read_byte_1, 1);
   serial_stream >> read_byte_2;

   std::cout << \(dqserial_port read:   \(dq << read_byte_1 << std::endl;
   std::cout << \(dqserial_stream read: \(dq << read_byte_2 << std::endl;

   // Close the Serial Port and Serial Stream.
   serial_port.Close();
   serial_stream.Close();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition to the C++ programming languge, LibSerial releases after version
0.6.0 also provide bindings to several scripting languages such as Python,
Perl, PHP, Java, and Ruby. This provides developers a wide range languages to
select when writing applications that need access to serial ports on POSIX
compatible operating systems. LibSerial has received the most extensive testing
on (Debian) Linux operating systems.
.SH DOWNLOAD
.sp
The latest version of LibSerial is 1.0.0. You can find the source code
for LibSerial\-1.0.0 \fI\%here\fP\&.
Older versions of LibSerial may also be found at the above site.
.SH INSTALL
.sp
To install LibSerial the current release package on many Linux distributions you may simply use the package manager associated with your distribution:
.sp
For Debian distrbutions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt install libserial\-dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For Arch Linux distributions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo pacman \-S libserial\-dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install LibSerial from source, first clone the repository at \fI\%https://github.com/crayzeewulf/libserial\fP
.sp
Using https:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone https://github.com/crayzeewulf/libserial.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using ssh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone git@github.com:crayzeewulf/libserial.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Next, using make, execute the following commands from your libserial directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make \-F Makefile.dist
\&./configure
make
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install the build to your /usr/local/ directory your may simply:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo make install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install to another directory, simply use the \fIprefix\fP argument in the configure step above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./configure \-\-prefix=<DIRECTORY_NAME>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The code is also easily built using \fICMake\fP via a bash script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./compile.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install, change directories to the build directory and proceed as with make:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd build/
sudo make install
.ft P
.fi
.UNINDENT
.UNINDENT
.SH TUTORIAL
.SS Opening a Serial Port I/O Stream
.sp
A serial port instance, SerialPort, or an I/O stream instance,
SerialStream, can be created and opened by providing the name of the
serial port device to the constructor:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <SerialPort.h>
#include <SerialStream.h>

using namespace LibSerial ;

// Create and open the serial port for communication.
SerialPort   my_serial_port( \(dq/dev/ttyS0\(dq );
SerialStream my_serial_stream( \(dq/dev/ttyUSB0\(dq ) ;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In certain applications, the name of the serial port device may not be known
when the SerialStream instance is created. In such cases, the same effect as
above can be achieved as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Create a object instance.
SerialPort   my_serial_port;
SerialStream my_serial_stream;

// Obtain the serial port name from user input.
std::cout << \(dqPlease enter the name of the serial device, (e.g. /dev/ttyUSB0): \(dq << std::flush;
std::string serial_port_name;
std::cin >> serial_port_name;

// Open the serial port for communication.
my_serial_port.Open( serial_port_name );
my_serial_stream.Open( serial_port_name );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting the Baud Rate
.sp
The baud rate for the SerialStream can be set using the
SerialStream::SetBaudRate() member function.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Set the desired baud rate using a SetBaudRate() method call.
// Available baud rate values are defined in SerialStreamConstants.h.

my_serial_port.SetBaudRate( BAUD_115200 );
my_serial_stream.SetBaudRate( BAUD_115200 );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting the Character Size
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Set the desired character size using a SetCharacterSize() method call.
// Available character size values are defined in SerialStreamConstants.h.
my_serial_port.SetCharacterSize( CHAR_SIZE_8 );
my_serial_stream.SetCharacterSize( CHAR_SIZE_8 );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting the Flow\-Control Type
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Set the desired flow control type using a SetFlowControl() method call.
// Available flow control types are defined in SerialStreamConstants.h.
my_serial_port.SetFlowControl( FLOW_CONTROL_HARD );
my_serial_stream.SetFlowControl( FLOW_CONTROL_HARD );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting the Parity Type
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Set the desired parity type using a SetParity() method call.
// Available parity types are defined in SerialStreamConstants.h.
my_serial_port.SetParity( PARITY_ODD );
my_serial_stream.SetParity( PARITY_ODD );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting the Number of Stop Bits
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Set the number of stop bits using a SetNumOfStopBits() method call.
// Available stop bit values are defined in SerialStreamConstants.h.
my_serial_port.SetNumOfStopBits( STOP_BITS_1 ) ;
my_serial_stream.SetNumOfStopBits( STOP_BITS_1 ) ;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reading Characters
.sp
Characters can be read from serial port instances using Read(), ReadByte(),
and Readline() methods. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Read one character from the serial port within the timeout allowed.
int timeout_ms = 25; // timeout value in milliseconds
char next_char;      // variable to store the read result

my_serial_port.ReadByte( next_char, timeout_ms );
my_serial_stream.read( next_char );
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Characters can be read from serial streams using standard iostream operators. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Read one character from the serial port.
char next_char;
my_serial_stream >> next_char;

// You can also read other types of values from the serial port in a similar fashion.
int data_size;
my_serial_stream >> data_size;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other methods of standard C++ iostream objects could be used as well.
For example, one can read characters from the serial stream using the get() method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Read one byte from the serial port.
char next_byte;
my_serial_stream.get( next_byte );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Writing Characters
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Write a single character to the serial port.
my_serial_port.WriteByte( \(aqU\(aq );
my_serial_stream << \(aqU\(aq ;

// You can easily write strings.
std::string my_string = \(dqHello, Serial Port.\(dq

my_serial_port.Write( my_string );
my_serial_stream << my_string << std::endl ;

// And, with serial stream objects, you can easily write any type
// of object that is supported by a \(dq<<\(dq operator.
double radius = 2.0 ;
double area = M_PI * 2.0 * 2.0 ;

my_serial_stream << area << std::endl ;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reading Blocks of Data
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Read a whole array of data from the serial port.
const int BUFFER_SIZE = 256;
char input_buffer[BUFFER_SIZE];

my_serial_port.Read( input_buffer, BUFFER_SIZE );
my_serial_stream.read( input_buffer, BUFFER_SIZE );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Writing Blocks of Data
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Write an array of data from the serial port.
const int BUFFER_SIZE = 256;
char output_buffer[BUFFER_SIZE];

for( int i=0; i<BUFFER_SIZE; ++i )
{
    output_buffer[i] = i;
}

my_serial_port.Write( output_buffer, BUFFER_SIZE );
my_serial_stream.write( output_buffer, BUFFER_SIZE );
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Closing the Serial Port
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_serial_port.Close();
my_serial_stream.Close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SH API DOCUMENTATION
.sp
The API documentation generated by doxygen is available \fI\%here\fP\&.
.sp
To generate a new set of docs using Sphinx, simply run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sphinx\-build \-b html docs/user_manual/ docs/html/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Sphinx output will be located in the \fI/libserial/docs/html/\fP directory.
.sp
To generate a new set of doxygen documentation, you can run the compile.sh script or simply invoke doxygen directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
doxygen doxygen.conf.in
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The doxygen output will be located in the \fI/libserial/build/docs/html/\fP directory.
.SH DESIGN DOCUMENTATION
.SS LibSerial\(aqs Coding standards
.sp
Try to utilize these guidelines if you are contributing the LibSerial as a
developer.  Although we attempt to maintain these standards wherever practical,
on occasion you might still discover a few deviations.
.sp
Please familiarize yourselves with \fI\%C++ Core Guidelines\fP and try to
follow these guidelines.
.sp
LibSerial uses ISO standard C++ based on the C++14 standard.
.sp
Use Doxygen style comments (with @ commands) for every:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Class
.IP \(bu 2
Data Member
.IP \(bu 2
Function
.INDENT 2.0
.IP \(bu 2
@brief command for every function
.IP \(bu 2
@param command (if not void) for every parameter
.IP \(bu 2
@return command (if not void)
.UNINDENT
.IP \(bu 2
File
.INDENT 2.0
.IP \(bu 2
@file command, (except @example files)
.IP \(bu 2
@copyright command
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Allman (BSD) indentation style
.sp
Classes/Namespace/Structure/Enumeration names: CamelCase
Class methods: CamelCase
Class members: mCamelCase
.sp
Arguments to methods/functions: camelCase (lower case first word)
.SS Naming Convention
.sp
Use CamelCase for Files, Classes, Namespace, Structures, Enumerations, Functions, Procedures, and Member Variables.
.sp
Filenames are the name of the class or namespace within \-\- one class per file.
.sp
Classes, Namespaces, Structures, Enumerations, and Functions start with a capitalized letter and are nouns: (e.g. SerialPort, SerialStream, etc.).
Inhertied functions may be exceptions.
.sp
Function names are a description of the return value, and Procedure names are a strong verb followed by an object. (See Code Complete 2 §7.6 for the difference between a function and a procedure verb.)
.sp
Function arguments start with a lowercase letter and are nouns; (e.g. numberOfBytes, etc.)
.sp
Member Variables start with a lowercase letter \(dqm\(dq and are nouns; (e.g. mFileDescriptor, etc.).
.sp
Use underscores for non\-member functions and local variables, lower case with an underscore to separate words; (e.g. lower_case, short_names).
.sp
Constants and Globals are named identically to variables.
.sp
Do not use abbreviations and be as precise and descriptive with naming as possible.
.SS Indentation
.sp
Indentation shall be 4 space characters, not tabs.
.sp
Braces shall begin and end on the indentation level.
.sp
Namespaces are NOT indented.
.sp
Case statements are NOT indented.
.sp
Class visibility statements are NOT indented (public, protected, private).
.sp
One statement per line \-\- this includes variable declarations.
.sp
Do not put short if() ...; statements on one line.
.sp
If the constructor initializers don\(aqt fit on a single line, put constructor initializer list items one per line, starting with the comma and aligned with the colon separator.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Class::Class()
    : var1(1)
    , var2(2)
    , var3(3)
{
\&...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The purpose of this indentation policy, which can feel \(dqincorrect\(dq at times is to ensure that changes are isolated to the minimum number of lines.  Our tools, (compilers, editors, diff viewers, and source code repository), all operate on a line\-by\-line basis.  When someone makes a change that affects a portion anywhere in the line, the tools consider the entire line changed.  This can lead to nasty issues like complex merge conflicts, or, worse, obscure the developer activity.
.SS Include Headers
.sp
A good practice is to include headers in the order most local to least local and alphabetize your lists to avoid duplications. The purpose for this is to ensure that a proper dependency chain is maintained. As the project grows larger, these compilation failures sometimes can be difficult to identify and resolve.
.sp
This means that header files have includes alphabetized in the order:
.INDENT 0.0
.IP \(bu 2
project includes
.IP \(bu 2
project dependency includes
.IP \(bu 2
system includes
.UNINDENT
.sp
Source files have the includes in the order:
.INDENT 0.0
.IP \(bu 2
definition includes
.IP \(bu 2
project includes
.IP \(bu 2
project dependency includes
.IP \(bu 2
system includes
.UNINDENT
.SH LINKS
.INDENT 0.0
.INDENT 3.5
\fI\%LibSerial\-1.0.0rc1\fP
.sp
\fI\%Documentation\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%Index\fP
.IP \(bu 2
\fI\%Module Index\fP
.IP \(bu 2
\fI\%Search Page\fP
.UNINDENT
.SH AUTHOR
LibSerial Development Team
.SH COPYRIGHT
2004-2023, LibSerial Development Team
.\" Generated by docutils manpage writer.
.