Added doxygen comments

Peter M. Groen
1 parent 91724967
Showing 5 changed files with 150 additions and 107 deletions
CMakeLists.txt
src/ConnectionConfig.h
src/IModbusAdapter.h
src/ModbusAdapter.h
src/ModbusConnections.h
-cmake_minimum_required(VERSION 3.2)
+cmake_minimum_required(VERSION 3.10)
 project(modbus)
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
+/****************************************************************************
+ * Copyright (c) 2022 Priva b.v.
+ ****************************************************************************/
 #pragma once
 #include <string>
 #include <unordered_map>
 /*!
- * \brief The ConnectionPort enum
+ * \brief   The ConnectionPort enum.
+ *          CP_EXTERNAL - the first serial port
+ *          CP_IOBUS    - The second serial port through RJ45 connector
+ *          CP_TCP      - TCP Connections
  */
 enum class ConnectionPort : unsigned int
 {
@@ -14,7 +20,8 @@ enum class ConnectionPort : unsigned int
 };
 /*!
- * \brief The Parity enum
+ * \brief   The Parity enum.
+ *          Used in a serial port context
  */
 enum class Parity : unsigned int
 {
@@ -24,7 +31,8 @@ enum class Parity : unsigned int
 };
 /*!
- * \brief The ConnectionType enum
+ * \brief   The ConnectionType enum.
+ *          Added for convenience, to distinguish between types.
  */
 enum class ConnectionType : unsigned int
 {
@@ -33,17 +41,25 @@ enum class ConnectionType : unsigned int
     CT_UNKNOWN
 };
