Usage Guide

Basic Usage

The libserial library provides a simple C++ interface for serial port communication. Here’s how to get started:

Opening a Serial Port

#include <libserial/serial.hpp>

int main() {
    try {
        // Create a Serial object
        libserial::Serial serial;

        // Open the port
        serial.open("/dev/ttyUSB0");

        // Port is now ready for communication

    } catch (const libserial::SerialException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Configuring Serial Parameters

You can configure various serial port parameters:

#include <libserial/serial.hpp>

int main() {
    try {
        libserial::Serial serial;

        // Configure before opening
        serial.setBaudRate(libserial::BaudRate::BAUD_9600);
        serial.setDataLength(libserial::DataBits::SEVEN);
        serial.setParity(libserial::Parity::ENABLE);
        serial.setStopBits(libserial::StopBits::ONE);
        serial.setCanonicalMode(libserial::CanonicalMode::DISABLE);

        serial.open("/dev/ttyUSB0");

    } catch (const libserial::SerialException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Reading and Writing Data

Basic read/write operations:

#include <libserial/serial.hpp>
#include <iostream>
#include <string>

int main() {
    try {
        libserial::Serial serial;
        serial.open("/dev/ttyUSB0");

        // Write data
        auto message = std::make_shared<std::string>("Hello from libserial!");
        serial.write(message);

        // Read response
        auto buffer = std::make_shared<std::string>();
        size_t bytes_read = serial.read(buffer);

        serial.close();

    } catch (const libserial::SerialException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Advanced Usage

Timeout Configuration

Configure read timeouts to prevent blocking:

#include <libserial/serial.hpp>
#include <chrono>

int main() {
    try {
        libserial::Serial serial;
        serial.open("/dev/ttyUSB0");
        // Set read timeout to 5 seconds
        serial.setReadTimeout(std::chrono::milliseconds(5000));

        // This will timeout after 5 seconds if no data is available
        auto buffer = std::make_shared<std::string>();
        size_t bytes_read = serial.read(buffer);

    } catch (const libserial::TimeoutException& e) {
        std::cout << "Read operation timed out" << std::endl;
    } catch (const libserial::SerialException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
    }

    return 0;
}

Asynchronous Operations

For non-blocking operations:

#include <libserial/serial.hpp>

int main() {
    try {
        libserial::Serial serial;
        serial.open("/dev/ttyUSB0");

        auto buffer = std::make_shared<std::string>();

        // Check if data is available before reading
        if (serial.getAvailableData() > 0) {
            size_t bytes_read = serial.read(buffer);
            // Process data...
        }

    } catch (const libserial::SerialException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
    }

    return 0;
}

Error Handling

libserial uses exceptions for error handling. The main exception types are:

SerialException: Base exception class
PortNotFoundException: Port doesn’t exist or can’t be accessed
PermissionDeniedException: Insufficient permissions
TimeoutException: Operation timed out
IOException: Input/output error

try {
    // Serial operations...
} catch (const libserial::PortNotFoundException& e) {
    std::cerr << "Port not found: " << e.what() << std::endl;
} catch (const libserial::PermissionDeniedException& e) {
    std::cerr << "Permission denied: " << e.what() << std::endl;
} catch (const libserial::TimeoutException& e) {
    std::cerr << "Operation timed out: " << e.what() << std::endl;
} catch (const libserial::SerialException& e) {
    std::cerr << "Serial error: " << e.what() << std::endl;
}

Best Practices

Always use exception handling when working with serial ports
Close ports explicitly or use RAII patterns
Set appropriate timeouts to prevent blocking
Check data availability before reading in loops
Use appropriate buffer sizes for your application
Test with different baud rates to find optimal settings