Merge pull request #5 from NestorDP/feat-control-data

Feat control data

Author: NestorDP

CPPLINT.cfg

@@ -1,2 +1,2 @@
-filter=-build/include_order,-whitespace/line_length,-whitespace/access-members,-whitespace/indent,-whitespace/newline,-readability/braces
+filter=-build/include_order,-whitespace/line_length,-whitespace/access-members,-whitespace/indent,-whitespace/newline,-readability/braces, -runtime/string
 linelength=120

examples/list_ports.cpp

@@ -3,7 +3,10 @@
 // Example: list serial ports using Ports class
 
 #include <iostream>
+#include <vector>
+
 #include "libserial/ports.hpp"
+#include "libserial/device.hpp"
 
 int main() {
     libserial::Ports ports;
@@ -18,6 +21,16 @@ int main() {
         auto bus_path = ports.findBusPath(i);
         std::cout << "  [" << i << "] " << name.value_or("unknown") << " -> " << port_path.value_or("unknown") << " (bus: " << bus_path.value_or("unknown") << ")\n";
     }
+    std::vector<libserial::Device> devices;
+    ports.getDevices(devices);
+
+    std::cout << "\nRetrieving device list via getDevices() method:\n";
+    for (const auto& device : devices) {
+        std::cout << "Device Name: " << device.getName() << "\n";
+        std::cout << "Port Path: " << device.getPortPath() << "\n";
+        std::cout << "Bus Path: " << device.getBusPath() << "\n";
+        std::cout << "Device ID: " << device.getId() << "\n";
+    }
 
     return 0;
 }

include/libserial/device.hpp

@@ -0,0 +1,125 @@
+//  @ Copyright 2022-2025 Nestor Neto
+
+#ifndef INCLUDE_LIBSERIAL_DEVICE_HPP_
+#define INCLUDE_LIBSERIAL_DEVICE_HPP_
+
+#include <string>
+#include <cstdint>
+
+namespace libserial {
+
+/**
+ * @brief A class representing a serial device
+ *
+ * The Device class encapsulates the properties of a serial device,
+ * including its name, port path, bus path, and unique identifier.
+ *
+ * @author Nestor Pereira Neto
+ */
+class Device {
+public:
+/**
+ * @brief Default constructor of the Device class
+ *
+ */
+Device() = default;
+
+/**
+ * @brief Default destructor of the Device class
+ *
+ */
+~Device() = default;
+
+/**
+ * @brief Parameterized constructor of the Device class
+ *
+ * @param name The name of the device
+ * @param port_path The port path of the device
+ * @param bus_path The bus path of the device
+ * @param id The unique identifier of the device
+ */
+Device(const std::string& name,
+       const std::string& port_path,
+       const std::string& bus_path,
+       uint16_t id);
+
+/**
+ * @brief Retrieves the name of the device
+ *
+ * @return std::string The name of the device
+ */
+std::string getName() const;
+
+/**
+ * @brief Retrieves the port path of the device
+ *
+ * @return std::string The port path of the device
+ */
+std::string getPortPath() const;
+
+/**
+ * @brief Retrieves the bus path of the device
+ *
+ * @return std::string The bus path of the device
+ */
+std::string getBusPath() const;
+
+/**
+ * @brief Retrieves the unique identifier of the device
+ *
+ * @return uint16_t The unique identifier of the device
+ */
+uint16_t getId() const;
+
+/**
+ * @brief Sets the name of the device
+ *
+ * @param name The name to set
+ */
+void setName(const std::string& name);
+
+/**
+ * @brief Sets the port path of the device
+ *
+ * @param port_path The port path to set
+ */
+void setPortPath(const std::string& port_path);
+
+/**
+ * @brief Sets the bus path of the device
+ *
+ * @param bus_path The bus path to set
+ */
+void setBusPath(const std::string& bus_path);
+
+/**
+ * @brief Sets the unique identifier of the device
+ *
+ * @param id The unique identifier to set
+ */
+void setId(uint16_t id);
+
+private:
+/**
+ * @brief The name of the device
+ */
+std::string name_{"unknown"};
+
+/**
+ * @brief The port path of the device
+ */
+std::string port_path_{"unknown"};
+
+/**
+ * @brief The bus path of the device
+ */
+std::string bus_path_{"unknown"};
+
+/**
+ * @brief The unique identifier of the device
+ */
+uint16_t id_{0};
+};
+}  // namespace libserial
+
+#endif  // INCLUDE_LIBSERIAL_DEVICE_HPP_