+/*!
+ * \brief The ConnectionConfig class holds all the information we need to establish a proper connection.
+ *        It can be created by a configuration object and passed on to the ModBus stack.
+ *        By using this class, all the connectioninfo is within its context for convenience.
+ *
+ *        Data can be accessed by their resp. getter-methods to avoid internal data-exposure
+ *        according to the basic principles of object oriented programming. ( Abstraction, Encapsulation, Inheritance, and Polymorphism )
+ */
 class ConnectionConfig
 {
 public:
     /*!
-     * \brief ConnectionConfig
-     * \param port
-     * \param baud
-     * \param parity
-     * \param dataBits
-     * \param stopBits
-     * \param timeOut
+     * \brief ConnectionConfig Constructor. Used to create a new serial connection.
+     * \param port      - The portname given by its enum.
+     * \param baud      - The port speed in a serial port context ( default = 115200 )
+     * \param parity    - The parity. ( Default : None, no parity )
+     * \param dataBits  - The number of databits. RTU uses 8 (0 - 255), ASCII uses 7 (0 - 127). Default is RTU
+     * \param stopBits  - The number of stopbits used to detect the end of the frame. ( Default = 1 )
+     * \param timeOut   - Timeout in .1 secs. See the termios documentation for deviations on this.
      */
     ConnectionConfig( ConnectionPort port, int baud = 115200, Parity parity = Parity::PAR_NONE, int dataBits = 8, int stopBits = 1, int timeOut = -1 )
         : m_port( port )
@@ -58,11 +74,11 @@ public:
     {}
     /*!
-     * \brief ConnectionConfig
-     * \param port
-     * \param ip
-     * \param portnum
-     * \param timeOut
+     * \brief ConnectionConfig Constructor. Used to create a new TCP connection.
+     * \param port      - The portname given by its enaum. ( Should be CP_TCP )
+     * \param ip        - The ip address of the ModBus device we want to connect to.
+     * \param portnum   - The portnumber the ModBus device is using
+     * \param timeOut   - Timeout in which a modbus device should respond.
      */
     ConnectionConfig( ConnectionPort port, const std::string &ip, int portnum, int timeOut = -1  )
         : m_port( port )
@@ -81,6 +97,7 @@ public:
     ConnectionPort getPortEnum() const { return m_port; }           ///< Get the portname Enum
     int getBaudRate() const { return m_baudRate; }                  ///< Get the given baudrate as int.
     char getParity() const { return m_parityMap.at(m_parity); }     ///< Get the translated parity.
+    Parity getParityEnum() const { return m_parity; }               ///< Get the parity Enum
     int getDataBits() const { return m_dataBits; }                  ///< Get the number of databits ( 7 for ASCII, 8 for RTU )
     int getStopBits() const { return m_stopBits; }                  ///< Get the number of stopBits. ( de-facto = 1 )
@@ -93,20 +110,21 @@ public:
 private:
     /// Serial connections
-    ConnectionPort  m_port;
-    int             m_baudRate;
-    Parity          m_parity;
-    int             m_dataBits;
-    int             m_stopBits;
+    ConnectionPort  m_port;                                         ///< Member variable holding the portName Enum
+    int             m_baudRate;                                     ///< Member variable holding the Serial port Baudrate
+    Parity          m_parity;                                       ///< Member variable holding the Serial port Parity
+    int             m_dataBits;                                     ///< Member variable holding the number of databits
+    int             m_stopBits;                                     ///< Member variable holding the number of stopbits
     /// TCP connections
-    std::string     m_ipaddress;
-    int             m_portnumber;
+    std::string     m_ipaddress;                                    ///< Member variable holding the ip-address of the TCP-connection
+    int             m_portnumber;                                   ///< Member variable holding the portnumber of the TCP-connection
     /// Generic
-    int             m_timeOut;
-    ConnectionType  m_conType;
+    int             m_timeOut;                                      ///< Member variable holding the timeOut value
+    ConnectionType  m_conType;                                      ///< Member variable holding the connection type.
+    /// Translation tables for portnames and parity.
     // ============================================================
     // == Change accordingly to the devicenames on your platform ==
     // ============================================================
@@ -15,58 +15,70 @@ using modbusData = std::vector&lt;std::variant&lt;uint8_t, uint16_t&gt;&gt;;
 class ConnectionConfig;
 /*!
- * \brief The IModbusAdapter class
+ * \brief   The IModbusAdapter class provides an abstract way of using
+ *          the modbus stack. Implemented as a pure virtual, it cannot be instantiated.
+ *          This represents a unique connection to either a serial bus or a TCP connection.
  */
 class IModbusAdapter
 {
 public:
-    virtual ~IModbusAdapter() {}
+    /// Default DTor.
+    virtual ~IModbusAdapter() = default;
+    /// Create a modbus connection, accepting a configuration object.
     virtual bool ModbusConnect( const ConnectionConfig &conncfg ) = 0;
     /*!
-     * \brief ModbusDisconnect
+     * \brief   ModbusDisconnect
+     *          Disconnect from the serial bus or the TCP connection, freeing its resources
      */
     virtual bool ModbusDisconnect() = 0;
     /*!
-     * \brief ModbusReadData
-     * \param slaveId
-     * \param startAddress
-     * \param noOfItems
+     * \brief Read data from a modbus device given by its parameters.
+     * \param   slaveId         - The Id of the ModbusDevice.
+     * \param   functionCode    - The code describing the action we want to perform on the device.
+     *                            Given by an enum, provided by the modbus-stack.
+     * \param   startAddress    - Startaddres of the register we want to read.
+     * \param   noOfItems       - The number of items we expect back.
+     * \returns modbusData      - A vector holding each register in an entry in the same order as they are received.
+     *                            Empty if no data was received.
      */
     virtual modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) = 0;
     /*!
-     * \brief ModbusReadHoldReg
-     * \param slaveId
-     * \param startAddress
-     * \param noOfItems
-     * \return
+     * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device.
+     * \param   slaveId         - The Id of the ModbusDevice.
+     * \param   startAddress    - Startaddres of the register we want to read.
+     * \param   noOfItems       - The number of items we expect back.
+     * \returns modbusData      - A vector holding each register in an entry in the same order as they are received.
+     *                            Empty if no data was received.
      */
     virtual modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) = 0;
     /*!
-     * \brief ModBusWriteData
-     * \param slaveId
-     * \param funtionCode
-     * \param startAddress
-     * \param noOfItems
-     * \param values
+     * \brief Write data to the device.
+     * \param slaveId           - The Id of the Modbus device
+     * \param funtionCode       - The code describing the action we want to perform on the device
+     *                            given by an enum, provided by the modbus-stack.
+     * \param startAddress      - Startaddres of the register we want to read.
+     * \param noOfItems         - The number of items we expect to be written
+     * \param values            - The values we want to write to the given device. Each vector-entry represents a single byte
+     *                            and they will be sent in sequence.
      */
     virtual void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vector<int>values ) = 0;
     /*!
-     * \brief isConnected
-     * \return
+     * \brief   Indicates if this connection is alive.
+     * \return  True if alive, false if not.
      */
     virtual bool isConnected() const = 0;
     /*!
-     * \brief ErrorString
-     * \param errnum
-     * \return
+     * \brief   returns the translated error code coming from the modbus stack.
+     * \param   errnum          - error Number coming from the stack.
+     * \return  The translated error as a string. Empty if not resolvable.
      */
     virtual std::string ErrorString( int errnum ) const = 0;
 };
