LIBSERIAL(1)

🦋 LibSerial, aka LIBSERIAL(1) 🦋

✨ NAME ✨

LibSerial - LibSerial Documentation

Contents: 📚

---

🌈 FEATURE SUMMARY 🌈

• Simplified serial port programming in C++ 💅 under POSIX operating systems.
• Support for USB-serial converters 🔌
• Access serial ports from scripting languages like PHP, Python, Perl, Ruby, and Java 🐍💜

---

💖 DESCRIPTION 💖

Okay so, LibSerial was created to simplify serial port programming on POSIX systems through a collection of object oriented C++ classes 🎀.

The SerialPort class gives you simplified access to serial port settings and usage through a convenient set of methods 💅. It's giving embedded systems energy, since it's super useful where a complete C++ STL may not be available 🧚.

The SerialStream class lets you access serial ports the same way you'd use standard C++ iostream objects 🌊.

Methods are provided for setting serial port parameters such as baud rate, character size, flow control, etc. ⚙️

Here is a short example using libserial 👇

#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( "/dev/ttyUSB0" );
   serial_stream.Open( "/dev/ttyUSB1" );

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

   char write_byte_1 = 'a';
   char write_byte_2 = 'b';

   char read_byte_1 = 'A';
   char read_byte_2 = 'B';

   // 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 << "serial_port read:   " << read_byte_1 << std::endl;
   std::cout << "serial_stream read: " << read_byte_2 << std::endl;

   // Close the Serial Port and Serial Stream.
   serial_port.Close();
   serial_stream.Close();
}

Besides C++, LibSerial releases after version 0.6.0 also come with bindings for scripting languages like Python, Perl, PHP, Java, and Ruby 🐍💜. Developers get a whole buffet of languages to pick from when building apps that need serial port access on POSIX compatible operating systems 🍓. LibSerial has been tested the most on (Debian) Linux operating systems 🐧.

---

🎀 DOWNLOAD 🎀

The latest version is 1.0.0 🔥. You can grab the source code for LibSerial-1.0.0 from https://github.com/crayzeewulf/libserial. Older versions are also hanging out at that same site 🕰️.

---

🌸 INSTALL 🌸

For most Linux distributions, the easiest move is to use your distro's package manager 📦. Slay.

Debian besties 🌀:

sudo apt install libserial-dev

Arch besties 🐧:

sudo pacman -S libserial-dev

Want to install from source instead? First, clone the repository at https://github.com/crayzeewulf/libserial 🫶.

Using https 🔒:

git clone https://github.com/crayzeewulf/libserial.git

Using ssh 🔑:

git clone git@github.com:crayzeewulf/libserial.git

Next, using make, run these commands from your libserial directory:

make -F Makefile.dist
./configure
make

To install the build into /usr/local/, you can simply run:

sudo make install

Want it somewhere else? Just pass the prefix argument during the configure step above:

./configure --prefix=<DIRECTORY_NAME>

The code is also easily built with CMake using a bash script, so no stress 💀:

./compile.sh

To install, change into the build directory and carry on like you would with make:

cd build/
sudo make install

Part 1 of 2 is a wrap 🎀. TUTORIAL and API DOCUMENTATION are up next!

💖 DESIGN DOCUMENTATION 💖

🎀 LibSerial's Coding standards 🎀

okay so bestie, if you're gonna contribute to LibSerial as a developer, you NEED to follow these vibes 💅 we try to keep them everywhere we can, but ngl you might still spot a few deviations here and there 🙈

please go get familiar with the C++ Core Guidelines <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines> and try to follow those too 🫶

LibSerial uses ISO standard C++ based on the C++14 standard ✨

Use Doxygen style comments (with @ commands) for every:

• Class 🦋
• Data Member 🦋
• Function 🦋
  • @brief command for every function 💜
  • @param command (if not void) for every parameter 💜
  • @return command (if not void) 💜
• File 🦋
  • @file command, (except @example files) 💜
  • @copyright command 💜

Allman (BSD) indentation style 👑

Classes/Namespace/Structure/Enumeration names: CamelCase Class methods: CamelCase Class members: mCamelCase Arguments to methods/functions: camelCase (lower case first word) 🌸

🦋 Naming Convention 🦋

Use CamelCase for Files, Classes, Namespace, Structures, Enumerations, Functions, Procedures, and Member Variables, bestie 💅

Filenames are the name of the class or namespace within. One class per file, no exceptions 🎀

Classes, Namespaces, Structures, Enumerations, and Functions start with a capitalized letter and are nouns (e.g. SerialPort, SerialStream, etc.) ✨ Inhertied functions may be exceptions 🙈

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.) 🧚

Function arguments start with a lowercase letter and are nouns (e.g. numberOfBytes, etc.) 🌈

Member Variables start with a lowercase letter m and are nouns (e.g. mFileDescriptor, etc.) 💜

Use underscores for non-member functions and local variables, lower case with an underscore to separate words (e.g. lower_case, short_names) 🍓

Constants and Globals are named identically to variables 🔥

Do not use abbreviations and be as precise and descriptive with naming as possible. Main character energy only, no shortcuts 👑

🌸 Indentation 🌸

Indentation shall be 4 space characters, not tabs. Tabs are NOT it 💀

Braces shall begin and end on the indentation level 🦋

Namespaces are NOT indented 🎀

Case statements are NOT indented 🌈

Class visibility statements are NOT indented (public, protected, private) 💅

One statement per line, and that includes variable declarations 🫶

Do not put short if() ...; statements on one line 😭

If the constructor initializers don't 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:

Class::Class()
    : var1(1)
    , var2(2)
    , var3(3)
{
...
}

The purpose of this indentation policy, which can feel "incorrect" 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 😭🔥

🧚 Include Headers 🧚

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 🙈

This means that header files have includes alphabetized in the order:

• project includes ✨
• project dependency includes ✨
• system includes ✨

Source files have the includes in the order:

• definition includes 💖
• project includes 💖
• project dependency includes 💖
• system includes 💖

🌈 LINKS 🌈

LibSerial-1.0.0rc1 <https://github.com/crayzeewulf/libserial>

Documentation <http://libserial.readthedocs.io/en/latest/index.html>

• Index <> 🦋
• Module Index <> 🦋
• Search Page <> 🦋

👑 Author 👑

LibSerial Development Team 🫶

💜 Copyright 💜

2004-2018, LibSerial Development Team ✨

---

bestie that's the whole thing 🎀 the page was written by the LibSerial Development Team and it's © 2004-2018 LibSerial Development Team, version 1.0, dated Feb 04, 2026 🦋 go forth and write some clean, lowkey iconic C++ 💅✨🌸