include/libserial/ports.hpp

@@ -17,6 +17,7 @@
 #include <algorithm>
 #include <optional>
 
+#include "libserial/device.hpp"
 #include "libserial/serial_exception.hpp"
 #include "libserial/serial_types.hpp"
 
@@ -49,22 +50,27 @@ Ports() = default;
  * @brief Scans the system for available serial ports
  *
  * @return uint16_t The number of serial ports found
+ * @throws SerialException if scanning fails
+ * @throws SerialException if no ports are found
+ * @throws PermissionDeniedException if insufficient permissions
  */
 uint16_t scanPorts();
 
 /**
  * @brief Retrieves the list of detected serial devices
  *
- * @param list A reference to a vector that will be populated with
- *             DeviceStruct entries for each detected device
+ * @param devices A reference to a vector that will be populated with
+ *             Device entries for each detected device
+ * @throws SerialException if device list cannot be retrieved
  */
-void getDeviceList(std::vector<DeviceStruct> & list) const;
+void getDevices(std::vector<Device> & devices) const;
 
 /**
  * @brief Finds the port path for a device with the specified ID
  *
  * @param id The unique identifier of the device to search for
  * @return std::optional<std::string> The port path if found, or std::nullopt if not found
+ * @throws SerialException if search operation fails
  */
 std::optional<std::string> findPortPath(uint16_t id) const;
 
@@ -73,6 +79,7 @@ std::optional<std::string> findPortPath(uint16_t id) const;
  *
  * @param id The unique identifier of the device to search for
  * @return std::optional<std::string> The bus path if found, or std::nullopt if not found
+ * @throws SerialException if search operation fails
  */
 std::optional<std::string> findBusPath(uint16_t id) const;
 
@@ -81,6 +88,7 @@ std::optional<std::string> findBusPath(uint16_t id) const;
  *
  * @param id The unique identifier of the device to search for
  * @return std::optional<std::string> The name if found, or std::nullopt if not found
+ * @throws SerialException if search operation fails
  */
 std::optional<std::string> findName(uint16_t id) const;
 
@@ -93,7 +101,7 @@ static constexpr const char* kSysSerialByIdPath = "/dev/serial/by-id/";
 /**
  * @brief Internal list of detected serial devices
  */
-std::vector<DeviceStruct> device_list_;
+std::vector<Device> devices_;
 };
 }  // namespace libserial
 

include/libserial/serial.hpp

@@ -196,6 +196,7 @@ int getAvailableData() const;
  * timing out. A value of 0 means no timeout (blocking).
  *
  * @param timeout Timeout in milliseconds
+ * @throws SerialException if setting cannot be applied
  */
 void setReadTimeout(unsigned int timeout);
 
@@ -206,14 +207,87 @@ void setReadTimeout(unsigned int timeout);
  * timing out. A value of 0 means no timeout (blocking).
  *
  * @param timeout Timeout in milliseconds
+ * @throws SerialException if setting cannot be applied
  */
 void setWriteTimeout(unsigned int timeout);
 