@@ -21,63 +21,70 @@ class ModbusAdapter : public IModbusAdapter
 {
 public:
     /*!
-     * \brief ModbusAdapter
+     * \brief Default constructor
      */
     explicit ModbusAdapter();
     /*!
-     * \brief ~ModbusAdapter
+     * \brief Default destructor
      */
     virtual ~ModbusAdapter();
     /*!
-     * \brief ModbusConnect
-     * \param conncfg
+     * \brief /// Create a modbus connection, accepting a configuration object.
      */
     bool ModbusConnect( const ConnectionConfig &conncfg ) override;
     /*!
-     * \brief ModbusDisconnect
+     * \brief   ModbusDisconnect
+     *          Disconnect from the serial bus or the TCP connection, freeing its resources
      */
     bool ModbusDisconnect() override;
     /*!
-     * \brief ModbusReadData
-     * \param slaveId
-     * \param startAddress
-     * \param noOfItems
+     * \brief Read data from a modbus device given by its parameters.
+     * \param   slaveId         - The Id of the ModbusDevice.
+     * \param   functionCode    - The code describing the action we want to perform on the device.
+     *                            Given by an enum, provided by the modbus-stack.
+     * \param   startAddress    - Startaddres of the register we want to read.
+     * \param   noOfItems       - The number of items we expect back.
+     * \returns modbusData      - A vector holding each register in an entry in the same order as they are received.
+     *                            Empty if no data was received.
      */
     modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) override;
     /*!
-     * \brief ModbusReadHoldReg
-     * \param slaveId
-     * \param startAddress
-     * \param noOfItems
-     * \return
+     * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device.
+     * \param   slaveId         - The Id of the ModbusDevice.
+     * \param   startAddress    - Startaddres of the register we want to read.
+     * \param   noOfItems       - The number of items we expect back.
+     * \returns modbusData      - A vector holding each register in an entry in the same order as they are received.
+     *                            Empty if no data was received.
      */
     modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) override;
     /*!
-     * \brief ModBusWriteData
-     * \param slaveId
-     * \param funtionCode
-     * \param startAddress
-     * \param noOfItems
-     * \param values
+     * \brief Write data to the device.
+     * \param slaveId           - The Id of the Modbus device
+     * \param funtionCode       - The code describing the action we want to perform on the device
+     *                            given by an enum, provided by the modbus-stack.
+     * \param startAddress      - Startaddres of the register we want to read.
+     * \param noOfItems         - The number of items we expect to be written
+     * \param values            - The values we want to write to the given device. Each vector-entry represents a single byte
+     *                            and they will be sent in sequence.
      */
     void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vector<int>values ) override;
     /*!
-     * \brief isConnected
-     * \return
+     * \brief   Indicates if this connection is alive.
+     * \return  True if alive, false if not.
      */
     bool isConnected() const override;
     /*!
-     * \brief ErrorString
-     * \param errnum
-     * \return
+     * \brief   returns the translated error code coming from the modbus stack.
+     * \param   errnum          - error Number coming from the stack.
+     * \return  The translated error as a string. Empty if not resolvable.
      */
     std::string ErrorString( int errnum ) const override;
@@ -13,91 +13,97 @@
 #include <string>
 #include <unordered_map>