-// Future planned methods (not yet implemented):
-// void setNumberBits(NumBits num_bits);
-// void setParity(Parity parity);
-// void setStopBits(StopBits stop_bits);
+/**
+ * @brief Sets the number of data bits per byte
+ *
+ * Configures the number of data bits used in each byte of serial
+ * communication.
+ *
+ * @param nbits The desired number of data bits (5, 6, 7, or 8)
+ * @throws SerialException if number of bits cannot be set
+ */
+void setDataLength(DataLength nbits);
+
+/**
+ * @brief Sets the parity configuration
+ *
+ * Configures the parity checking mechanism for serial communication.
+ *
+ * @param parity The desired parity setting (ENABLE or DISABLE)
+ * @throws SerialException if parity cannot be set
+ */
+void setParity([[maybe_unused]] Parity parity);
+
+/**
+ * @brief Sets the stop bits configuration
+ *
+ * Configures the number of stop bits used in serial communication.
+ *
+ * @param stop_bits The desired stop bits setting (ONE, ONE_AND_HALF, or TWO)
+ * @throws SerialException if stop bits cannot be set
+ */
+void setStopBits([[maybe_unused]] StopBits stop_bits);
+
+/**
+ * @brief Sets the flow control configuration
+ *
+ * Configures the flow control mechanism for serial communication.
+ *
+ * @param flow_control The desired flow control setting (HARDWARE or SOFTWARE)
+ * @throws SerialException if flow control cannot be set
+ */
+void setFlowControl([[maybe_unused]] FlowControl flow_control);
+
+/**
+ * @brief Sets canonical mode for input processing
+ *
+ * Configures whether the input is processed in canonical (line-based)
+ * mode or non-canonical (raw) mode.
+ *
+ * @param canonical_mode The desired canonical mode setting (ENABLE or DISABLE)
+ * @throws SerialException if canonical mode cannot be set
+ */
+void setCanonicalMode([[maybe_unused]] CanonicalMode canonical_mode);
+
+/**
+ * @brief Sets the terminator character for readUntil operations
+ *
+ * Configures the character that signals the end of a readUntil operation.
+ *
+ * @param term The desired terminator character
+ * @throws SerialException if terminator cannot be set
+ */
+void setTerminator([[maybe_unused]] Terminator term);
 
+/**
+ * @brief Sets the read timeout in deciseconds
+ *
+ * @param time Timeout in deciseconds
+ * @throws SerialException if setting cannot be applied
+ */
+void setTimeOut([[maybe_unused]] int time);
+
+/**
+ * @brief Sets the minimum number of characters to read
+ *
+ * @param num Minimum number of characters to read
+ * @throws SerialException if setting cannot be applied
+ */
+void setMinNumberCharRead([[maybe_unused]] int num);
 
 private:
 /**

include/libserial/serial_types.hpp

@@ -7,13 +7,6 @@
 
 namespace libserial {
 
-struct DeviceStruct {
-  std::string name;
-  std::string port_path;
-  std::string bus_path;
-  uint16_t id;
-};
-
 /**
  * @enum Parity
  * @brief Enumeration for serial port parity configuration
@@ -38,12 +31,10 @@ enum class Parity {
  * serial communication. Common configurations include 1 stop bit (standard)
  * or 2 stop bits (for slower or noisy communication).
  *
- * @note This enum currently provides basic enable/disable functionality.
- *       Future versions may include specific stop bit counts (ONE, TWO).
  */
 enum class StopBits {
-  ENABLE,   ///< Enable stop bits configuration
-  DISABLE,  ///< Disable stop bits configuration
+  ONE,   ///< One stop bit
+  TWO,   ///< Two stop bits
 };
 
 /**
@@ -84,6 +75,7 @@ enum class CanonicalMode {
 enum class Terminator {
   EOT = 4,   ///< End of Transmission (ASCII 4, Ctrl+D)
   CR  = 13,  ///< Carriage Return (ASCII 13, '\r')
+  LF  = 10   ///< Line Feed (ASCII 10, '\n')
 };
 
 /**
@@ -130,6 +122,22 @@ enum class BaudRate {
   BAUD_RATE_230400 = 230400   ///< 230400 bps - Very high speed applications
 };
 
+/**
+ * @enum DataLength
+ * @brief Enumeration for serial port data bits configuration
+ *
+ * Data bits define the number of bits used to represent each byte of data
+ * in serial communication. Common configurations include 5, 6, 7, or 8 data
+ * bits per byte. The choice of data bits affects the range of values that
+ * can be transmitted and may need to match between communicating devices.
+ */
+enum class DataLength {
+  FIVE = 5,   ///< 5 data bits per byte
+  SIX  = 6,   ///< 6 data bits per byte
+  SEVEN = 7,  ///< 7 data bits per byte
+  EIGHT = 8   ///< 8 data bits per byte
+};
+
 }  // namespace libserial
 
 #endif  // INCLUDE_LIBSERIAL_SERIAL_TYPES_HPP_