-///
+/// Easy replacement of template construction
 using AdapterList = std::vector<std::shared_ptr<IModbusAdapter>>;
 /*!
- * \brief The ModbusConnections class
+ * \brief The ModbusConnections class conatins a list of all modbus connections, Serial and TCP.
+ *        To access a specific connection, use its portname and / or endpoint to return it's interface.
  */
 class ModbusConnections
 {
 public:
     /*!
-     * \brief ModbusConnections
+     * \brief Default CTor
      */
     explicit ModbusConnections();
     /*!
-     * \brief ~ModbusConnections
+     * \brief Default DTor
      */
     virtual ~ModbusConnections();
     /*!
-     * \brief CreateConnection
-     * \param config
-     * \return
+     * \brief Create a modbus connection as described by the connection object.
+     * \param config    - The connection object describing the connection in detail.
+     * \return  The result of the creation.
+     *          True    = succesful.
+     *          False   = Failed.
      */
     bool CreateConnection( const ConnectionConfig &config );
     /*!
-     * \brief DeleteConnection
-     * \param portName
-     * \param endpoint
+     * \brief Remove the connection described by its portname and/or endpoint.
+     * \param portName  - The portname as its enum
+     * \param endpoint  - combination of ip-address and portname in endpoint-format
+     *                    ( tcp://<ip_address>:<portNumber> )
+     *                    ( i.e. tcp://127.0.0.1:501 )
      * \return
      */
     bool DeleteConnection( const ConnectionPort portName, const std::string &endpoint = std::string() );
     /*!
-     * \brief ConnectionCount
-     * \return
+     * \brief Give the number of registered serial and tcp-connections combined.
      */
     int ConnectionCount();
     /*!
-     * \brief getConnection
-     * \param portName
-     * \param endpoint
-     * \return
+     * \brief Get the connection give by its parameters.
+     * \param   portName    - The portname by its enum
+     * \param   endpoint    - combination of ip-address and portname in endpoint-format
+     *                          ( tcp://<ip_address>:<portNumber> )
+     *                          ( i.e. tcp://127.0.0.1:501 )
+     * \return  Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found.
      */
     std::shared_ptr<IModbusAdapter> getConnection( const ConnectionPort portName, const std::string &endpoint = std::string() );
     // Convenient functions
     /*!
-     * \brief getConnection
-     * \param portName
-     * \param ipAddress
-     * \param tcpPortNumber
-     * \return
+     * \brief Get the connection given by its parameters. If applicable, ipaddress and portnumber will be used to create the endpoint.
+     * \param   portName    - The portname by its enum
+     * \param   ipAddress   - The ipaddress of the TCP-connection
+     * \param   tcpPortNumber   - The portnumber of the TCP-connection
+     * \return  Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found.
      */
     std::shared_ptr<IModbusAdapter> getConnection( const ConnectionPort portName, const std::string &ipAddress, int tcpPortNumber );
     /*!
-     * \brief getConnections
-     * \return
+     * \brief Returns a list of all registered connections by their interfaces. This is a mix of Serial and TCP-connections.
      */
     AdapterList getConnections();
 private:
     /*!
-     * \brief connectionExist
-     * \param portName
-     * \param endpoint
-     * \return
+     * \brief Check if a connection already exist.
+     * \param portName  - The portName by its enum
+     * \param endpoint  - The endpoint this connection was registered with.
+     * \return  A valid pointer to the Interface if the connection exist. If the connection is unknown, it will return a nullptr.
+     *          shared_ptr can manifest themselves as booleans, so "!ptr" is sufficient to check.
      */
     std::shared_ptr<IModbusAdapter> connectionExist( const ConnectionPort portName, const std::string &endpoint = std::string() );
     /*!
-     * \brief createEndPoint
-     * \param ipAddress
-     * \param portNumber
-     * \return
+     * \brief Create the TCP endpoint based on the connections IP-address and portnumber
+     * \param ipAddress     - The ipAddress as string.
+     * \param portNumber    - The portnumber as integer.
+     * \return  The endpoint in format : tcp://<ip_address>:<portNumber> i.e. tcp://127.0.0.1:501
      */
     std::string createEndPoint( const std::string &ipAddress, int portNumber );
     /*!
-     * \brief createEndPoint
-     * \param config
-     * \return
+     * \brief Create the TCP endpoint based on the connections IP-address and portnumber extracted from the connection configuration.
+     * \param config - The configuration object used to create the connection.
+     * \return  The endpoint in format : tcp://<ip_address>:<portNumber> i.e. tcp://127.0.0.1:501
      */
     std::string createEndPoint( const ConnectionConfig &config );